GitPython

https://gitpython.readthedocs.io/en/stable/
Admin
GitPython is a Python library used to interact with Git repositories, providing an object-oriented...
Tokens:100,109
Snippets:1,040
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install GitPython from setup.py

Source: https://gitpython.readthedocs.io/en/stable/intro.html

Alternative installation method using the setup.py script from the distribution. Note that GitDB must be installed manually in this case; using the git source repository is recommended.

```bash
# python setup.py install

```

--------------------------------

### multi_options example for clone()

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Example list of git-clone options passed to the multi_options parameter of clone() or clone_from(). Each item is passed exactly as specified to git clone.

```python
[
    "--config core.filemode=false",
    "--config core.ignorecase",
    "--recurse-submodule=repo1_path",
    "--recurse-submodule=repo2_path",
]
```

--------------------------------

### Install GitPython with pip

Source: https://gitpython.readthedocs.io/en/stable/intro.html

Installs the latest GitPython version from the Python Package Index using pip. Requires pip to be installed on the system.

```bash
# pip install GitPython

```

--------------------------------

### FetchInfo usage example

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Shows how to access attributes of a FetchInfo object returned from remote.fetch(). The example demonstrates accessing ref, flags, note, old_commit, and remote_ref_path.

```python
info = remote.fetch()[0]
info.ref           # Symbolic Reference or RemoteReference to the changed
                   # remote head or FETCH_HEAD
info.flags         # additional flags to be & with enumeration members,
                   # i.e. info.flags & info.REJECTED
                   # is 0 if ref is SymbolicReference
info.note          # additional notes given by git-fetch intended for the user
info.old_commit    # if info.flags & info.FORCED_UPDATE|info.FAST_FORWARD,
                   # field is set to the previous location of ref, otherwise None
info.remote_ref_path # The path from which we fetched on the remote. It's the remote's version of our info.ref
```

--------------------------------

### Using Head class to access repository heads

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Example from the Head class documentation showing how to access a repository's heads and their commit information.

```python
>>> repo = Repo("/path/to/repo")
>>> head = repo.heads[0]

>>> head.name
'master'

>>> head.commit
<git.Commit "1c09f116cbc2cb4100fb6935bb162daa4723f455">

>>> head.commit.hexsha
'1c09f116cbc2cb4100fb6935bb162daa4723f455'
```

--------------------------------

### Get tree object for a revision

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Use repo.tree() to obtain the Tree object for a given tree-ish revision. The example passes repo.heads[0] to get the tree of the current branch head.

```python
repo.tree(repo.heads[0])
```

--------------------------------

### Initialize a bare repository with Repo.init

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Initializes a new bare repository using Repo.init with bare=True. The example uses os.path.join(rw_dir, "bare-repo") as the path and asserts the resulting repo is bare.

```python
bare_repo = Repo.init(os.path.join(rw_dir, "bare-repo"), bare=True)
assert bare_repo.bare
```

--------------------------------

### Obtain commits at specified revision

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Use repo.commit() with a revision string to get a specific commit. Examples include branch names, tags, and HEAD~10.

```python
repo.commit("master")
repo.commit("v0.8.1")
repo.commit("HEAD~10")

```

--------------------------------

### Iterate commits with max_count and skip

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Use repo.iter_commits() to iterate commits. max_count limits the number, skip allows paging. The example shows getting the first 50 and then commits 21-30.

```python
fifty_first_commits = list(repo.iter_commits("master", max_count=50))
assert len(fifty_first_commits) == 50
# This will return commits 21-30 from the commit list as traversed backwards master.
ten_commits_past_twenty = list(repo.iter_commits("master", max_count=10, skip=20))
assert len(ten_commits_past_twenty) == 10
assert fifty_first_commits[20:30] == ten_commits_past_twenty

```

--------------------------------

### Initialize a repository and commit an empty file

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Creates a new repository at the given path, adds an empty file to the index, and commits it. The example uses git.Repo.init, r.index.add, and r.index.commit. Individual methods support many customization arguments.

```python
import git

repo_dir = os.path.join(rw_dir, "my-new-repo")
file_name = os.path.join(repo_dir, "new-file")

r = git.Repo.init(repo_dir)
# This function just creates an empty file.
open(file_name, "wb").close()
r.index.add([file_name])
r.index.commit("initial commit")

```

--------------------------------

### Clone and initialize repositories

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Clones an existing repository to a new path and initializes a new empty repository. Both operations return Repo instances, as asserted.

