Top-Level

git.__version__

Current GitPython version.

git.refresh(path:str|os.PathLike[str]|None=None)→None

Convenience method for setting the git executable path.

Parameters:

path – Optional path to the Git executable. If not absolute, it is resolvedimmediately, relative to the current directory.

Note:

Thepath parameter is usually omitted and cannot be used to specify a customcommand whose location is looked up in a path search on each call. SeeGit.refresh for details on how to achieve this.

Note:

This callsGit.refresh and sets other globalconfiguration according to the effect of doing so. As such, this function shouldusually be used instead of usingGit.refresh orFetchInfo.refresh directly.

Note:

This function is called automatically, with no arguments, at import time.

Objects.Base

classgit.objects.base.IndexObject(repo:Repo,binsha:bytes,mode:None|int=None,path:None|str|os.PathLike[str]=None)

Base for all objects that can be part of the index file.

The classes representing git object types that can be part of the index file areBlob. In addition,Submodule, which is not really a git objecttype but can be part of an index file, is also a subclass.

__annotations__={}

__hash__()→int

Returns:

Hash of our path as index items are uniquely identifiable by path, not bytheir data!

__init__(repo:Repo,binsha:bytes,mode:None|int=None,path:None|str|os.PathLike[str]=None)→None

Initialize a newly instancedIndexObject.

Parameters:

• repo – TheRepo we are located in.

• binsha – 20 byte sha1.

• mode – The stat-compatible file mode asint.Use thestat module to evaluate the information.

• path – The path to the file in the file system, relative to the git repositoryroot, likefile.ext orfolder/other.ext.

Note:

Path may not be set if the index object has been created directly, as itcannot be retrieved without knowing the parent tree.

__module__='git.objects.base'

__slots__=('path','mode')

propertyabspath:str|os.PathLike[str]

Returns:

Absolute path to this index object in the file system (as opposed to thepath field which is a path relative to the git repository).

The returned path will be native to the system and contains\ onWindows.

mode

propertyname:str

Returns:

Name portion of the path, effectively being the basename

path

classgit.objects.base.Object(repo:Repo,binsha:bytes)

Base class for classes representing git object types.

The following four leaf classes represent specific kinds of git objects:

• Blob

• Tree

• Commit

• TagObject

Seegitglossary(7) on:

• “object”:https://git-scm.com/docs/gitglossary#def_object

• “object type”:https://git-scm.com/docs/gitglossary#def_object_type

• “blob”:https://git-scm.com/docs/gitglossary#def_blob_object

• “tree object”:https://git-scm.com/docs/gitglossary#def_tree_object

• “commit object”:https://git-scm.com/docs/gitglossary#def_commit_object

• “tag object”:https://git-scm.com/docs/gitglossary#def_tag_object

Note:

See theAnyGitObject union type of the four leaf subclassesthat represent actual git object types.

Note:

Submodule is defined under the hierarchyrooted at thisObject class, even though submodules are not really atype of git object. (This also applies to itsRootModule subclass.)

Note:

ThisObject class should not be confused withobject (the rootof the class hierarchy in Python).

NULL_BIN_SHA=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

NULL_HEX_SHA='0000000000000000000000000000000000000000'

TYPES=(b'blob',b'tree',b'commit',b'tag')

__annotations__={'type':typing.Optional[typing.Literal['commit','tag','blob','tree']]}

__eq__(other:Any)→bool

Returns:

True if the objects have the same SHA1

__hash__()→int

Returns:

Hash of our id allowing objects to be used in dicts and sets

__init__(repo:Repo,binsha:bytes)→None

Initialize an object by identifying it by its binary sha.

All keyword arguments will be set on demand ifNone.

Parameters:

• repo – Repository this object is located in.

• binsha – 20 byte SHA1

__module__='git.objects.base'

__ne__(other:Any)→bool

Returns:

True if the objects do not have the same SHA1

__repr__()→str

Returns:

String with pythonic representation of our object

__slots__=('repo','binsha','size')

__str__()→str

Returns:

String of our SHA1 as understood by all git commands

binsha

propertydata_stream:OStream

Returns:

File-object compatible stream to the uncompressed raw data of the object

Note:

Returned streams must be read in order.

propertyhexsha:str

Returns:

40 byte hex version of our 20 byte binary sha

classmethodnew(repo:Repo,id:str|Reference)→Commit|Tree|TagObject|Blob

Returns:

NewObject instance of a type appropriate to the object type behindid. The id of the newly created object will be a binsha even though theinput id may have been a~git.refs.reference.Reference or rev-spec.

Parameters:

id –Reference, rev-spec, or hexsha.

Note:

This cannot be a__new__ method as it would always call__init__()with the input id which is not necessarily a binsha.

classmethodnew_from_sha(repo:Repo,sha1:bytes)→Commit|Tree|TagObject|Blob

Returns:

New object instance of a type appropriate to represent the given binary sha1

Parameters:

sha1 – 20 byte binary sha1.

repo

size

stream_data(ostream:OStream)→Object

Write our data directly to the given output stream.

Parameters:

ostream – File-object compatible stream object.

Returns:

self

type:Literal['commit','tag','blob','tree']|None=None

String identifying (a concreteObject subtype for) a git object type.

The subtypes that this may name correspond to the kinds of git objects that exist,i.e., the objects that may be present in a git repository.

Note:

Most subclasses represent specific types of git objects and override this classattribute accordingly. This attribute isNone in theObject baseclass, as well as theIndexObject intermediate subclass, but neverNone in concrete leaf subclasses representing specific git object types.

Note:

