The Index file and the Working copy

  • Repository.index
  • Index representing the repository’s index file.

Index read:

  1. >>> index = repo.index
  2. >>> index.read()
  3. >>> id = index['path/to/file'].id    # from path to object id
  4. >>> blob = repo[id]                  # from object id to object

Iterate over all entries of the index:

  1. >>> for entry in index:
  2. ...     print(entry.path, entry.hex)

Index write:

  1. >>> index.add('path/to/file')          # git add
  2. >>> index.remove('path/to/file')       # git rm
  3. >>> index.write()                      # don't forget to save the changes
  • Custom entries::
  1. >>> entry = pygit2.IndexEntry('README.md', blob_id, blob_filemode)
  2. >>> repo.index.add(entry)

The index fulfills a dual role as the in-memory representation of theindex file and data structure which represents a flat list of atree. You can use it independently of the index file, e.g.

  1. >>> index = pygit2.Index()
  2. >>> entry = pygit2.IndexEntry('README.md', blob_id, blob_filemode)
  3. >>> index.add(entry)

The Index type

  • class pygit2.Index(path=None)
    • add(path_or_entry)
    • Add or update an entry in the Index.

If a path is given, that file will be added. The path must be relativeto the root of the worktree and the Index must be associated with arepository.

If an IndexEntry is given, that entry will be added or update in theIndex without checking for the existence of the path or id.

  • addall(_pathspecs=[])
  • Add or update index entries matching files in the working directory.

If pathspecs are specified, only files matching those pathspecs willbe added.

  • conflicts
  • A collection of conflict information

If there are no conflicts None is returned. Otherwise return an objectthat represents the conflicts in the index.

This object presents a mapping interface with the paths as keys. Youcan use the del operator to remove a conflict form the Index.

Each conflict is made up of three elements. Access or iterationof the conflicts returns a three-tuple ofIndexEntry. The first is the commonancestor, the second is the “ours” side of the conflict and thethirs is the “theirs” side.

These elements may be None depending on which sides exist forthe particular conflict.

  • diffto_tree(_tree, flags=0, context_lines=3, interhunk_lines=0)
  • Diff the index against a tree. Return a object with thedifferences between the index and the given tree.

Parameters:

  1. - tree
  2. - The tree to diff.
  3. - flags
  4. - A GIT_DIFF_* constant.
  5. - context_lines
  6. - The number of unchanged lines that define the boundary of a hunk(and to display before and after).
  7. - interhunk_lines
  8. - The maximum number of unchanged lines between hunk boundariesbefore the hunks will be merged into a one.
  • diffto_workdir(_flags=0, context_lines=3, interhunk_lines=0)
  • Diff the index against the working directory. Return a objectwith the differences between the index and the working copy.

Parameters:

  1. - flags
  2. - A GIT_DIFF_* constant.
  3. - context_lines
  4. - The number of unchanged lines that define the boundary of a hunk(and to display before and after).
  5. - interhunk_lines
  6. - The maximum number of unchanged lines between hunk boundariesbefore the hunks will be merged into a one.
  • read(force=True)
  • Update the contents of the Index by reading from a file.

Parameters:

  1. - force
  2. - If True (the default) allways reload. If False, only if the filehas changed.
  • readtree(_tree)
  • Replace the contents of the Index with those of the given tree,expressed either as a object or as an oid (string or ).

The tree will be read recursively and all its children will also beinserted into the Index.

  • remove(path, level=0)

  • Remove an entry from the Index.

  • write()

  • Write the contents of the Index to disk.

  • writetree(_repo=None)

  • Create a tree out of the Index. Return the object of thewritten tree.

The contents of the index will be written out to the objectdatabase. If there is no associated repository, ‘repo’ must bepassed. If there is an associated repository and ‘repo’ ispassed, then that repository will be used instead.

It returns the id of the resulting tree.

The IndexEntry type

  • class pygit2.IndexEntry(path, object_id, mode)
    • hex

    • The id of the referenced object as a hex string

    • id

    • The id of the referenced object

    • mode

    • The mode of this entry, a GITFILEMODE* value

    • path

    • The path of this entry

Status

  • Repository.status() → {str: int}

  • Reads the status of the repository and returns a dictionary with filepaths as keys and status flags as values. See pygit2.GITSTATUS*.

  • Repository.statusfile(_path) → int

  • Returns the status of the given file path.

Inspect the status of the repository:

  1. >>> from pygit2 import GIT_STATUS_CURRENT
  2. >>> status = repo.status()
  3. >>> for filepath, flags in status.items():
  4. ...     if flags != GIT_STATUS_CURRENT:
  5. ...         print("Filepath %s isn't clean" % filepath)

Checkout

  • Repository.checkout(refname=None, **kwargs)
  • Checkout the given reference using the given strategy, and update theHEAD.The reference may be a reference name or a Reference object.The default strategy is GIT_CHECKOUT_SAFE | GIT_CHECKOUT_RECREATE_MISSING.

If no reference is given, checkout from the index.

Parameters:

  • refname :str or Reference
  • The reference to checkout. After checkout, the current branch willbe switched to this one.
  • strategy :int
  • A GITCHECKOUT value. The default is GIT_CHECKOUT_SAFE.
  • directory :str
  • Alternative checkout path to workdir.
  • paths :list[str]

  • A list of files to checkout from the given reference.If paths is provided, HEAD will not be set to the reference.
    Examples:

  • To checkout from the HEAD, just pass ‘HEAD’:

  1. >>> checkout('HEAD')

This is identical to calling checkout_head().

Lower level API:

  • Repository.checkouthead(**kwargs_)
  • Checkout HEAD

For arguments, see Repository.checkout().

  • Repository.checkouttree(_treeish, **kwargs)
  • Checkout the given treeish

For arguments, see Repository.checkout().

  • Repository.checkoutindex(**kwargs_)
  • Checkout the repository’s index

For arguments, see Repository.checkout().

Stash

  • Repository.stash(stasher, message=None, keep_index=False, include_untracked=False, include_ignored=False)
  • Save changes to the working directory to the stash.

Returns: The Oid of the stash merge commit (Oid).

Parameters:

  • stasher :Signature
  • The identity of the person doing the stashing.
  • message :str
  • An optional description of stashed state.
  • keep_index :bool
  • Leave changes already added to the index in the working directory.
  • include_untracked :bool
  • Also stash untracked files.
  • include_ignored :bool
  • Also stash ignored files.
    Example:
  1. >>> repo = pygit2.Repository('.')
  2. >>> repo.stash(repo.default_signature(), 'WIP: stashing')
  • Repository.stashapply(_index=0, **kwargs)
  • Apply a stashed state in the stash list to the working directory.

Parameters:

  • index :int
  • The position within the stash list of the stash to apply. 0 is themost recent stash.
  • reinstate_index :bool
  • Try to reinstate stashed changes to the index.
    The checkout options may be customized using the same arguments taken byRepository.checkout().

Example:

  1. >>> repo = pygit2.Repository('.')
  2. >>> repo.stash(repo.default_signature(), 'WIP: stashing')
  3. >>> repo.stash_apply(strategy=GIT_CHECKOUT_ALLOW_CONFLICTS)
  • Repository.stashdrop(_index=0)
  • Remove a stashed state from the stash list.

Parameters:

  • index :int
  • The position within the stash list of the stash to remove. 0 isthe most recent stash.
    • Repository.stashpop(_index=0, **kwargs)
    • Apply a stashed state and remove it from the stash list.

For arguments, see Repository.stash_apply().