Git utilities reference¶

Git ¶

Example usage:

app.tools.git.run(["status"])

author_name ¶

author_name: str

Get the git author name from dda config, env var, or by querying the global git config. Note that the global git config should itself read the env var if it exists - we manually read the env var as a performance optimization.

author_email ¶

author_email: str

Get the git author email from dda config, env var, or by querying the global git config. Note that the global git config should itself read the env var if it exists - we manually read the env var as a performance optimization.

get_changes ¶

get_changes(
    ref: str = "HEAD",
    /,
    *,
    start: str | None = None,
    merge_base: bool = False,
    working_tree: bool = False,
    remote_name: str = "origin",
) -> ChangeSet

Use git to compute a ChangeSet between two refs.

Parameters:

Name	Type	Description	Default
`ref`	`str`	The reference to compare.	`'HEAD'`
`start`	`str \| None`	The reference to compare against, defaulting to the parent commit of `ref`.	`None`
`merge_base`	`bool`	Whether to compare against the merge base of `ref` and `start`.	`False`
`working_tree`	`bool`	Whether to include working tree changes.	`False`
`remote_name`	`str`	The configured name of the remote. This is only used if `merge_base` is True and `start` is not provided.	`'origin'`

Returns:

Type	Description
`ChangeSet`	A ChangeSet representing the differences between the refs.

Examples:

Get changes between HEAD and its parent commit
```
git.get_changes()
```
Get changes between HEAD and the main branch
```
git.get_changes(start="origin/main")
```
Get changes between two references
```
git.get_changes("ref2", start="ref1")
```
Get changes between HEAD and the feat1 branch starting from the merge base
```
git.get_changes(start="origin/feat1", merge_base=True)
```
Get changes between HEAD and remote's HEAD (tip of the default branch) starting from the merge base
```
git.get_changes(merge_base=True)
```

Get only the working tree changes

git.get_changes(start="HEAD", working_tree=True)

get_commit ¶

get_commit(ref: str = 'HEAD') -> Commit

Get a Commit object from the Git repository in the current working directory for the given reference (default: HEAD).

get_remote ¶

get_remote(remote_name: str = 'origin') -> Remote

Get the details of the given remote for the Git repository in the current working directory.

add ¶

add(paths: Iterable[str | PathLike[str]]) -> None

Add the given paths to the index. Will fail if any path is not under cwd.

commit ¶

commit(message: str, *, allow_empty: bool = False) -> None

Commit the changes in the index.

commit_file ¶

commit_file(path: Path, *, content: str, commit_message: str) -> None

Create and commit a single file with the given content.

Commit ¶

A Git commit, identified by its SHA-1 hash.

sha1 ¶

sha1: str

author ¶

author: GitPersonDetails

committer ¶

committer: GitPersonDetails

message ¶

message: str

committer_datetime ¶

committer_datetime: datetime

author_datetime ¶

author_datetime: datetime

GitPersonDetails ¶

Details of a person in Git (author or committer), including their name, email, and timestamp.

name ¶

name: str

email ¶

email: str

timestamp ¶

timestamp: int

ChangeSet ¶

Represents a set of changes to files in a git repository. This can both be a change between two commits, or the changes in the working directory.

When considering the changes to the working directory, the untracked files are considered as added files.

files ¶

files: Iterable[ChangedFile]

paths ¶

paths: MappingProxyType[str, ChangedFile]

added ¶

added: MappingProxyType[str, ChangedFile]

Set of files that were added.

modified ¶

modified: MappingProxyType[str, ChangedFile]

Set of files that were modified.

deleted ¶

deleted: MappingProxyType[str, ChangedFile]

Set of files that were deleted.

digest ¶

digest() -> str

Compute a hash of the changeset.

from_patches ¶

from_patches(diff_output: str | list[str]) -> Self

Generate a ChangeSet from the output of some git diff commands. Not all outputs from git diff are supported (ex: renames).

ChangedFile ¶

Represents changes to a single file in a git repository.

path ¶

path: Path

The path to the file that was changed.

type ¶

type: ChangeType

The type of change that was made to the file: added, modified, or deleted.

binary ¶

binary: bool

Whether the changed file was a binary file.

patch ¶

patch: str

The patch representing the changes to the file, in unified diff format. We only keep the hunk lines (starting with @@) and the lines starting with + or - (no extra context lines). This is similar to the format used by the patch fields in GitHub's API.

Example:

@@ -15,1 +15 @@ if TYPE_CHECKING:
-    from dda.utils.git.commit import Commit
-    from dda.utils.git.commit import CommitDetails
+    from dda.utils.git.commit import Commit, CommitDetails

ChangeType ¶

ADDED ¶

ADDED = 'A'

MODIFIED ¶

MODIFIED = 'M'

DELETED ¶

DELETED = 'D'

Remote ¶

url ¶

url: str

The URL of the remote.

protocol ¶

protocol: str

The protocol of the remote.

hostname ¶

hostname: str | None

The hostname of the remote.

port ¶

port: int | None

The port of the remote, or None if not specified.

username ¶

username: str | None

The username of the remote, or None if not specified.

org ¶

org: str

The name of the organization the remote belongs to.

repo ¶

repo: str

The name of the repository.

full_repo ¶

full_repo: str