See alsoGitObjectTypeString.

Objects.Blob

classgit.objects.blob.Blob(repo:Repo,binsha:bytes,mode:None|int=None,path:None|str|os.PathLike[str]=None)

A Blob encapsulates a git blob object.

Seegitglossary(7) on “blob”:https://git-scm.com/docs/gitglossary#def_blob_object

DEFAULT_MIME_TYPE='text/plain'

__annotations__={'type':typing.Literal['blob']}

__module__='git.objects.blob'

__slots__=()

executable_mode=33261

file_mode=33188

link_mode=40960

propertymime_type:str

Returns:

String describing the mime type of this file (based on the filename)

Note:

Defaults totext/plain in case the actual file type is unknown.

type:Literal['blob']='blob'

String identifying (a concreteObject subtype for) a git object type.

The subtypes that this may name correspond to the kinds of git objects that exist,i.e., the objects that may be present in a git repository.

Note:

Most subclasses represent specific types of git objects and override this classattribute accordingly. This attribute isNone in theObject baseclass, as well as theIndexObject intermediate subclass, but neverNone in concrete leaf subclasses representing specific git object types.

Note:

See alsoGitObjectTypeString.

Objects.Commit

classgit.objects.commit.Commit(repo:Repo,binsha:bytes,tree:Tree|None=None,author:Actor|None=None,authored_date:int|None=None,author_tz_offset:None|float=None,committer:Actor|None=None,committed_date:int|None=None,committer_tz_offset:None|float=None,message:str|bytes|None=None,parents:Sequence[Commit]|None=None,encoding:str|None=None,gpgsig:str|None=None)

Wraps a git commit object.

Seegitglossary(7) on “commit object”:https://git-scm.com/docs/gitglossary#def_commit_object

Note:

This class will act lazily on some of its attributes and will query the value ondemand only if it involves calling the git binary.

__abstractmethods__=frozenset({})

__annotations__={'_id_attribute_':'str','parents':typing.Sequence[ForwardRef('Commit')],'repo':"'Repo'",'type':typing.Literal['commit']}

__init__(repo:Repo,binsha:bytes,tree:Tree|None=None,author:Actor|None=None,authored_date:int|None=None,author_tz_offset:None|float=None,committer:Actor|None=None,committed_date:int|None=None,committer_tz_offset:None|float=None,message:str|bytes|None=None,parents:Sequence[Commit]|None=None,encoding:str|None=None,gpgsig:str|None=None)→None

Instantiate a newCommit. All keyword arguments takingNone asdefault will be implicitly set on first query.

Parameters:

• binsha – 20 byte sha1.

• tree – ATree object.

• author – The authorActor object.

• authored_date – int_seconds_since_epochThe authored DateTime - usetime.gmtime() to convert it into adifferent format.

• author_tz_offset – int_seconds_west_of_utcThe timezone that theauthored_date is in.

• committer – The committer string, as anActor object.

• committed_date – int_seconds_since_epochThe committed DateTime - usetime.gmtime() to convert it into adifferent format.

• committer_tz_offset – int_seconds_west_of_utcThe timezone that thecommitted_date is in.

• message – stringThe commit message.

• encoding – stringEncoding of the message, defaults to UTF-8.

• parents – List or tuple ofCommit objects which are our parent(s) in thecommit dependency graph.

Returns:

Commit

Note:

Timezone information is in the same format and in the same sign as whattime.altzone() returns. The sign is inverted compared to git’s UTCtimezone.

__module__='git.objects.commit'

__parameters__=()

__slots__=('tree','author','authored_date','author_tz_offset','committer','committed_date','committer_tz_offset','message','parents','encoding','gpgsig')

classmethod__subclasshook__(other)

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__().It should return True, False or NotImplemented. If it returnsNotImplemented, the normal algorithm is used. Otherwise, itoverrides the normal algorithm (and the outcome is cached).

author

author_tz_offset

authored_date

propertyauthored_datetime:datetime

propertyco_authors:List[Actor]

Search the commit message for any co-authors of this commit.

Details on co-authors:https://github.blog/2018-01-29-commit-together-with-co-authors/

Returns:

List of co-authors for this commit (asActor objects).

committed_date

propertycommitted_datetime:datetime

committer

committer_tz_offset

conf_encoding='i18n.commitencoding'

count(paths:str|PathLike[str]|Sequence[str|PathLike[str]]='',**kwargs:Any)→int

Count the number of commits reachable from this commit.

Parameters:

• paths – An optional path or a list of paths restricting the return value to commitsactually containing the paths.

• kwargs – Additional options to be passed togit-rev-list(1). They must notalter the output style of the command, or parsing will yield incorrectresults.

Returns:

An int defining the number of reachable commits

classmethodcreate_from_tree(repo:Repo,tree:Tree|str,message:str,parent_commits:None|List[Commit]=None,head:bool=False,author:None|Actor=None,committer:None|Actor=None,author_date:None|str|datetime=None,commit_date:None|str|datetime=None)→Commit

Commit the given tree, creating aCommit object.

Parameters:

• repo –Repo object the commit should be part of.

• tree –Tree object or hex or bin sha.The tree of the new commit.

• message – Commit message. It may be an empty string if no message is provided. It willbe converted to a string, in any case.

• parent_commits – OptionalCommit objects to use as parents for the new commit. Ifempty list, the commit will have no parents at all and become a root commit.IfNone, the current head commit will be the parent of the new commitobject.

• head – IfTrue, the HEAD will be advanced to the new commit automatically.Otherwise the HEAD will remain pointing on the previous commit. This couldlead to undesired results when diffing files.

