graphtage.git

A git external diff driver that formats changes with Graphtage.

Git runs an external diff driver with seven positional arguments:

path old-file old-hex old-mode new-file new-hex new-mode

old-file and new-file are the two revisions to compare. Git usually passes at least one of them as a temporary copy whose name does not necessarily carry the original file extension, so this driver resolves the file type from path, which is the file’s location in the repository. Git appends two more arguments when it detects a rename or a copy, and passes a single argument for an unmerged path; both forms are handled.

Git stops the whole diff when a driver exits with a non-zero status, so this driver reports a successful diff as graphtage.__main__.EXIT_SUCCESS even when the two revisions differ. A status of graphtage.__main__.EXIT_ERROR is reserved for failures that prevent Graphtage from producing a diff at all, such as an unsupported file type or a file that does not parse.

See the “Git Integration” section of the Graphtage README for the git configuration this driver expects.

git functions

absent_revision

graphtage.git.absent_revision(from_path: str, to_path: str) → str | None

Describes a change that leaves Graphtage with only one revision to work from.

Parameters:

from_path – The old revision, which git passes as its second argument.
to_path – The new revision, which git passes as its fifth argument.

Returns:

'added' or 'deleted' if one of the revisions is missing, and None if both of them exist.

Return type:

str | None

main

graphtage.git.main(argv: Sequence[str] | None = None) → int

Runs Graphtage over the two revisions that git supplies.

Parameters:: argv – The command line arguments, including the name of the program. Defaults to sys.argv.
Returns:: graphtage.__main__.EXIT_SUCCESS if the diff was produced, whether or not the revisions differ, and graphtage.__main__.EXIT_ERROR if Graphtage could not produce one.
Return type:: int

mime_options

graphtage.git.mime_options(path: str, forwarded: Sequence[str]) → list[str]

Builds the Graphtage MIME type options implied by a path in the repository.

Parameters:

path – The path of the file in the repository, which git passes as its first argument.
forwarded – The Graphtage options that the user configured, which take precedence over the inferred type.

Returns:

The --from-mime and --to-mime options that are not already covered by forwarded.

Return type:

List[str]

Raises:

ValueError – If the file type of path is unknown or is not supported by Graphtage.

split_options

graphtage.git.split_options(argv: Sequence[str]) → tuple[list[str], list[str]]

Splits the leading Graphtage options off of the arguments that git supplies.

Git appends its own positional arguments after whatever command the user configured, so every argument up to the first one that does not start with - belongs to the user. Two consequences follow: an option that takes a value must spell it with an equals sign, because a value passed as a separate argument is indistinguishable from the first argument supplied by git, and a repository path that starts with - is read as an option.

Parameters:: argv – The command line arguments, excluding the name of the program.
Returns:: The options to forward to Graphtage, followed by git’s arguments.
Return type:: Tuple[List[str], List[str]]