Controlling patch generation

When syncing the content of a source-git repo to dist-git, distribution commits from source-git are converted to patch files in dist-git using git format-patch, and the patch files are added to the spec-file with indexing starting from 1.

This process can be customized with the help of Git-trailers added to the end of commit messages. The value of these Git-trailers is expected to be a valid YAML value.

When a source-git repo is initialized with packit source-git init, the Git-trailers bellow are used to capture the name, ID and patch-status from dist-git. This way existing distribution patches don't produce any change in dist-git when they are transformed and synced back.

Controlling patch generation with Git-trailers deprecates the source-git patch metadata mechanism in flavor of a Git-native format. This old patch metadata format is still supported if none of the Git-trailers bellow are found in any of the distribution commits.

Patch-name

This can be used to change the name of a patch-file from the one generated by git format-patch. To merge multiple adjacent commits in a single patch file, specify an identical Patch-name for each of them.

When merging multiple adjacent commits to a single patch file, Git-trailers which control the way in which patches are added to the spec-file (Patch-id, Patch-status, Patch-present-in-specfile) are ignored for all commits except the first (oldest) one.

If no Patch-name is present, the one generated by git format-patch is left unchanged.

Example:

Patch-name: downstream.patch

Patch-id

This is to control the numerical ID used in the patch-tag when adding the patch to the spec-file. If none is specified, the previous ID is incremented. The ID of the first distribution patch is 1, unless otherwise specified.

The number of digits used for the IDs can be controlled with the patch_generation_patch_id_digits configuration option.

The following Git-trailer

Patch-id: 100

results in a following patch-tag in the spec-file:

Patch100: distribution.patch

Patch-status

This is to specify the comment lines to be included before the patch-line in the spec-file, to serve as patch status (clarifying the purpose of the patch downstream).

If none is specified, the commit message of the distribution commit is going to be used, after all Git-trailers are stripped.

To specify a pre-wrapped multiline string, use a YAML block scalar. To include empty lines, prepend each line with # .

For example, the following Git-trailer:

Patch-status: |
    # This is a patch status.
    # Having multiple lines.
    #
    # With some empty lines, even.

Will be rendered as bellow in the spec-file:

# This is a patch status.
# Having multiple lines.
#
# With some empty lines, even.
Patch2: downstream.patch

Patch-present-in-specfile

This tells whether the patch generated from the commit is already in the spec-file. The value is a YAML Boolean. If True, the spec-file is not updated with this patch. Defaults to False.

Ignore-patch

If True, no patch-file is generated from this commit. False if not specified.

No-prefix

Strip source and destination prefixes from diffs. This is the same as running git format-patch --no-prefix.