• author – The name of the author, optional.If unset, the repository configuration is used to obtain this value.

• committer – The name of the committer, optional.If unset, the repository configuration is used to obtain this value.

• author_date – The timestamp for the author field.

• commit_date – The timestamp for the committer field.

Returns:

Commit object representing the new commit.

Note:

Additional information about the committer and author are taken from theenvironment or from the git configuration. Seegit-commit-tree(1)for more information.

default_encoding='UTF-8'

encoding

env_author_date='GIT_AUTHOR_DATE'

env_committer_date='GIT_COMMITTER_DATE'

gpgsig

classmethoditer_items(repo:Repo,rev:str|Commit|SymbolicReference,paths:str|os.PathLike[str]|Sequence[str|os.PathLike[str]]='',**kwargs:Any)→Iterator[Commit]

Find all commits matching the given criteria.

Parameters:

• repo – TheRepo.

• rev – Revision specifier. Seegit-rev-parse(1) for viable options.

• paths – An optional path or list of paths. If set onlyCommits thatinclude the path or paths will be considered.

• kwargs –

  Optional keyword arguments togit-rev-list(1) where:

  • max_count is the maximum number of commits to fetch.

  • skip is the number of commits to skip.

  • since selects all commits since some date, e.g."1970-01-01".

Returns:

Iterator yieldingCommit items.

iter_parents(paths:str|PathLike[str]|Sequence[str|PathLike[str]]='',**kwargs:Any)→Iterator[Commit]

Iterate _all_ parents of this commit.

Parameters:

• paths – Optional path or list of paths limiting theCommits to those thatcontain at least one of the paths.

• kwargs – All arguments allowed bygit-rev-list(1).

Returns:

Iterator yieldingCommit objects which are parents ofself

message

propertyname_rev:str

Returns:

String describing the commits hex sha based on the closest~git.refs.reference.Reference.

Note:

Mostly useful for UI purposes.

parents:Sequence[Commit]

replace(**kwargs:Any)→Commit

Create new commit object from an existing commit object.

Any values provided as keyword arguments will replace the correspondingattribute in the new object.

propertystats:Stats

Create a git stat from changes between this commit and its first parentor from all changes done if this is the very first commit.

Returns:

Stats

propertysummary:str|bytes

Returns:

First line of the commit message

propertytrailers:Dict[str,str]

Deprecated. Get the trailers of the message as a dictionary.

Note:

This property is deprecated, please use eithertrailers_list ortrailers_dict.

Returns:

Dictionary containing whitespace stripped trailer information.Only contains the latest instance of each trailer key.

propertytrailers_dict:Dict[str,List[str]]

Get the trailers of the message as a dictionary.

Git messages can contain trailer information that are similar toRFC 822e-mail headers. Seegit-interpret-trailers(1).

This function callsgitinterpret-trailers--parse onto the message toextract the trailer information. The key value pairs are stripped of leading andtrailing whitespaces before they get saved into a dictionary.

Valid message with trailer:

Subjectlinesomebodyinformationanotherinformationkey1:value1.1key1:value1.2key2:value2withinnerspaces

Returned dictionary will look like this:

{"key1":["value1.1","value1.2"],"key2":["value 2 with inner spaces"],}

Returns:

Dictionary containing whitespace stripped trailer information, mappingtrailer keys to a list of their corresponding values.

propertytrailers_list:List[Tuple[str,str]]

Get the trailers of the message as a list.

Git messages can contain trailer information that are similar toRFC 822e-mail headers. Seegit-interpret-trailers(1).

This function callsgitinterpret-trailers--parse onto the message toextract the trailer information, returns the raw trailer data as a list.

Valid message with trailer:

Subjectlinesomebodyinformationanotherinformationkey1:value1.1key1:value1.2key2:value2withinnerspaces

Returned list will look like this:

[("key1","value1.1"),("key1","value1.2"),("key2","value 2 with inner spaces"),]

Returns:

List containing key-value tuples of whitespace stripped trailer information.

tree

type:Literal['commit']='commit'

String identifying (a concreteObject subtype for) a git object type.

The subtypes that this may name correspond to the kinds of git objects that exist,i.e., the objects that may be present in a git repository.

Note:

Most subclasses represent specific types of git objects and override this classattribute accordingly. This attribute isNone in theObject baseclass, as well as theIndexObject intermediate subclass, but neverNone in concrete leaf subclasses representing specific git object types.

Note:

See alsoGitObjectTypeString.

Objects.Tag

Provides anObject-based type for annotated tags.

This defines theTagObject class, which represents annotated tags.For lightweight tags, see thegit.refs.tag module.

classgit.objects.tag.TagObject(repo:Repo,binsha:bytes,object:None|Object=None,tag:None|str=None,tagger:None|Actor=None,tagged_date:int|None=None,tagger_tz_offset:int|None=None,message:str|None=None)

Annotated (i.e. non-lightweight) tag carrying additional information about anobject we are pointing to.

Seegitglossary(7) on “tag object”:https://git-scm.com/docs/gitglossary#def_tag_object

__annotations__={'type':typing.Literal['tag']}

__init__(repo:Repo,binsha:bytes,object:None|Object=None,tag:None|str=None,tagger:None|Actor=None,tagged_date:int|None=None,tagger_tz_offset:int|None=None,message:str|None=None)→None

Initialize a tag object with additional data.

Parameters:

• repo – Repository this object is located in.

• binsha – 20 byte SHA1.

• object –Object instance of object we are pointing to.

• tag – Name of this tag.

• tagger –Actor identifying the tagger.

