Git

The Git module.

class confirm.tools.git.GitCommits(repo='.', rev=None)

This class can be used to work with Git commits, mainly to validate them and create a changelog out of Git commit messages.

When the rev parameter is omitted, the revision range is automatically determined.

See also

The man page gitrevisions(7) describes revisions and ranges for Git revisions pretty well.

Parameters:

  • repo (str) – The path to a Git repository (working copy)

  • rev (None or str) – An alternative revision

build_markdown(prefixes='FEATURE FIX TEST DOC', newline='\n', commit_format='- {message} {flags} *– {sha}*')

Build a Markdown changelog for all commits with certain subject prefixes group them in sections.

Hint

If no rev is defined, the last_tag_rev() is used as default.

Parameters:

  • prefixes (str) – The subject prefixes of the filtered commits

  • newline (str) – The newline character

  • commit_format (str) – The format for the commits

Returns:

The markdown changelog

Return type:

str

build_markdown_section(prefix, newline, commit_format)

Build a Markdown changelog section for Git commits with a certain prefixed subject.

Parameters:

  • prefix (str) – The subject prefix of the filtered commits

  • newline (str) – The newline character

  • commit_format (str) – The format for the commits

Returns:

The markdown section

Return type:

str

find_commits(prefix, rev)

Find all commits with a certain prefix. Please note the prefix param is case sensitive.

See also

GitPython method git.repo.base.Repo.iter_commits().

Parameters:

  • prefix (str) – The commit’s subject prefix

  • rev (None or str) – An alternative revision

Returns:

The commits

Return type:

generator

property last_tag

The last Git tag, automatically determined from the current HEAD. In case the HEAD contains a tag (i.e. the current commit is a tag), then the last tag before this commit is returned, so that the changelog is based on the last tag. If there’s no tag available, None is returned.

Returns:

The last tag or None

Return type:

None or str

property last_tag_rev

The Git revision range which is automatically determined, based on the current HEAD and the last tag. In case there’s a tag available, the revision looks like {LAST TAG}..HEAD. If there’s no tag available, then only HEAD is returned.

Returns:

The auto revision range

Return type:

str

validate_commits()

Validate the commit messages for their format.

Hint

If no rev is defined, {default}..HEAD is used, where {default} matches the defaultBranch branch of the Git config. If the git config has no defaultBranch, main is used as default.

Note

Currently the commit is validated for the following rules:

  • The length of the summary line

  • The length of the description lines

  • A valid prefix the summary

  • An initial uppercase letter in the summary

  • An absent trailing dot and whitespace in the summary

Returns:

The amount of errors

Return type:

int

class confirm.tools.git.GitRepo(repo='.')

This class can be used to work with Git repositories.

Parameters:

repo (str) – The path to a Git repository (working copy)

prune(force)

Prune local & remote branches.

Parameters:

force (bool) – Delete local branches irrespective of their merged status

prune_local(force)

Prune local branches with gone remote tracks.

Parameters:

force (bool) – Delete local branches irrespective of their merged status

prune_origin()

Prune remote branches.

confirm.tools.git.PREFIXES = {'BUILD': 'Build Changes', 'CI': 'Pipeline Changes', 'CLEANUP': 'Clean-ups', 'DOC': 'Documentation', 'FEATURE': 'Features', 'FIX': 'Bug Fixes', 'MISC': 'Miscellaneous Changes', 'REFACTOR': 'Refactoring', 'REVERT': 'Reverted Commits', 'STYLE': 'Style Changes', 'TEST': 'Tests'}

The allowed / known prefixes.

confirm.tools.git.HIGHLIGHT_WORDS = ('WARN', 'WARNING', 'IMPORTANT', 'BREAK', 'BREAKING', 'DEPRECATE', 'DEPRECATED', 'DEPRECATION')

The words which will highlight a commit in the changelog.

confirm.tools.git.SHA_DIGITS = 8

The number of SHA digits in the changelog.

confirm.tools.git.SUMMARY_FORMAT = re.compile('(?P<prefix>[A-Z]+): [A-Z].+\\w$')

The regular expression to validate the format of the Git summary.

confirm.tools.git.MAX_SUMMARY_LINE_LENGTH = 50

The max allowed line length of the Git message summary.

confirm.tools.git.MAX_DESCRIPTION_LINE_LENGTH = 72

The max allowed line length of the Git message description.