git module¶

GitBranch ¶

The branch a repository is on, according to git describe --all.

Commands:

! test -d <repo> || (cd <repo> && git describe --all)

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_branch.py.

GitConfig ¶

The git configuration items, as a list of key/values entries.

Commands:

! test -d <repo> || (cd <repo> && git config --local -l)

Returns:

list[GitConfigItem]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_config.py.

GitConfigItem ¶

Attributes:

Name	Type	Description
`key`		The configuration item's key, for example `user.email`.
`values`		The key's values in listing order; a multi-valued key (`safe.directory`) keeps every entry.

GitHeadDetached ¶

Whether the repository's HEAD is detached, or None if undetermined.

Commands:

! test -d <repo> || (cd <repo> && if git symbolic-ref -q HEAD >/dev/null 2>&1; then echo attached; elif git rev-parse --git-dir >/dev/null 2>&1; then echo detached; fi)

Returns:

bool | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_head_detached.py.

GitIsRepo ¶

Whether a directory is a valid git working-tree repository.

Commands:

! test -d <repo> || (cd <repo> && git rev-parse --is-inside-work-tree 2>/dev/null)

Returns:

bool

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_is_repo.py.

GitLocalCommit ¶

The SHA of a local ref (default HEAD) in a repository, or None.

Commands:

! test -d <repo> || (cd <repo> && git rev-parse <ref> 2>/dev/null) || true

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_local_commit.py.

GitRemoteBranchCommit ¶

The tip SHA of a branch on a remote, via git ls-remote, or None.

Commands:

! test -d <repo> || (cd <repo> && git ls-remote <remote> <branch> 2>/dev/null | head -n1)

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_remote_branch_commit.py.

GitRemoteUrl ¶

A remote's fetch (or push) URL, or None when it cannot be resolved.

Commands:

! test -d <repo> || (cd <repo> && git remote get-url <remote> 2>/dev/null)

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_remote_url.py.

GitSshKeyConfigured ¶

Whether ssh -T authenticates the user to a git remote host.

Commands:

ssh -T -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=<timeout> <user>@<remote_host> >/dev/null 2>&1; rc=$?; test "$rc" -eq 127 && exit 127; test "$rc" -ne 255 && echo authenticated || echo unauthenticated

Returns:

bool

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_ssh_key_configured.py.

GitStatus ¶

The working tree's staged, unstaged and untracked changes.

Commands:

! test -d <repo> || (cd <repo> && git status --porcelain)

Returns:

GitStatusSummary

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_status.py.

GitStatusSummary ¶

Attributes:

Name	Type	Description
`dirty`		`True` when any of the three path lists is non-empty.
`staged`		Paths with an index (`git add`-ed) change.
`unstaged`		Paths with a work-tree change not yet staged. A path both staged and modified in the work tree appears in both lists.
`untracked`		Paths git does not track (the porcelain `??` rows).

GitSubmodule ¶

The repository's submodules and their synchronization state.

Commands:

! test -d <repo> || (cd <repo> && git submodule status)

Returns:

list[GitSubmoduleStatus]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_submodule.py.

GitSubmoduleStatus ¶

Attributes:

Name	Type	Description
`path`		The submodule's path within the repository.
`sha`		The commit the submodule is checked out at.
`state`		One of `synced`, `uninitialized`, `modified`, `conflicted` or `unknown`.
`describe`		The `git describe` detail git appends in parentheses, or `None` when the row carries none (an uninitialized submodule).

GitTag ¶

The repository's tags, as GitTagInfo entries in git tag order.

Commands:

! test -d <repo> || (cd <repo> && git tag)

Returns:

list[GitTagInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_tag.py.

GitTagInfo ¶

Attributes:

Name	Type	Description
`name`		The tag name, for example `v1.0.0`.

GitTrackingBranch ¶

The upstream tracking branch of the checked-out branch, or None.

Commands:

! test -d <repo> || (cd <repo> && git status --branch --porcelain)

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_git_tracking_branch.py.

config `async` ¶

config(
    ctx: OpContext,
    key: str,
    value: str,
    multi_value: bool = False,
    repo: str | None = None,
    system: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage git config at repository, user or system level.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`key`	`str`	The config key to ensure.	required
`value`	`str`	The value this key should have.	required
`multi_value`	`bool`	Add the value (`--add`) rather than set it, for keys that carry several values. Defaults to False.	`False`
`repo`	`str \| None`	Edit this repository's `--local` config; defaults to the login user's `--global` config when unset. Defaults to None.	`None`
`system`	`bool`	With no `repo`, work at `--system` level instead of `--global`. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The config-set command, when the value differs.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_config.py.

repo `async` ¶

repo(
    ctx: OpContext,
    src: str,
    dest: str,
    branch: str | None = None,
    pull: bool = True,
    rebase: bool = False,
    update_submodules: bool = False,
    recursive_submodules: bool = False,
    depth: int | None = None,
    *,
    fetch_tags: bool = False,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Clone or update a git repository.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	The git source URL to clone from or keep `origin` pointed at.	required
`dest`	`str`	The directory to clone into / update.	required
`branch`	`str \| None`	The branch or tag to check out. Defaults to None.	`None`
`pull`	`bool`	Pull changes for an existing repository. Defaults to True.	`True`
`rebase`	`bool`	When pulling, use `--rebase`. Defaults to False.	`False`
`update_submodules`	`bool`	Run `git submodule update --init` afterwards. Defaults to False.	`False`
`recursive_submodules`	`bool`	Add `--recursive` to that submodule update. Defaults to False.	`False`
`depth`	`int \| None`	Truncate clone, fetch and pull history to N commits (`--depth N` on each). Defaults to None.	`None`
`fetch_tags`	`bool`	Fetch all tags (`--tags`) before a branch checkout. Defaults to False.	`False`
`force`	`bool`	Pass `--force` to fetch, checkout and pull. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated clone, remote-update, fetch, checkout, pull and submodule-update commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/git/git_repo.py.

worktree `async` ¶

worktree(
    ctx: OpContext,
    worktree: str,
    repo: str | None = None,
    detached: bool = False,
    new_branch: str | None = None,
    commitish: str | None = None,
    pull: bool = True,
    rebase: bool = False,
    from_remote_branch: tuple[str, str] | None = None,
    present: bool = True,
    assume_repo_exists: bool = False,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage git working trees.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`worktree`	`str`	The working-tree directory to manage.	required
`repo`	`str \| None`	The main repository directory the worktree is added from (required when creating; unused when removing). Defaults to None.	`None`
`detached`	`bool`	Create the working tree with a detached `HEAD`. Defaults to False.	`False`
`new_branch`	`str \| None`	A local branch created together with the worktree. Defaults to None.	`None`
`commitish`	`str \| None`	The commit/branch/tag the worktree is created from. Defaults to None.	`None`
`pull`	`bool`	Pull changes for an existing worktree linked to a remote branch. Defaults to True.	`True`
`rebase`	`bool`	When pulling, use `--rebase`. Defaults to False.	`False`
`from_remote_branch`	`tuple[str, str] \| None`	A `(remote, branch)` 2-tuple naming the remote branch to pull from. Defaults to None.	`None`
`present`	`bool`	Whether the working tree should exist. Defaults to True.	`True`
`assume_repo_exists`	`bool`	Skip the `repo/.git` validity check. Defaults to False.	`False`
`force`	`bool`	Pass `--force` when adding or removing the worktree. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated worktree add/remove and pull commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError, ValueError

Examples:

Examples can be found in examples/modules/git/git_worktree.py.

git module¶

GitBranch ¶

GitConfig ¶

GitConfigItem ¶

GitHeadDetached ¶

GitIsRepo ¶

GitLocalCommit ¶

GitRemoteBranchCommit ¶

GitRemoteUrl ¶

GitSshKeyConfigured ¶

GitStatus ¶

GitStatusSummary ¶

GitSubmodule ¶

GitSubmoduleStatus ¶

GitTag ¶

GitTagInfo ¶

GitTrackingBranch ¶

config async ¶

repo async ¶

worktree async ¶

config `async` ¶

repo `async` ¶

worktree `async` ¶