• tagged_date – int_seconds_since_epochThe DateTime of the tag creation.Usetime.gmtime() to convert it into a different format.

• tagger_tz_offset – int_seconds_west_of_utcThe timezone that thetagged_date is in, in a format similar totime.altzone.

__module__='git.objects.tag'

__slots__=('object','tag','tagger','tagged_date','tagger_tz_offset','message')

message

object:'Commit'|'Blob'|'Tree'|'TagObject'

tag

tagged_date

tagger

tagger_tz_offset

type:Literal['tag']='tag'

String identifying (a concreteObject subtype for) a git object type.

The subtypes that this may name correspond to the kinds of git objects that exist,i.e., the objects that may be present in a git repository.

Note:

Most subclasses represent specific types of git objects and override this classattribute accordingly. This attribute isNone in theObject baseclass, as well as theIndexObject intermediate subclass, but neverNone in concrete leaf subclasses representing specific git object types.

Note:

See alsoGitObjectTypeString.

Objects.Tree

classgit.objects.tree.Tree(repo:Repo,binsha:bytes,mode:int=16384,path:str|os.PathLike[str]|None=None)

Tree objects represent an ordered list ofBlobs andotherTrees.

Seegitglossary(7) on “tree object”:https://git-scm.com/docs/gitglossary#def_tree_object

Subscripting is supported, as with a list or dict:

• Access a specific blob using thetree["filename"] notation.

• You may likewise access by index, likeblob=tree[0].

__abstractmethods__=frozenset({})

__annotations__={'_map_id_to_type':typing.Dict[int,typing.Type[typing.Union[ForwardRef('Tree'),ForwardRef('Blob'),ForwardRef('Submodule')]]],'repo':"'Repo'",'type':typing.Literal['tree']}

__contains__(item:Tree|Blob|Submodule|str|os.PathLike[str])→bool

__getitem__(item:str|int|slice)→Tree|Blob|Submodule

__getslice__(i:int,j:int)→List[Tree|Blob|Submodule]

__init__(repo:Repo,binsha:bytes,mode:int=16384,path:str|os.PathLike[str]|None=None)

Initialize a newly instancedIndexObject.

Parameters:

• repo – TheRepo we are located in.

• binsha – 20 byte sha1.

• mode – The stat-compatible file mode asint.Use thestat module to evaluate the information.

• path – The path to the file in the file system, relative to the git repositoryroot, likefile.ext orfolder/other.ext.

Note:

Path may not be set if the index object has been created directly, as itcannot be retrieved without knowing the parent tree.

__iter__()→Iterator[Tree|Blob|Submodule]

__len__()→int

__module__='git.objects.tree'

__reversed__()→Iterator[Tree|Blob|Submodule]

__slots__=('_cache',)

__truediv__(file:str)→Tree|Blob|Submodule

The/ operator is another syntax for joining.

Seejoin() for details.

blob_id=8

propertyblobs:List[Blob]

Returns:

list(Blob, …) List of blobs directly below this tree

propertycache:TreeModifier

Returns:

An object allowing modification of the internal cache. This can be used tochange the tree’s contents. When done, make sure you callset_done() on the tree modifier, or serializationbehaviour will be incorrect.

Note:

SeeTreeModifier for more information on how to alter the cache.

commit_id=14

join(file:str)→Tree|Blob|Submodule

Find the named object in this tree’s contents.

Returns:

Blob,Tree, orSubmodule

Raises:

KeyError – If the given file or tree does not exist in this tree.

list_traverse(*args:Any,**kwargs:Any)→IterableList[Tree|Blob|Submodule]

Returns:

IterableList with the results of the traversal asproduced bytraverse()

Tree -> IterableList[Union[Submodule, Tree, Blob]]

symlink_id=10

traverse(predicate:~typing.Callable[[~git.objects.tree.Tree|~git.objects.blob.Blob|~git.objects.submodule.base.Submodule|~typing.Tuple[~git.objects.tree.Tree|None,~git.objects.tree.Tree|~git.objects.blob.Blob|~git.objects.submodule.base.Submodule,~typing.Tuple[~git.objects.submodule.base.Submodule,~git.objects.submodule.base.Submodule]],int],bool]=<functionTree.<lambda>>,prune:~typing.Callable[[~git.objects.tree.Tree|~git.objects.blob.Blob|~git.objects.submodule.base.Submodule|~typing.Tuple[~git.objects.tree.Tree|None,~git.objects.tree.Tree|~git.objects.blob.Blob|~git.objects.submodule.base.Submodule,~typing.Tuple[~git.objects.submodule.base.Submodule,~git.objects.submodule.base.Submodule]],int],bool]=<functionTree.<lambda>>,depth:int=-1,branch_first:bool=True,visit_once:bool=False,ignore_self:int=1,as_edge:bool=False)→Iterator[Tree|Blob|Submodule]|Iterator[Tuple[Tree|None,Tree|Blob|Submodule,Tuple[Submodule,Submodule]]]

For documentation, seeTraversable._traverse() <git.objects.util.Traversable._traverse>.

Trees are set tovisit_once=False to gain more performance in thetraversal.

tree_id=4

propertytrees:List[Tree]

Returns:

list(Tree, …) List of trees directly below this tree

type:Literal['tree']='tree'

String identifying (a concreteObject subtype for) a git object type.

The subtypes that this may name correspond to the kinds of git objects that exist,i.e., the objects that may be present in a git repository.

Note:

Most subclasses represent specific types of git objects and override this classattribute accordingly. This attribute isNone in theObject baseclass, as well as theIndexObject intermediate subclass, but neverNone in concrete leaf subclasses representing specific git object types.

