Using git

Packaging work happens in the recipes git repository. This page covers the one-commit-per-package rule, the git hooks installed by just init, and the git commands we use day to day.

If this is your first time using git or GitHub, start with GitHub’s Get started guide, then come back here for aerynOS-specific conventions.

One commit per package

aerynOS requires one commit per package. Each recipe you add or change gets its own commit.

• Do not combine multiple packages into a single commit.
• Do not leave multiple commits for the same package in a pull request.
• A pull request may contain several commits when you add a package plus new dependencies. Each dependency is still its own commit.

libfoo: Add at v1.0.0
libbar: Add at v2.1.0
mypackage: Add at v3.4.5

This keeps reviews focused, makes git bisect useful, and keeps the history readable. The same rule applies to updates and fixes: one package, one commit.

If you need to change a package after you have already committed it, fold those changes into the existing commit instead of adding a second one. See Amending an existing package commit.

Do not squash a multi-package PR into one commit

When a pull request contains several packages, keep each package as its own commit. Squashing the branch into a single commit before merge hides which files belong to which package.

Git hooks

The prerequisites page has you run just init in the recipes repository. That installs two git hooks that run automatically when you commit:

Hook	What it does
prepare-commit-msg	Prefills the commit title from the staged recipe so you start from name: Add at v<version>, name: Update to v<version>, or [NFC] name:.
pre-commit	Runs package checks on the files you staged. Common packaging errors reject the commit until you fix them.

Commit from the recipe directory so the hooks can see the recipe:

chpkg nano
git commit

The prepare-commit-msg hook looks at the staged stone.yaml and manifest.x86_64.jsonc in the current directory and chooses a title:

• name: Add at v<version> when this is the first release of the package
• name: Update to v<version> when the version changed
• [NFC] name: when stone.yaml changed but the package was not rebuilt (no new manifest)
• name: for other recipe changes, such as a fix that you then describe

Edit the prefilled title and complete the rest of the commit message before saving.

Committing a package

After you have built and tested the package:

chpkg nano
git status
git diff
git add stone.yaml manifest.x86_64.bin manifest.x86_64.jsonc monitoring.yaml
# include pkg/ if you added patches or other extra files
git add pkg/
git commit

Complete the commit message in the editor, then move to the next package if you have one and repeat. Each package is a separate git add / git commit cycle.

Stage only the current recipe

Stay inside the package directory and add paths relative to it. That avoids accidentally staging unrelated work from another recipe on the same branch.

Amending an existing package commit

To change a package you have already committed on this branch — review feedback, a missed file, or a rebuild — stay in that recipe directory and run fixup-recipe-commit. It is only for amending an existing package commit. Create the first commit with git add and git commit.

chpkg nano
# make the additional edits and rebuild if the recipe changed
fixup-recipe-commit

The helper (bash and zsh, after Prerequisites) stages the recipe files, fixups the last commit that touched this directory, and autosquashes it. If you have already pushed the branch:

git push --force-with-lease

Caution

Do not run this unless the package already has a commit on your branch. Without one, it can fixup an unrelated older commit that last touched the directory.

Common git commands

These are the commands we use most often while packaging. Pair them with the helper functions from Prerequisites (gotoaosrepo, chpkg) and the branch setup in Preparing for packaging.

Moving around and inspecting

Command	What it does
gotoaosrepo	Jump to the recipes repository root.
chpkg <name>	Jump to that package’s recipe directory.
git status	Show staged, unstaged, and untracked files.
git diff	Show unstaged changes.
git diff --staged	Show staged changes that will go into the next commit.
git log --oneline	Show recent commits.
git log -1 -- .	Show the latest commit that touched the current directory.
git branch -a	List local and remote branches.

Updating main and creating a branch

gotoaosrepo
git switch main
gh repo sync yourusername/yourfork -b main
git pull
git switch -c update-nano

Use add-packagename or update-packagename as the branch name. See Preparing for packaging for the full recap.

Committing and sharing

Command	What it does
git add <files>	Stage recipe files for the current package.
git commit	Create a commit. The prepare-commit-msg hook prefills the title.
git push -u origin HEAD	Publish the current branch to your fork.
git push --force-with-lease	Update a branch you have already pushed after a rebase.
git gone	Delete local branches whose upstream branch no longer exists. Set this alias up in Prerequisites.

Once the branch is on your fork, open the pull request on GitHub. Submitting a PR covers commit message format and pull request descriptions.

Handling review feedback

Stay on the pull request branch, change the package that was requested, and amend that package’s existing commit. Do not add a second commit for the same package.