Skip to content

Git 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

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.

changes

added

added: set[Path]

List of files that were added.

modified

modified: set[Path]

List of files that were modified.

deleted

deleted: set[Path]

List of files that were deleted.

changed

changed: set[Path]

List of files that were changed (added, modified, or deleted).

digest

digest() -> str

Compute a hash of the changeset.

from_iter

from_iter(data: Iterable[ChangedFile]) -> Self

Create a ChangeSet from an iterable of FileChanges.

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