# Python : GitPython
## API
```python
from git import Repo
repo = Repo( . )
# remote cheatsheet
repo.remotes iter: Remote
repo.remotes.origin Remote "origin"
repo.remotes.origin.refs iter: RemoteReference
repo.remotes.origin.refs.HEAD RemoteReference "refs/remotes/origin/HEAD"
repo.remotes.origin.refs.HEAD.commit Commit "9508622..."
repo.remotes.origin.refs.HEAD.remote_head "HEAD"
repo.remotes.origin.refs.HEAD.ref RemoteReference "refs/remotes/origin/main"
repo.remotes.origin.refs.HEAD.ref.commit Commit "9508622..."
repo.remotes.origin.refs.HEAD.ref.remote_head "main"
```
#### Repo
```python
Repo( "PATH" ) Repo
Repo.clone_from( "URL", "PATH", **kwargs ) Repo # URL: "https://github.com/NAMESPACE/REPO.git"
kwargs forwarded to `git clone` # URL: "
[email protected]:NAMESPACE/REPO.git"
depth=1, branch="..." <-- to clone a specific tag for building
Repo.init( "PATH" ) Repo
repo.active_branch Head # <git.Head "refs/heads/main">
repo.branches iter: Head
repo.commit( "SHA" ) Commit
repo.create_head( "NAME", commit="HEAD" ) Head
repo.create_tag( "NAME", ref ="HEAD" ) TagReference
repo.git Git
repo.head HEAD # <git.HEAD "HEAD">
repo.head.ref Head # <git.Head "refs/heads/main">
repo.heads iter: Head # [ <git.Head "refs/heads/main"> ]
repo.heads.NAME
repo.index IndexFile
repo.iter_commits() iter: Commit
repo.iter_commits( "rev" -or- "revA..revB" )
repo.refs iter: Head | RemoteReference | TagReference
# [ <git.Head "refs/heads/main">,
# <git.RemoteReference "refs/remotes/origin/HEAD">,
# <git.RemoteReference "refs/remotes/origin/main">,
# <git.TagReference "refs/tags/foo">,
# <git.TagReference "refs/tags/v1">, ... ]
repo.remote( "REMOTE" ) Remote
repo.remotes iter: Remote # [ <git.Remote "origin"> ]
repo.remotes.NAME
repo.remotes.origin Remote
repo.remotes.origin.refs # [ <git.RemoteReference "refs/remotes/origin/HEAD">,
# <git.RemoteReference "refs/remotes/origin/main"> ]
repo.tag( "TAG" ) TagReference
repo.tags iter: TagReference
# [ <git.TagReference "refs/tags/foo">, <git.TagReference "refs/tags/v1">, ... ]
repo.untracked_files [ "PATH1", ... ]
```
```python
repo.remotes # iter: Remote
repo.remotes.origin # Remote "origin"
repo.remotes.origin.refs # iter: RemoteReference
repo.remotes.origin.refs.HEAD # RemoteReference "refs/remotes/origin/HEAD"
repo.remotes.origin.refs.HEAD.commit # Commit "9508622..."
repo.remotes.origin.refs.HEAD.remote_head # "HEAD"
repo.remotes.origin.refs.HEAD.ref # RemoteReference "refs/remotes/origin/main"
repo.head.ref.tracking_branch() # RemoteReference "refs/remotes/origin/main"
repo.remotes.origin.refs.HEAD.ref.commit # Commit "9508622..."
repo.remotes.origin.refs.HEAD.ref.remote_head # "main"
```
#### Object
```python
obj.hexsha
obj.size
obj.type
```
#### IndexObject
```python
obj.abspath
obj.mode
obj.name
obj.path
+ Object
```
#### Blob
```python
blob.mime_type
+ Object + IndexObject
```
#### Commit
```python
Commit.iter_items() iter: Commit
commit.author
commit.authored_datetime datetime.datetime
commit.committed_datetime datetime.datetime
commit.committer
commit.message
commit.parents [ Commit ]
commit.stats Stats
commit.summary
commit.tree
+ Object + IndexObject
```
#### Tree
```python
tree.blobs [ Blob ]
tree.list_traverse( ... ) iter: Blob | Tree
tree.traverse( ... ) iter: Blob | Tree
+ Object + IndexObject
```
#### IndexFile
```python
index.add( [ "PATH1", ... ] )
index.commit( "MESSAGE" ) Commit
index.diff( None ) DiffIndex # compare staging to working
index.move( ... )
index.remove( ... )
index.reset( ... )
```
#### DiffIndex
```python
[ git.diff.Diff ]
diff_index.change_type
A = Added
D = Deleted
R = Renamed
M = Modified
T = Changed in the type
```
#### Diff
```python
diff.a_path
diff.b_path
```
#### SymbolicReference
```python
SymbolicReference.iter_items()
ref.abspath
ref.commit Commit
ref.is_remote()
ref.name
ref.object Blob | Commit | TagObject | Tree
ref.path
ref.rename( ... )
ref.set_commit( ... )
```
#### Reference
```python
ref.remote_head
+ SymbolicReference
```
#### HEAD
```python
head.orig_head() SymbolicReference
head.reset( ... )
+ SymbolicReference
```
#### Head
```python
head.checkout()
head.set_tracking_branch( remote_ref )
head.tracking_branch() RemoteReference
+ Reference + SymbolicReference
```
#### TagReference
```
+ Reference + SymbolicReference
```
#### RemoteReference
```python
RemoteReference.iter_items()
+ Head + Reference + SymbolicReference
```
#### Remote
```python
Remote.add( ... )
Remote.iter_items()
Remote.remove( ... )
remote.fetch( **kwargs )
remote.pull()
remote.push()
remote.push( "TAG" )
remote.refs iter: RemoteReference
remote.url
```
## Classes
#### Descriptions
```python
Cmd := Manages communication with the Git binary.
Object := Base class for object types. (Blob, Commit, Tree, TagObject)
IndexObject := Base for all objects that can be part of the index file. (Blob)
Blob := A Blob encapsulates a git blob object.
Commit := Wraps a git commit object.
Tree := Tree objects represent an ordered list of Blobs and other Trees.
IndexFile := An Index that can be manipulated using a native implementation
in order to save git command function calls wherever possible.
Diff := A Diff contains diff information between two Trees.
DiffIndex := Copntains a list of diffs.
SymbolicReference := Points to another Head, which itself specifies a commit.
Reference := A named reference to any object.
HEAD := Represents the repository’s HEAD reference.
Head := A named reference to a Commit.
RemoteReference := A reference pointing to a remote head.
TagReference := Provides a Reference-based type for lightweight tags.
Remote := Provides easy read and write access to a git remote.
Repo := Wraps local .git folder. Allows you to query references, create commit info,
generate diffs, create and clone repositories, and query the log.
Stats := Represents stat information as presented by git at the end of a merge.
It is created from the output of a diff operation.
```
#### Structure
```python
git.cmd. Git
git.objects.base. Object
git.objects.base. IndexObject < Object
git.objects.blob. Blob < IndexObject < Object
git.objects.commit. Commit < Object
git.objects.tree. Tree < IndexObject < Object
git.index.base. IndexFile
git.diff. Diff
git.diff. DiffIndex
git.refs.symbolic. SymbolicReference
git.refs.reference. Reference < SymbolicReference
git.refs.head. HEAD < SymbolicReference
git.refs.head. Head < Reference < SymbolicReference
git.refs.tag. TagReference < Reference < SymbolicReference
git.refs.remote. RemoteReference < Head < Reference < SymbolicReference
git.remote. Remote
git.repo.base. Repo
git.util. Stats
```
## Example Repos
#### Initial
```
HEAD ref: refs/heads/main
packed-refs 949486cd504c09b1a7cc0571200829dcbb52bc74 refs/remotes/origin/main
refs/
├── heads
│ └── main a430a14c6a7767089d500f9f7fce717b1abacbb9 -> 66fae088f728cfd53ab22e7654be3775d0954f1d
├── remotes
│ └── origin
│ ├── HEAD ref: refs/remotes/origin/main
│ └── main a430a14c6a7767089d500f9f7fce717b1abacbb9 -> 66fae088f728cfd53ab22e7654be3775d0954f1d
└── tags
├── foo 398bfa07f376e582907ea3323d63a9c48d19a3fc
├── v1 a8039a10e20a8f815be552fe2ca07119f0d602d9
└── v2 a430a14c6a7767089d500f9f7fce717b1abacbb9
```
#### Cloning with Packed Refs
```
HEAD ref: refs/heads/main
packed-refs a430a14c6a7767089d500f9f7fce717b1abacbb9 refs/remotes/origin/main
a8039a10e20a8f815be552fe2ca07119f0d602d9 refs/tags/v1
a430a14c6a7767089d500f9f7fce717b1abacbb9 refs/tags/v2
refs/
├── heads
│ └── main a430a14c6a7767089d500f9f7fce717b1abacbb9
├── remotes
│ └── origin
│ ├── HEAD ref: refs/remotes/origin/main
│ └── main 66fae088f728cfd53ab22e7654be3775d0954f1d
└── tags
```