```python
cloned_repo = repo.clone(os.path.join(rw_dir, "to/this/path"))
assert cloned_repo.__class__ is Repo  # Clone an existing repository.
assert Repo.init(os.path.join(rw_dir, "path/for/new/repo")).__class__ is Repo
```

--------------------------------

### Initialize a new git Repo with Repo.init

Source: https://gitpython.readthedocs.io/en/stable/quickstart.html

Creates a new Git repository at the given path using Repo.init(). The commented command shows the equivalent shell command.

```python
# $ git init <path/to/dir>

from git import Repo

repo = Repo.init(path_to_dir)
```

--------------------------------

### Create Repo instances with different path formats

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Shows how to instantiate a Repo object using various path formats: absolute, .git directory, tilde expansion, environment variable, and raw string. The constructor accepts a path to the worktree or .git directory.

```python
repo = Repo("/Users/mtrier/Development/git-python")
repo = Repo("/Users/mtrier/Development/git-python.git")
repo = Repo("~/Development/git-python.git")
repo = Repo("$REPOSITORIES/Development/git-python.git")
repo = Repo(R"C:\Users\mtrier\Development\git-python\.git")
```

--------------------------------

### PushInfo usage example

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Shows how to access attributes of a PushInfo object returned from remote.push(). The example demonstrates accessing flags, local_ref, remote_ref_string, remote_ref, old_commit, and summary.

```python
info = remote.push()[0]
info.flags          # bitflags providing more information about the result
info.local_ref      # Reference pointing to the local reference that was pushed
                    # It is None if the ref was deleted.
info.remote_ref_string # path to the remote reference located on the remote side
info.remote_ref # Remote Reference on the local side corresponding to
                # the remote_ref_string. It can be a TagReference as well.
info.old_commit # commit at which the remote_ref was standing before we pushed
                # it to local_ref.commit. Will be None if an error was indicated
info.summary    # summary line providing human readable english text about the push
```

--------------------------------

### Repo.init

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Initializes a git repository at the given path if specified. Returns the newly created Repo object.

```APIDOC
## Repo.init

### Description
Initializes a git repository at the given path if specified.

### Method
classmethod

### Endpoint
Repo.init(path, mkdir=True, odbt=GitCmdObjectDB, expand_vars=True, allow_unsafe_options=False, **kwargs)

### Parameters
- **path** (str or os.PathLike or None) - Optional - The full path to the repo (traditionally ends with `/<name>.git`). Or `None`, in which case the repository will be created in the current working directory.
- **mkdir** (bool) - Optional - If specified, will create the repository directory if it doesn't already exist. Creates the directory with a mode=0755. Only effective if a path is explicitly given.
- **odbt** (type) - Optional - Object DataBase type - a type which is constructed by providing the directory containing the database objects, i.e. `.git/objects`. It will be used to access all object data. The pure-Python `GitDB` backend is deprecated; use the default `GitCmdObjectDB` instead.
- **expand_vars** (bool) - Optional - If specified, environment variables will not be escaped. This can lead to information disclosure, allowing attackers to access the contents of environment variables.
- **allow_unsafe_options** (bool) - Optional - Allow unsafe options to be used, such as `--template` and `--separate-git-dir`.
- **kwargs** (Any) - Optional - Keyword arguments serving as additional options to the _git-init(1)_ command.

### Returns
`Repo` (the newly created repo)
```

--------------------------------

### Get any commit tree

Source: https://gitpython.readthedocs.io/en/stable/quickstart.html

Iterate over all commits in the repository and access their trees.

```python
prev_commits = list(repo.iter_commits(all=True))
```

--------------------------------

### Git.__init__

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Initializes a Git instance with an optional working directory.

```APIDOC
## Git.__init__

### Description
Initialize this instance with a working directory.

### Method
Constructor

### Parameters
#### Parameters
- **working_dir** (None | str | PathLike[str]) - Optional - Git directory we should work in. If `None`, we always work in the current directory as returned by `os.getcwd()`. This is meant to be the working tree directory if available, or the `.git` directory in case of bare repositories.

### Returns
None
```

--------------------------------

### Basic Git class usage

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Shows how to instantiate the Git class and call methods that invoke the git binary, such as init() and ls_files().

```python
g = Git( git_dir )
g.init()                   # calls 'git init' program
rval = g.ls_files()        # calls 'git ls-files' program
```

--------------------------------

### Run GitPython unit tests