Note:

See alsoGitObjectTypeString.

classgit.objects.tree.TreeModifier(cache:List[Tuple[bytes,int,str]])

A utility class providing methods to alter the underlying cache in a list-likefashion.

Once all adjustments are complete, the_cache, which really is a referenceto the cache of a tree, will be sorted. This ensures it will be in a serializablestate.

__delitem__(name:str)→None

Delete an item with the given name if it exists.

__init__(cache:List[Tuple[bytes,int,str]])→None

__module__='git.objects.tree'

__slots__=('_cache',)

add(sha:bytes,mode:int,name:str,force:bool=False)→TreeModifier

Add the given item to the tree.

If an item with the given name already exists, nothing will be done, but aValueError will be raised if the sha and mode of the existing item do notmatch the one you add, unlessforce isTrue.

Parameters:

• sha – The 20 or 40 byte sha of the item to add.

• mode –int representing the stat-compatible mode of the item.

• force – IfTrue, an item with your name and information will overwrite anyexisting item with the same name, no matter which information it has.

Returns:

self

add_unchecked(binsha:bytes,mode:int,name:str)→None

Add the given item to the tree. Its correctness is assumed, so it is thecaller’s responsibility to ensure that the input is correct.

For more information on the parameters, seeadd().

Parameters:

binsha – 20 byte binary sha.

set_done()→TreeModifier

Call this method once you are done modifying the tree information.

This may be called several times, but be aware that each call will cause a sortoperation.

Returns:

self

Objects.Functions

Functions that are supposed to be as fast as possible.

git.objects.fun.traverse_tree_recursive(odb:GitCmdObjectDB,tree_sha:bytes,path_prefix:str)→List[Tuple[bytes,int,str]]

Returns:

List of entries of the tree pointed to by the binarytree_sha.

An entry has the following format:

• [0] 20 byte sha

• [1] mode as int

• [2] path relative to the repository

Parameters:

path_prefix – Prefix to prepend to the front of all returned paths.

git.objects.fun.traverse_trees_recursive(odb:GitCmdObjectDB,tree_shas:Sequence[bytes|None],path_prefix:str)→List[Tuple[Tuple[bytes,int,str]|None,...]]

Returns:

List of list with entries according to the given binary tree-shas.

The result is encoded in a listof n tuple|None per blob/commit, (n == len(tree_shas)), where:

• [0] == 20 byte sha

• [1] == mode as int

• [2] == path relative to working tree root

The entry tuple isNone if the respective blob/commit did not exist in thegiven tree.

Parameters:

• tree_shas – Iterable of shas pointing to trees. All trees must be on the same level.A tree-sha may beNone, in which caseNone.

• path_prefix – A prefix to be added to the returned paths on this level.Set it"" for the first iteration.

Note:

The ordering of the returned items will be partially lost.

git.objects.fun.tree_entries_from_data(data:bytes)→List[Tuple[bytes,int,str]]

Read the binary representation of a tree and returns tuples ofTree items.

Parameters:

data – Data block with tree data (as bytes).

Returns:

list(tuple(binsha, mode, tree_relative_path), …)

git.objects.fun.tree_to_stream(entries:Sequence[Tuple[bytes,int,str]],write:Callable[[ReadableBuffer],int|None])→None

Write the given list of entries into a stream using itswrite method.

Parameters:

• entries –Sorted list of tuples with (binsha, mode, name).

• write – Awrite method which takes a data string.

Objects.Submodule.base

classgit.objects.submodule.base.Submodule(repo:Repo,binsha:bytes,mode:int|None=None,path:str|os.PathLike[str]|None=None,name:str|None=None,parent_commit:Commit|None=None,url:str|None=None,branch_path:str|os.PathLike[str]|None=None)

Implements access to a git submodule. They are special in that their sharepresents a commit in the submodule’s repository which is to be checked outat the path of this instance.

The submodule type does not have a string type associated with it, as it existssolely as a marker in the tree and index.

All methods work in bare and non-bare repositories.

__abstractmethods__=frozenset({})

__annotations__={'_id_attribute_':'str','type':typing.Literal['submodule']}

__eq__(other:Any)→bool

Compare with another submodule.

__hash__()→int

Hash this instance using its logical id, not the sha.

__init__(repo:Repo,binsha:bytes,mode:int|None=None,path:str|os.PathLike[str]|None=None,name:str|None=None,parent_commit:Commit|None=None,url:str|None=None,branch_path:str|os.PathLike[str]|None=None)→None

Initialize this instance with its attributes.

We only document the parameters that differ fromIndexObject.

Parameters:

• repo – Our parent repository.

• binsha – Binary sha referring to a commit in the remote repository.See theurl parameter.

• parent_commit – TheCommit whose tree is supposed to containthe.gitmodules blob, orNone to always point to the most recentcommit. Seeset_parent_commit() for details.

• url – The URL to the remote repository which is the submodule.

• branch_path – Full repository-relative path to ref to checkout when cloning the remoterepository.

__module__='git.objects.submodule.base'

__ne__(other:object)→bool

Compare with another submodule for inequality.

__parameters__=()

__repr__()→str

Returns:

String with pythonic representation of our object

__slots__=('_parent_commit','_url','_branch_path','_name','__weakref__')

__str__()→str

Returns:

String of our SHA1 as understood by all git commands

classmethod__subclasshook__(other)

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__().It should return True, False or NotImplemented. If it returnsNotImplemented, the normal algorithm is used. Otherwise, itoverrides the normal algorithm (and the outcome is cached).

