API Reference

class giterator.Git(path: Path | str)

Represents a local work tree and repo.

Parameters:

path – The path to an existing work tree or local repo.

path: Path

The path where this instance is located.

__call__(*command: str, env: dict[str, str] | None = None, cwd: Path | None = None) → str

Run a git command in this repo. For example:

Git(...)('log', '-1')
git(*command: str, env: dict[str, str] | None = None, cwd: Path | None = None) → str

Run a git command in this repo. For example:

Git(...)('log', '-1')
init(user: User | None = None, branch: str | None = None) → None

Create an empty Git repository or reinitialize an existing one. If the path doesn’t exist, it will be created. This includes any missing parent directories.

Parameters:

  • user – The user to configure in the local repo.

  • branch – The name to use for the initial branch. If not specified, the machine’s git default is used.

classmethod clone(source: str | Path | Git, path: str | Path, user: User | None = None) → Self

Clone the source repo to the path specified.

Parameters:

  • source – The repo to clone, either as a path or a Git instance.

  • path – Where to clone to. Relative paths are resolved relative to the parent of source.

  • user – The user to configure in the local clone. If not specified and source is a Git instance, the user from source, if any, is configured. Otherwise, no user is configured and commits in the clone will depend on git’s normal identity discovery.

commit(msg: str, author_date: date | datetime | str | None = None, commit_date: date | datetime | str | None = None, short: bool = True) → str

Commit changes in this repo, including and new or deleted files.

Parameters:

  • msg – The commit message.

  • author_date – The author date.

  • commit_date – The commit date. Defaults to author date if not specified.

  • short – Return the short commit hash instead of the full 40-character hash.

tag(name: str) → None

Create a tag with the specified name.

tags() → list[str]

Return a list of tags in this repo.

tag_hashes() → dict[str, str]

Return a mapping of tag name to commit hash.

branch(name: str) → None

Create and checkout a branch with the specified name.

branches() → list[str]

Return a list of branches in this repo.

branch_hashes() → dict[str, str]

Return a mapping of branch name to commit hash.

class giterator.User(name: str, email: str)

Represents a git user, for configuring a repo.

class giterator.testing.Repo(path: Path | str)

A repo for use in automated tests.

classmethod make(path: Path | str, user: User | None = None, branch: str = 'main') → Self

Make a repo at the path specified and ensure a user and initial branch name are configured in the repo, so neither depends on the git config of the machine the tests are running on. Both can be specified.

classmethod clone(source: str | Path | Git, path: str | Path, user: User | None = None) → Self

As Git.clone(), but always ensures a user is configured in the clone, so commits made in it never depend on the machine’s global git config. The user can be specified, and is otherwise inherited from a Git source; failing both, the same default as make() is used.

commit(msg: str, author_date: date | datetime | str | None = None, commit_date: date | datetime | str | None = None, short: bool = True) → str

Commit changes in this repo, including and new or deleted files.

Parameters:

  • msg – The commit message.

  • author_date – The author date.

  • commit_date – The commit date. Defaults to author date if not specified.

  • short – Return the short commit hash instead of the full 40-character hash.

commit_content(prefix: str, dt: datetime | None = None, *, tag: str | None = None, branch: str | None = None, short: bool = True) → str

Write new context based on the prefix and then commit it at the specified datetime, or using at a sequence of increasing datetimes if not specified.