Source: https://gitpython.readthedocs.io/en/stable/intro.html

Runs the unit tests to verify the GitPython installation.

```bash
$ python -m unittest

```

--------------------------------

### Get the latest commit tree

Source: https://gitpython.readthedocs.io/en/stable/quickstart.html

Access the tree object of the latest commit on the current branch.

```python
tree = repo.head.commit.tree
```

--------------------------------

### Handle remotes with progress reporting

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Shows how to create a remote, fetch with a progress delegate, and create a local branch from a remote branch. Also demonstrates deleting a remote.

```python
from git import RemoteProgress

class MyProgressPrinter(RemoteProgress):
    def update(self, op_code, cur_count, max_count=None, message=""):
        print(
            op_code,
            cur_count,
            max_count,
            cur_count / (max_count or 100.0),
            message or "NO MESSAGE",
        )

self.assertEqual(len(cloned_repo.remotes), 1)  # We have been cloned, so should be one remote.
self.assertEqual(len(bare_repo.remotes), 0)  # This one was just initialized.
origin = bare_repo.create_remote("origin", url=cloned_repo.working_tree_dir)
assert origin.exists()
for fetch_info in origin.fetch(progress=MyProgressPrinter()):
    print("Updated %s to %s" % (fetch_info.ref, fetch_info.commit))
# Create a local branch at one of the remote's branches.
remote_branch = next(ref for ref in origin.refs if ref.remote_head != "HEAD")
bare_branch = bare_repo.create_head(remote_branch.remote_head, remote_branch)
bare_repo.head.set_reference(bare_branch)
assert not bare_repo.delete_remote(origin).exists()
# push and pull behave very similarly.
```

--------------------------------

### Repo.__init__

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Initializes a Repo object representing a git repository.

```APIDOC
## [CONSTRUCTOR] Repo.__init__

### Description
Initializes a Repo object representing a git repository.

### Method
CONSTRUCTOR

### Endpoint
Repo.__init__

### Parameters
#### Path Parameters
- **path** (str | os.PathLike | None) - Optional - Path to the repository. If None, uses the current directory.
- **odbt** (Type[LooseObjectDB | GitDB]) - Optional - Object database type. Defaults to GitCmdObjectDB.
- **search_parent_directories** (bool) - Optional - If True, searches parent directories for the repository.
- **expand_vars** (bool) - Optional - If True, expands environment variables in the path.

### Response
#### Success Response (None)
- **None** - No return value.
```

--------------------------------

### get_values(section, option, default=None)

Source: https://gitpython.readthedocs.io/en/stable/reference.html

Get an option's values. If multiple values are specified for this option in the section, all are returned.

```APIDOC
## get_values(section, option, default=None)

### Description
Get an option's values. If multiple values are specified for this option in the section, all are returned.

### Parameters
- **section** (str) - Required - The section name
- **option** (str) - Required - The option name
- **default** (int | float | str | bool | None) - Optional - If not `None`, a list containing the given default value will be returned in case the option did not exist.

### Returns
A list of properly typed values, either int, float, string or bool

### Raises
- **TypeError** – In case the value could not be understood. Otherwise the exceptions known to the ConfigParser will be raised.
```

--------------------------------

### Clone repository and examine heads

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Clones a repository and demonstrates how to access and rename heads. The example uses a small repository URL and a temporary directory. Heads can be accessed by name for convenience, and the commit pointed to by a head is available via the commit attribute.

```python
import git

repo = git.Repo.clone_from(self._small_repo_url(), os.path.join(rw_dir, "repo"), branch="master")

heads = repo.heads
master = heads.master  # Lists can be accessed by name for convenience.
master.commit  # the commit pointed to by head called master.
master.rename("new_name")  # Rename heads.
master.rename("master")

```

--------------------------------

### Get and set daemon_export property

Source: https://gitpython.readthedocs.io/en/stable/_sources/changes.rst.txt

Shows how to read and set the daemon_export property of a Repo object. The property is now a property of Repo.

```python
>>> exported = repo.daemon_export
>>> repo.daemon_export = True
```

--------------------------------

### Select GitCmdObjectDB explicitly

Source: https://gitpython.readthedocs.io/en/stable/tutorial.html

Shows how to create a Repo with the default GitCmdObjectDB backend, either implicitly or explicitly via the odbt parameter.

```python
repo = Repo("path/to/repo")
# Equivalent explicit selection:
repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
```
Tokens:
Raw