# The repository

Everything starts either by creating a new repository, or by opening an existing one.

Contents

- Functions
- The Repository class

## Functions

`pygit2.``init_repository`(path, bare=False, flags=16, mode=0, workdir_path=None, description=None, template_path=None, initial_head=None, origin_url=None)

  Creates a new Git repository in the given path.

  If bare is True the repository will be bare, i.e. it will not have a working copy.

  The flags may be a combination of:

  - GIT_REPOSITORY_INIT_BARE (overriden by the bare parameter)
  - GIT_REPOSITORY_INIT_NO_REINIT
  - GIT_REPOSITORY_INIT_NO_DOTGIT_DIR
  - GIT_REPOSITORY_INIT_MKDIR
  - GIT_REPOSITORY_INIT_MKPATH (set by default)
  - GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE

  The mode parameter may be any of GIT_REPOSITORY_SHARED_UMASK (default), GIT_REPOSITORY_SHARED_GROUP or GIT_REPOSITORY_INIT_SHARED_ALL, or a custom value.

  The workdir_path, description, template_path, initial_head and origin_url are all strings.

  See libgit2’s documentation on git_repository_init_ext for further details.

  Example:

      >>> from pygit2 import init_repository
      >>> repo = init_repository('test')            # Creates a non-bare repository
      >>> repo = init_repository('test', bare=True) # Creates a bare repository

`pygit2.``clone_repository`(url, path, bare=False, repository=None, remote=None, checkout_branch=None, callbacks=None)

  Clones a new Git repository from url in the given path.

  Returns: a Repository class pointing to the newly cloned repository.

  Parameters:

  url : str
    URL of the repository to clone.
  path : str
    Local path to clone into.
  bare : bool
    Whether the local repository should be bare.
  remote : callable

    Callback for the remote to use.

    The remote callback has (Repository, name, url) -> Remote as a signature. The Remote it returns will be used instead of the default one.

  repository : callable

    Callback for the repository to use.

    The repository callback has (path, bare) -> Repository as a signature. The Repository it returns will be used instead of creating a new one.

  checkout_branch : str
    Branch to checkout after the clone. The default is to use the remote’s default branch.
  callbacks : RemoteCallbacks

    Object which implements the callbacks as methods.

    The callbacks should be an object which inherits from pyclass:RemoteCallbacks.

  Example:

      >>> from pygit2 import clone_repository
      >>> repo_url = 'git://github.com/libgit2/pygit2.git'
      >>> repo_path = '/path/to/create/repository'
      >>> repo = clone_repository(repo_url, repo_path) # Clones a non-bare repository
      >>> repo = clone_repository(repo_url, repo_path, bare=True) # Clones a bare repository

`pygit2.``discover_repository`(path[, across_fs[, ceiling_dirs]]) → str

  Look for a git repository and return its path.

  Example:

      >>> current_working_directory = os.getcwd()
      >>> repository_path = discover_repository(current_working_directory)
      >>> repo = Repository(repository_path)

## The Repository class

class `pygit2.``Repository`(path)

  The Repository constructor only takes one argument, the path of the repository to open.

  Example:

      >>> from pygit2 import Repository
      >>> repo = Repository('pygit2/.git')

The API of the Repository class is quite large. Since this documentation is organized by features, the related bits are explained in the related chapters, for instance the `pygit2.Repository.checkout()` method is explained in the Checkout section.

Below there are some general attributes and methods:

`Repository.``path`

  The normalized path to the git repository.

`Repository.``workdir`

  The normalized path to the working directory of the repository. If the repository is bare, None will be returned.

`Repository.``is_bare`

  Check if a repository is a bare repository.

`Repository.``is_empty`

  Check if a repository is empty.

`Repository.``default_signature`

  Return the signature according to the repository’s configuration

`Repository.``read`(oid) → type, data, size

  Read raw object data from the repository.

`Repository.``write`(type, data) → Oid

  Write raw object data into the repository. First arg is the object type, the second one a buffer with data. Return the Oid of the created object.

`Repository.``ahead_behind`(local, upstream)

  Calculate how many different commits are in the non-common parts of the history between the two given ids.

  Ahead is how many commits are in the ancestry of the ‘local’ commit which are not in the ‘upstream’ commit. Behind is the opposite.

  Returns: a tuple of two integers with the number of commits ahead and behind respectively.

  Parameters:

  local
    The commit which is considered the local or current state.
  upstream
    The commit which is considered the upstream.

