From eb87d98ce25bfbfe042d2a681673855c2ca2d714 Mon Sep 17 00:00:00 2001 From: Maja Massarini Date: Tue, 26 May 2026 14:39:54 +0200 Subject: [PATCH 1/2] Add guide for tracking Source files in dist-git MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a how-to that shows how to use the post-modifications action (or pre-sync for URL-based sources) together with files_to_sync to keep small extra Source files in dist-git's VCS rather than uploading them to the lookaside cache on the first sync. Assisted-By: Claude Opus 4.7 (1M context) Co-authored-by: Nikola Forró --- docs/configuration/actions.md | 10 ++ .../downstream/source-files-in-dist-git.md | 139 ++++++++++++++++++ docs/configuration/index.md | 4 +- 3 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 docs/configuration/downstream/source-files-in-dist-git.md diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md index 3b96b9e6a2..4e0ef7eacc 100644 --- a/docs/configuration/actions.md +++ b/docs/configuration/actions.md @@ -168,6 +168,16 @@ Our internal API differentiates between the commit title and description, so we have an additional requirement on separating the commit title by an empty line. You can, of course, provide *just* the commit title. +### `post-modifications` + +This action runs in the release-synchronization workflow after the spec file +has been modified and remote sources have been downloaded into dist-git, but +*before* local `Source` files are collected for the lookaside-cache upload. +You can use it to stage extra files (e.g. systemd units, configuration templates) into +dist-git's Git index so that Packit treats them as VCS-tracked and skips them +when uploading to the lookaside cache. A complete walkthrough is in +[Tracking `Source` files in dist-git](/docs/configuration/downstream/source-files-in-dist-git). + ### `run-condition` :::note diff --git a/docs/configuration/downstream/source-files-in-dist-git.md b/docs/configuration/downstream/source-files-in-dist-git.md new file mode 100644 index 0000000000..805a803244 --- /dev/null +++ b/docs/configuration/downstream/source-files-in-dist-git.md @@ -0,0 +1,139 @@ +--- +title: Tracking Source files in dist-git +sidebar_position: 5 +--- + +# Tracking `Source` files in dist-git instead of the lookaside cache + +By default, every file referenced by a `Source*` tag in the spec file is +uploaded to the lookaside cache during a release synchronization +(`propose_downstream` / `pull_from_upstream`), **unless** the file is already +tracked by Git in the dist-git repository. + +This is the right default for tarballs (`Source0`) and large binary artifacts, +but it is not what you want for small, text-like files that ship together with +the spec file in dist-git, such as: + +- `systemd` unit files (`pkg.service`, `pkg.socket`, …) +- `tmpfiles.d` / `sysusers.d` snippets +- desktop entries (`pkg.desktop`) +- ad-hoc configuration templates referenced from `%install` + +If you simply add such a file as a new `Source` in the upstream spec file and +let Packit propose the update, the file ends up in the lookaside cache the +first time the change is synced downstream. On subsequent updates the file is +already tracked by Git in dist-git, so the issue does not occur again — but the +initial upload is hard to undo. + +This guide shows how to use Packit [actions](/docs/configuration/actions) to +keep a new `Source` file in dist-git's Git history right from the first +synchronization. The same recipe is the recommended workaround for +[packit/packit#2365][packit#2365]. + +## How Packit decides where a `Source` file goes + +When Packit handles sources during release synchronization, it: + +1. downloads remote sources (those with a URL) into the dist-git working + directory, +2. inspects which of those files are already present in dist-git's **Git + index** (`git_tracked_files`), +3. runs the [`post-modifications`](/docs/configuration/actions#post-modifications) + action, +4. collects local sources (without a URL) that exist in the dist-git working + directory but are not in the Git index, +5. uploads everything from steps 2 and 4 to the lookaside cache. + +The key observation is step 2 and step 4: anything that is **already in the +Git index of dist-git** by the time `_handle_sources` runs is excluded from the +lookaside-cache upload. + +## The recipe + +Add the new file to your upstream repository, list it in +[`files_to_sync`](/docs/configuration/#files_to_sync) so that Packit copies it +into dist-git, and use a Packit action to `git add` the file on the dist-git +side **before** sources are processed: + +```yaml +specfile_path: pkg.spec +files_to_sync: + - pkg.spec + - pkg.service # ship the systemd unit alongside the spec +upstream_package_name: pkg +downstream_package_name: pkg + +actions: + # Stage the file in dist-git's Git index so Packit treats it as VCS-tracked + # and does NOT upload it to the lookaside cache. + post-modifications: + - bash -c 'cd "${PACKIT_DOWNSTREAM_REPO}" && git add pkg.service' +``` + +After the first successful `propose_downstream`/`pull_from_upstream` run, +`pkg.service` is committed to dist-git. The action keeps working on subsequent +runs (`git add` of an unmodified, already-tracked file is a no-op), so it is +safe to leave it in the configuration permanently. + +### Which action should I use? + +`post-modifications` runs after upstream archives have been downloaded and +filtered, but **before** local `Source` files are collected for the lookaside +upload. This makes it the natural choice for files referenced as +`Source: pkg.service` (no URL). + +If the file is referenced by a **URL**, e.g. +`Source1: https://example.com/pkg.service`, Packit will treat it as a remote +upstream archive and filter the Git-tracked list *before* `post-modifications` +runs. In that case, use [`pre-sync`](/docs/configuration/actions) instead and +stage the file from `${PACKIT_UPSTREAM_REPO}` into `${PACKIT_DOWNSTREAM_REPO}` +yourself: + +```yaml +actions: + pre-sync: + - bash -c 'cp "${PACKIT_UPSTREAM_REPO}/pkg.service" "${PACKIT_DOWNSTREAM_REPO}/"' + - bash -c 'cd "${PACKIT_DOWNSTREAM_REPO}" && git add pkg.service' +``` + +The variables `PACKIT_UPSTREAM_REPO` and `PACKIT_DOWNSTREAM_REPO` are exposed +to every release-synchronization action — see +[Release-synchronization actions](/docs/configuration/actions#release-synchronization-actions). + +### Multiple files + +For more than one file, list them in `files_to_sync` and stage them in a single +command. Using `git add -- ` keeps the action robust against future +files that match dot-prefixes or unusual names: + +```yaml +files_to_sync: + - pkg.spec + - pkg.service + - pkg.socket + - pkg.sysusers + +actions: + post-modifications: + - bash -c 'cd "${PACKIT_DOWNSTREAM_REPO}" && git add -- pkg.service pkg.socket pkg.sysusers' +``` + +## Verifying the result + +When the synchronization PR is opened in dist-git, check: + +1. the dist-git commit contains the new file (it is *added*, not just present + in the working tree), +2. the dist-git `sources` file is **not** updated to reference the new file, +3. the lookaside cache for the package does not contain the new file. + +If the file still ends up in the lookaside cache, double-check that: + +- the file is listed in `files_to_sync` and the path matches what is in + dist-git after the sync, +- the action runs in `${PACKIT_DOWNSTREAM_REPO}` (the dist-git checkout), not + in the upstream working directory, +- the file is referenced as a plain `Source:` (no URL) — see the note about + `pre-sync` above for URL-based sources. + +[packit#2365]: https://github.com/packit/packit/issues/2365 diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 19cfb93d9b..8d6e462fcf 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -282,7 +282,9 @@ Files to be uploaded to lookaside cache also use this interface, where all files mentioned in the spec file's `Source` are uploaded to the lookaside cache, *unless* the file is already being tracked in dist-git. **Note:** this implies that new `Source` files are [always added][packit#2365] as lookaside cache as part of an -update even if they should be tracked in dist-git instead. +update even if they should be tracked in dist-git instead. See +[Tracking `Source` files in dist-git](/docs/configuration/downstream/source-files-in-dist-git) +for a recipe that keeps such files in dist-git's Git history instead of the lookaside cache. ::: From bbc3d58ad7ab78e1260bfc27bac5f3bb8d610568 Mon Sep 17 00:00:00 2001 From: Maja Massarini Date: Fri, 29 May 2026 14:27:00 +0200 Subject: [PATCH 2/2] Apply review feedback Assisted-By: Claude Opus 4.7 (1M context) --- docs/configuration/actions.md | 13 +++++----- .../downstream/source-files-in-dist-git.md | 25 ++++++------------- 2 files changed, 15 insertions(+), 23 deletions(-) diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md index 4e0ef7eacc..f2d6c2cb23 100644 --- a/docs/configuration/actions.md +++ b/docs/configuration/actions.md @@ -170,12 +170,13 @@ You can, of course, provide *just* the commit title. ### `post-modifications` -This action runs in the release-synchronization workflow after the spec file -has been modified and remote sources have been downloaded into dist-git, but -*before* local `Source` files are collected for the lookaside-cache upload. -You can use it to stage extra files (e.g. systemd units, configuration templates) into -dist-git's Git index so that Packit treats them as VCS-tracked and skips them -when uploading to the lookaside cache. A complete walkthrough is in +During release synchronization (`propose_downstream` / `pull_from_upstream`), +this action runs after the spec file has been modified and remote sources have +been downloaded into dist-git, but *before* local `Source` files are collected +for the lookaside-cache upload. You can use this timing to stage extra files +(e.g. systemd units, configuration templates) into dist-git's Git index so that +Packit treats them as VCS-tracked and skips them when uploading to the +lookaside cache. A complete walkthrough is in [Tracking `Source` files in dist-git](/docs/configuration/downstream/source-files-in-dist-git). ### `run-condition` diff --git a/docs/configuration/downstream/source-files-in-dist-git.md b/docs/configuration/downstream/source-files-in-dist-git.md index 805a803244..4c908c3b3f 100644 --- a/docs/configuration/downstream/source-files-in-dist-git.md +++ b/docs/configuration/downstream/source-files-in-dist-git.md @@ -70,6 +70,14 @@ actions: - bash -c 'cd "${PACKIT_DOWNSTREAM_REPO}" && git add pkg.service' ``` +:::tip Staging multiple files + +Avoid `git add .` or `git add *` — shell globs skip dot-files and can pick up +unrelated paths. List every file explicitly with the `--` separator instead, +e.g. `git add -- pkg.service pkg.socket pkg.sysusers`. + +::: + After the first successful `propose_downstream`/`pull_from_upstream` run, `pkg.service` is committed to dist-git. The action keeps working on subsequent runs (`git add` of an unmodified, already-tracked file is a no-op), so it is @@ -100,23 +108,6 @@ The variables `PACKIT_UPSTREAM_REPO` and `PACKIT_DOWNSTREAM_REPO` are exposed to every release-synchronization action — see [Release-synchronization actions](/docs/configuration/actions#release-synchronization-actions). -### Multiple files - -For more than one file, list them in `files_to_sync` and stage them in a single -command. Using `git add -- ` keeps the action robust against future -files that match dot-prefixes or unusual names: - -```yaml -files_to_sync: - - pkg.spec - - pkg.service - - pkg.socket - - pkg.sysusers - -actions: - post-modifications: - - bash -c 'cd "${PACKIT_DOWNSTREAM_REPO}" && git add -- pkg.service pkg.socket pkg.sysusers' -``` ## Verifying the result