__weakref__

classmethodadd(repo:Repo,name:str,path:str|os.PathLike[str],url:str|None=None,branch:str|None=None,no_checkout:bool=False,depth:int|None=None,env:Mapping[str,str]|None=None,clone_multi_options:Sequence[Any]|None=None,allow_unsafe_options:bool=False,allow_unsafe_protocols:bool=False)→Submodule

Add a new submodule to the given repository. This will alter the index aswell as the.gitmodules file, but will not create a new commit. If thesubmodule already exists, no matter if the configuration differs from the oneprovided, the existing submodule will be returned.

Parameters:

• repo – Repository instance which should receive the submodule.

• name – The name/identifier for the submodule.

• path – Repository-relative or absolute path at which the submodule should belocated.It will be created as required during the repository initialization.

• url –gitclone...-compatible URL. Seegit-clone(1) for moreinformation. IfNone, the repository is assumed to exist, and the URL ofthe first remote is taken instead. This is useful if you want to make anexisting repository a submodule of another one.

• branch – Name of branch at which the submodule should (later) be checked out. Thegiven branch must exist in the remote repository, and will be checked outlocally as a tracking branch.It will only be written into the configuration if it notNone, which iswhen the checked out branch will be the one the remote HEAD pointed to.The result you get in these situation is somewhat fuzzy, and it isrecommended to specify at leastmaster here.Examples aremaster orfeature/new.

• no_checkout – IfTrue, and if the repository has to be cloned manually, no checkoutwill be performed.

• depth – Create a shallow clone with a history truncated to the specified number ofcommits.

• env –

  Optional dictionary containing the desired environment variables.

  Note: Provided variables will be used to update the execution environmentforgit. If some variable is not specified inenv and is defined inattr:os.environ, the value from attr:os.environ will be used. If youwant to unset some variable, consider providing an empty string as itsvalue.

• clone_multi_options – A list of clone options. Please seeRepo.clone for details.

• allow_unsafe_protocols – Allow unsafe protocols to be used, likeext.

• allow_unsafe_options – Allow unsafe options to be used, like--upload-pack.

Returns:

The newly createdSubmodule instance.

Note:

Works atomically, such that no change will be done if, for example, therepository update fails.

propertybranch:Head

Returns:

The branch instance that we are to checkout

Raises:

git.exc.InvalidGitRepositoryError – If our module is not yet checked out.

propertybranch_name:str

Returns:

The name of the branch, which is the shortest possible branch name

propertybranch_path:str|PathLike[str]

Returns:

Full repository-relative path as string to the branch we would checkout fromthe remote and track

children()→IterableList[Submodule]

Returns:

IterableList(Submodule, …) An iterable list ofSubmoduleinstances which are children of this submodule or 0 if the submodule is notchecked out.

config_reader()→SectionConstraint[SubmoduleConfigParser]

Returns:

ConfigReader instance which allows you to query the configuration values ofthis submodule, as provided by the.gitmodules file.

Note:

The config reader will actually read the data directly from the repositoryand thus does not need nor care about your working tree.

Note:

Should be cached by the caller and only kept as long as needed.

Raises:

IOError – If the.gitmodules file/blob could not be read.

config_writer(index:IndexFile|None=None,write:bool=True)→SectionConstraint[SubmoduleConfigParser]

Returns:

A config writer instance allowing you to read and write the data belongingto this submodule into the.gitmodules file.

Parameters:

• index – If notNone, anIndexFile instance which shouldbe written. Defaults to the index of theSubmodule’s parentrepository.

• write – IfTrue, the index will be written each time a configuration value changes.

Note:

The parameters allow for a more efficient writing of the index, as you canpass in a modified index on your own, prevent automatic writing, and writeyourself once the whole operation is complete.

Raises:

• ValueError – If trying to get a writer on a parent_commit which does not match thecurrent head commit.

• IOError – If the.gitmodules file/blob could not be read.

exists()→bool

Returns:

True if the submodule exists,False otherwise.Please note that a submodule may exist (in the.gitmodules file) eventhough its module doesn’t exist on disk.

classmethoditer_items(repo:Repo,parent_commit:Commit|TagObject|str='HEAD',*args:Any,**kwargs:Any)→Iterator[Submodule]

Returns:

Iterator yieldingSubmodule instances available in the givenrepository

k_default_mode=57344

Submodule flags. Submodules are directories with link-status.

k_head_default='master'

k_head_option='branch'

k_modules_file='.gitmodules'

module()→Repo

Returns:

Repo instance initialized from the repository at oursubmodule path

Raises:

git.exc.InvalidGitRepositoryError – If a repository was not available.This could also mean that it was not yet initialized.

module_exists()→bool

Returns:

True if our module exists and is a valid git repository.See themodule() method.

move(module_path:str|PathLike[str],configuration:bool=True,module:bool=True)→Submodule

Move the submodule to a another module path. This involves physically movingthe repository at our current path, changing the configuration, as well asadjusting our index entry accordingly.

Parameters:

• module_path – The path to which to move our module in the parent repository’s workingtree, given as repository-relative or absolute path. Intermediatedirectories will be created accordingly. If the path already exists, it mustbe empty. Trailing (back)slashes are removed automatically.

• configuration – IfTrue, the configuration will be adjusted to let the submodule pointto the given path.

• module – IfTrue, the repository managed by this submodule will be moved as well.IfFalse, we don’t move the submodule’s checkout, which may leave theparent repository in an inconsistent state.

Returns:

self

Raises:

ValueError – If the module path existed and was not empty, or was a file.

Note:

Currently the method is not atomic, and it could leave the repository in aninconsistent state if a sub-step fails for some reason.

propertyname:str

Returns:

The name of this submodule. It is used to identify it within the.gitmodules file.

Note:

By default, this is the name is the path at which to find the submodule, butin GitPython it should be a unique identifier similar to the identifiersused for remotes, which allows to change the path of the submodule easily.

propertyparent_commit:Commit

Returns:

Commit instance with the tree containing the.gitmodules file

Note:

Will always point to the current head’s commit if it was not set explicitly.

remove(module:bool=True,force:bool=False,configuration:bool=True,dry_run:bool=False)→Submodule

Remove this submodule from the repository. This will remove our entryfrom the.gitmodules file and the entry in the.git/config file.

Parameters:

• module –

  IfTrue, the checked out module we point to will be deleted as well. Ifthat module is currently on a commit outside any branch in the remote, or ifit is ahead of its tracking branch, or if there are modified or untrackedfiles in its working tree, then the removal will fail. In case the removalof the repository fails for these reasons, the submodule status will nothave been altered.

  If this submodule has child modules of its own, these will be deleted priorto touching the direct submodule.

• force – Enforces the deletion of the module even though it contains modifications.This basically enforces a brute-force file system based deletion.

• configuration – IfTrue, the submodule is deleted from the configuration, otherwise itisn’t. Although this should be enabled most of the time, this flag enablesyou to safely delete the repository of your submodule.

• dry_run – IfTrue, we will not actually do anything, but throw the errors we wouldusually throw.

Returns:

self

Note:

Doesn’t work in bare repositories.

Note:

Doesn’t work atomically, as failure to remove any part of the submodule willleave an inconsistent state.

Raises:

• git.exc.InvalidGitRepositoryError – Thrown if the repository cannot be deleted.

• OSError – If directories or files could not be removed.

rename(new_name:str)→Submodule

Rename this submodule.

Note:

This method takes care of renaming the submodule in various places, such as:

• $parent_git_dir/config

• $working_tree_dir/.gitmodules

• (git >= v1.8.0: move submodule repository to new name)

As.gitmodules will be changed, you would need to make a commit afterwards.The changed.gitmodules file will already be added to the index.

Returns:

ThisSubmodule instance

set_parent_commit(commit:Commit|TagObject|str|None,check:bool=True)→Submodule

Set this instance to use the given commit whose tree is supposed tocontain the.gitmodules blob.

Parameters:

• commit – Commit-ish reference pointing at the root tree, orNone to always pointto the most recent commit.

• check – IfTrue, relatively expensive checks will be performed to verifyvalidity of the submodule.

Raises:

• ValueError – If the commit’s tree didn’t contain the.gitmodules blob.

• ValueError – If the parent commit didn’t store this submodule under the current path.

Returns:

self

type:Literal['submodule']='submodule'

This is a bogus type string for base class compatibility.

update(recursive:bool=False,init:bool=True,to_latest_revision:bool=False,progress:UpdateProgress|None=None,dry_run:bool=False,force:bool=False,keep_going:bool=False,env:Mapping[str,str]|None=None,clone_multi_options:Sequence[Any]|None=None,allow_unsafe_options:bool=False,allow_unsafe_protocols:bool=False)→Submodule

Update the repository of this submodule to point to the checkout we point atwith the binsha of this instance.

Parameters:

• recursive – IfTrue, we will operate recursively and update child modules as well.

• init – IfTrue, the module repository will be cloned into place if necessary.

• to_latest_revision – IfTrue, the submodule’s sha will be ignored during checkout. Instead,the remote will be fetched, and the local tracking branch updated. This onlyworks if we have a local tracking branch, which is the case if the remoterepository had a master branch, or if thebranch option was specifiedfor this submodule and the branch existed remotely.

• progress –UpdateProgress instance, orNone if no progress should beshown.

• dry_run – IfTrue, the operation will only be simulated, but not performed.All performed operations are read-only.

• force –

  IfTrue, we may reset heads even if the repository in question is dirty.Additionally we will be allowed to set a tracking branch which is ahead ofits remote branch back into the past or the location of the remote branch.This will essentially ‘forget’ commits.

  IfFalse, local tracking branches that are in the future of theirrespective remote branches will simply not be moved.

• keep_going – IfTrue, we will ignore but log all errors, and keep going recursively.Unlessdry_run is set as well,keep_going could causesubsequent/inherited errors you wouldn’t see otherwise.In conjunction withdry_run, it can be useful to anticipate all errorswhen updating submodules.

• env –

  Optional dictionary containing the desired environment variables.

  Note: Provided variables will be used to update the execution environmentforgit. If some variable is not specified inenv and is defined inattr:os.environ, value from attr:os.environ will be used.

  If you want to unset some variable, consider providing the empty string asits value.

• clone_multi_options – List ofgit-clone(1) options.Please seeRepo.clone for details.They only take effect with theinit option.

• allow_unsafe_protocols – Allow unsafe protocols to be used, likeext.

• allow_unsafe_options – Allow unsafe options to be used, like--upload-pack.

Note:

Does nothing in bare repositories.

Note:

This method is definitely not atomic ifrecursive isTrue.

Returns:

self

propertyurl:str

Returns:

The url to the repository our submodule’s repository refers to

classgit.objects.submodule.base.UpdateProgress

Class providing detailed progress information to the caller who shouldderive from it and implement theupdate(...) message.

CLONE=512

FETCH=1024

UPDWKTREE=2048

__annotations__={'_cur_line':'Optional[str]','_num_op_codes':<class'int'>,'_seen_ops':'List[int]','error_lines':'List[str]','other_lines':'List[str]'}