`Repository.``create_reference`(name, target, force=False)

  Create a new reference “name” which points to an object or to another reference.

  Based on the type and value of the target parameter, this method tries to guess whether it is a direct or a symbolic reference.

  Keyword arguments:

  force
    If True references will be overridden, otherwise (the default) an exception is raised.

  Examples:

      repo.create_reference('refs/heads/foo', repo.head.target)
      repo.create_reference('refs/tags/foo', 'refs/heads/master')
      repo.create_reference('refs/tags/foo', 'bbb78a9cec580')

`Repository.``describe`(committish=None, max_candidates_tags=None, describe_strategy=None, pattern=None, only_follow_first_parent=None, show_commit_oid_as_fallback=None, abbreviated_size=None, always_use_long_format=None, dirty_suffix=None)

  Describe a commit-ish or the current working tree.

  Returns: The description (str).

  Parameters:

  committish : str, `Reference`, or `Commit`
    Commit-ish object or object name to describe, or None to describe the current working tree.
  max_candidates_tags : int
    The number of candidate tags to consider. Increasing above 10 will take slightly longer but may produce a more accurate result. A value of 0 will cause only exact matches to be output.
  describe_strategy : int

    Can be one of:

    - GIT_DESCRIBE_DEFAULT - Only match annotated tags. (This is equivalent to setting this parameter to None.)
    - GIT_DESCRIBE_TAGS - Match everything under refs/tags/ (includes lightweight tags).
    - GIT_DESCRIBE_ALL - Match everything under refs/ (includes branches).
  pattern : str
    Only consider tags matching the given glob(7) pattern, excluding the “refs/tags/” prefix.
  only_follow_first_parent : bool
    Follow only the first parent commit upon seeing a merge commit.
  show_commit_oid_as_fallback : bool
    Show uniquely abbreviated commit object as fallback.
  abbreviated_size : int
    The minimum number of hexadecimal digits to show for abbreviated object names. A value of 0 will suppress long format, only showing the closest tag.
  always_use_long_format : bool
    Always output the long format (the nearest tag, the number of commits, and the abbrevated commit name) even when the committish matches a tag.
  dirty_suffix : str
    A string to append if the working tree is dirty.

  Example:

      repo.describe(pattern='public/*', dirty_suffix='-dirty')

`Repository.``path_is_ignored`()

  Check if a path is ignored in the repository.

`Repository.``reset`(oid, reset_type)

  Resets the current head.

  Parameters:

  oid
    The oid of the commit to reset to.
  reset_type
    - GIT_RESET_SOFT: resets head to point to oid, but does not modify working copy, and leaves the changes in the index.
    - GIT_RESET_MIXED: resets head to point to oid, but does not modify working copy. It empties the index too.
    - GIT_RESET_HARD: resets head to point to oid, and resets too the working copy and the content of the index.

`Repository.``revert_commit`(revert_commit, our_commit, mainline=0)

  Reverts the given Commit against the given “our” Commit, producing an Index that reflects the result of the revert.

  Returns: an Index with the result of the revert.

  Parameters:

  revert_commit
    The Commit to revert.
  our_commit
    The Commit to revert against (eg, HEAD).
  mainline
    The parent of the revert Commit, if it is a merge (i.e. 1, 2).

`Repository.``state_cleanup`()

  Remove all the metadata associated with an ongoing command like merge, revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc.

`Repository.``write_archive`(treeish, archive, timestamp=None, prefix='')

  Write treeish into an archive.

  If no timestamp is provided and ‘treeish’ is a commit, its committer timestamp will be used. Otherwise the current time will be used.

  All path names in the archive are added to ‘prefix’, which defaults to an empty string.

  Parameters:

  treeish
    The treeish to write.
  archive
    An archive from the ‘tarfile’ module.
  timestamp
    Timestamp to use for the files in the archive.
  prefix
    Extra prefix to add to the path names in the archive.

  Example:

      >>> import tarfile, pygit2
      >>>> with tarfile.open('foo.tar', 'w') as archive:
      >>>>     repo = pygit2.Repsitory('.')
      >>>>     repo.write_archive(repo.head.target, archive)

`Repository.``free`()

  Releases handles to the Git database without deallocating the repository.