Repository Git Workflow
Categories:
Repository Git Workflow: Linear History
This page documents the preferred repository workflow for RawCull documentation changes: branch-based development, signed commits when configured, rebasing onto main, and fast-forward integration without merge commits.
Create a Branch
git checkout -b <new-branch>
git push --set-upstream origin <new-branch>
Daily Workflow
You always work on a dedicated branch. Commit often as you make progress.
Stage changes
git add .
Commit
If you use the Claude CLI, it can generate a Conventional Commits message from the staged diff:
git commit -m "$(git diff --staged | claude -p 'Write a short conventional commit message. Output only the message, nothing else.')"
Claude pipes the staged diff into the claude CLI and returns a single-line message such as feat(cache): add LRU eviction for thumbnail layer. The -p flag runs Claude non-interactively (print mode) so the output can be captured directly into -m.
If you want to review the message before committing, capture it first:
MSG=$(git diff --staged | claude -p 'Write a short conventional commit message. Output only the message, nothing else.')
echo "$MSG"
git commit -m "$MSG"
Repeat staging and committing as often as needed while working.
Push
git push origin <your-branch>
Keep your branch current
If others have pushed to main while you were working, rebase your commits on top of their work rather than merging.
git fetch origin
git rebase origin/main
This puts your commits aside, fast-forwards your branch to the latest main, then replays your commits on top — keeping history a straight line.
Integrate into main (fast-forward)
When your branch is finished and ready to ship, follow this procedure to keep history linear.
1. Update main from the server
git checkout main
git pull --rebase origin main
2. Rebase your branch onto the fresh main
git checkout <your-branch>
git rebase main
3. Fast-forward merge into main
--ff-only makes Git abort instead of creating a merge commit.
git checkout main
git merge --ff-only <your-branch>
4. Push main to GitHub
git push origin main
5. Delete the branch locally
git branch -d <your-branch>
6. Delete the branch on GitHub
git push origin --delete <your-branch>
Using git fetch and git diff
The git fetch command is used to update your local repository with the latest changes from the remote repository without merging them. You can then use git diff to compare the branches.
Step 1: Fetch the Latest Changes
Fetch the latest changes from the remote repository to ensure you have the most up-to-date information.
git fetch origin
Step 2: Compare the Branches
Use the git diff command to compare your local branch with the remote branch.
git diff <local-branch> origin/<remote-branch>
For example, if you want to compare your local main branch with the remote main branch:
git diff main origin/main
Using git log
The git log command can be used to compare commit histories between your local and remote branches. This is useful for seeing which commits are present in one branch but not the other.
Fetch the Latest Changes:
Ensure your local repository is updated with the latest changes from the remote repository.
git fetch origin
Compare Commit Histories:
Use the git log to see the differences in commit histories.
git log <local-branch>..origin/<remote-branch>
For example, to compare your local main branch with the remote main branch:
git log main..origin/main
You can also reverse the comparison to see commits in the remote branch that are not in the local branch:
git log origin/main..main
Using git status
The git status command provides a quick summary of the differences between your local branch and the remote branch.
Fetch the Latest Changes:
Update your local repository with the latest changes from the remote repository.
git fetch origin
Check the Status:
Use git status to see the differences between your local branch and the remote branch.
git status
The output will show messages like “Your branch is ahead of ‘origin/
Pull and track a remote repository
The error means your local branch
git branch --set-upstream-to=origin/<your-branch> <your-branch>
git pull
Or do both in one step:
git pull origin <your-branch>
To avoid this in the future, whenever you create or checkout a new local branch that should track a remote, use:
git checkout --track origin/<your-branch>
Verify linear history
git log --oneline --graph --decorate
A clean linear history shows a straight vertical line with no merge nodes.
Re-sign and remediation
Re-sign the last commit without changing its message
git commit --amend --no-edit -S
Push after re-signing (the commit hash changed)
git push origin <your-branch> --force-with-lease
Fix GPG if signing fails
git config --global gpg.format openpgp
git config --global gpg.program gpg
# Confirm the Key ID is correct (no leading '0x')
git config --global user.signingkey <YOUR_KEY_ID>
# Restart the agent
gpgconf --kill gpg-agent
One-time setup
Run these commands once per machine to configure Git correctly for this workflow.
1. Set your identity
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
2. Verify the remote uses SSH
git remote -v
If the URL starts with https://, switch it to SSH:
git remote set-url origin git@github.com:<user>/<repo>.git
3. Configure GPG signing
# Find your GPG Key ID (the 16-character code after '/' on the 'sec' line)
gpg --list-secret-keys --keyid-format LONG
# Tell Git which key to use (omit the leading '0x')
git config --global user.signingkey <YOUR_KEY_ID>
# Auto-sign all commits and tags
git config --global commit.gpgsign true
git config --global tag.gpgSign true
git config --global gpg.program gpg
4. SSH connection
- Go to github.com/settings/keys and delete the old key.
- Copy your current public key to the clipboard:
pbcopy < ~/.ssh/id_ed25519.pub
- On GitHub: Settings → SSH and GPG keys → New SSH key → paste → Save.
- Test again:
ssh -T git@github.com
5. Test the SSH connection to GitHub
ssh -T git@github.com
A successful response looks like:
Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.
If you get a Permission denied (publickey) error, the most likely cause is a stale key.
6. Enforce linear history (no merge commits)
# Always rebase instead of merge when pulling
git config --global pull.rebase true
# Refuse any merge that would create a merge commit
git config --global merge.ff only
# Simplify first push of a new branch (Git ≥ 2.37)
git config --global push.autoSetupRemote true
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.