__module__='git.objects.submodule.base'

__slots__=()

Objects.Submodule.root

classgit.objects.submodule.root.RootModule(repo:Repo)

A (virtual) root of all submodules in the given repository.

This can be used to more easily traverse all submodules of thesuperproject (master repository).

__abstractmethods__=frozenset({})

__annotations__={'_id_attribute_':'str','type':"Literal['submodule']"}

__init__(repo:Repo)→None

Initialize this instance with its attributes.

We only document the parameters that differ fromIndexObject.

Parameters:

• repo – Our parent repository.

• binsha – Binary sha referring to a commit in the remote repository.See theurl parameter.

• parent_commit – TheCommit whose tree is supposed to containthe.gitmodules blob, orNone to always point to the most recentcommit. Seeset_parent_commit() for details.

• url – The URL to the remote repository which is the submodule.

• branch_path – Full repository-relative path to ref to checkout when cloning the remoterepository.

__module__='git.objects.submodule.root'

__parameters__=()

__slots__=()

classmethod__subclasshook__(other)

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__().It should return True, False or NotImplemented. If it returnsNotImplemented, the normal algorithm is used. Otherwise, itoverrides the normal algorithm (and the outcome is cached).

k_root_name='__ROOT__'

module()→Repo

Returns:

The actual repository containing the submodules

update(previous_commit:Commit|TagObject|str|None=None,recursive:bool=True,force_remove:bool=False,init:bool=True,to_latest_revision:bool=False,progress:None|RootUpdateProgress=None,dry_run:bool=False,force_reset:bool=False,keep_going:bool=False)→RootModule

Update the submodules of this repository to the current HEAD commit.

This method behaves smartly by determining changes of the path of a submodule’srepository, next to changes to the to-be-checked-out commit or the branch to bechecked out. This works if the submodule’s ID does not change.

Additionally it will detect addition and removal of submodules, which will behandled gracefully.

Parameters:

• previous_commit – If set to a commit-ish, the commit we should use as the previous commit theHEAD pointed to before it was set to the commit it points to now.IfNone, it defaults toHEAD@{1} otherwise.

• recursive – IfTrue, the children of submodules will be updated as well using thesame technique.

• force_remove – If submodules have been deleted, they will be forcibly removed. Otherwisethe update may fail if a submodule’s repository cannot be deleted as changeshave been made to it.(SeeSubmodule.updatefor more information.)

• init – If we encounter a new module which would need to be initialized, then do it.

• to_latest_revision –

  IfTrue, instead of checking out the revision pointed to by thissubmodule’s sha, the checked out tracking branch will be merged with thelatest remote branch fetched from the repository’s origin.

  Unlessforce_reset is specified, a local tracking branch will never bereset into its past, therefore the remote branch must be in the future forthis to have an effect.

• force_reset – IfTrue, submodules may checkout or reset their branch even if therepository has pending changes that would be overwritten, or if the localtracking branch is in the future of the remote tracking branch and would bereset into its past.

• progress –RootUpdateProgress instance, orNone if no progress should besent.

• dry_run – IfTrue, operations will not actually be performed. Progress messageswill change accordingly to indicate the WOULD DO state of the operation.

• keep_going – IfTrue, we will ignore but log all errors, and keep going recursively.Unlessdry_run is set as well,keep_going could causesubsequent/inherited errors you wouldn’t see otherwise.In conjunction withdry_run, this can be useful to anticipate all errorswhen updating submodules.

Returns:

self

classgit.objects.submodule.root.RootUpdateProgress

Utility class which adds more opcodes toUpdateProgress.

BRANCHCHANGE=16384

PATHCHANGE=8192

REMOVE=4096

URLCHANGE=32768

__annotations__={'_cur_line':'Optional[str]','_num_op_codes':'int','_seen_ops':'List[int]','error_lines':'List[str]','other_lines':'List[str]'}

__module__='git.objects.submodule.root'

__slots__=()

Objects.Submodule.util

classgit.objects.submodule.util.SubmoduleConfigParser(*args:Any,**kwargs:Any)

Catches calls towrite(), and updates the.gitmodules blob in the index with the new data, if we have written into astream.

Otherwise it would add the local file to the index to make it correspond with theworking tree. Additionally, the cache must be cleared.

Please note that no mutating method will work in bare mode.

__abstractmethods__=frozenset({})

__init__(*args:Any,**kwargs:Any)→None

Initialize a configuration reader to read the givenfile_or_files and topossibly allow changes to it by settingread_only False.

Parameters:

• file_or_files – A file path or file object, or a sequence of possibly more than one of them.

• read_only – IfTrue, the ConfigParser may only read the data, but not change it.IfFalse, only a single file path or file object may be given. We willwrite back the changes when they happen, or when the ConfigParser isreleased. This will not happen if other configuration files have beenincluded.

• merge_includes – IfTrue, we will read files mentioned in[include] sections andmerge their contents into ours. This makes it impossible to write back anindividual configuration file. Thus, if you want to modify a singleconfiguration file, turn this off to leave the original dataset unalteredwhen reading it.

• repo – Reference to repository to use if[includeIf] sections are found inconfiguration files.

__module__='git.objects.submodule.util'

flush_to_index()→None

Flush changes in our configuration file to the index.

set_submodule(submodule:Submodule)→None

Set this instance’s submodule. It must be called before the first writeoperation begins.

write()→None

Write changes to our file, if there are changes at all.

Raises:

IOError – If this is a read-only writer instance or if we could not obtain a filelock.