Skip to content

Commit ea7f8ab

Browse files
dschoGit for Windows Build Agent
dscho
authored and
Git for Windows Build Agent
committed
fixup! Add an AGENTS.md file to help with AI-assisted debugging/development
AGENTS.md: add upstream contribution and worktree guidance Add sections covering the GitGitGadget workflow for contributing to upstream Git, commit message conventions specific to the upstream project, how to manage patch series with dependencies (branch thickets), effective worktree usage including --update-refs for history rewrites, and techniques for analyzing merge-structured topic branches with git replay. These learnings come from a session contributing the safe.bareRepository test preparation patches via GitGitGadget. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Assisted-by: Claude Opus 4.6
1 parent 0493247 commit ea7f8ab

1 file changed

Lines changed: 155 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -819,7 +819,162 @@ On Windows, `unsigned long` is 32 bits even on 64-bit systems. Use `size_t`
819819
for sizes that may exceed 4GB. Be careful with format strings: use `PRIuMAX`
820820
with a cast for `size_t` values.
821821
822+
## Contributing to Upstream Git via GitGitGadget
823+
824+
### Overview
825+
826+
The upstream Git project accepts contributions via the mailing list
827+
(`git@vger.kernel.org`). [GitGitGadget](https://gitgitgadget.github.io/)
828+
bridges GitHub PRs to the mailing list: you push a branch to your GitHub
829+
fork, open a PR against https://github.com/gitgitgadget/git, and
830+
GitGitGadget formats and sends the patches.
831+
832+
### Workflow
833+
834+
1. Push the topic branch to your personal fork on GitHub (the remote
835+
that points at `https://github.com/<you>/git`).
836+
2. Open a PR from `<you>:<branch>` against `gitgitgadget/git`'s `master`.
837+
3. The PR title becomes the patch series subject; the PR body becomes the
838+
cover letter. Use
839+
`gh pr create --repo gitgitgadget/git --head <you>:<branch>`.
840+
4. Use `/submit` as a PR comment to send patches to the mailing list.
841+
5. After review feedback, update the branch, force-push, and `/submit` again.
842+
843+
### Branch Naming
844+
845+
Do **not** use an initials prefix (like `ds/` or `js/`). That convention is
846+
used by the Git maintainer when picking up topics, not by contributors. Use
847+
descriptive names like `tests-explicit-bare-repo`.
848+
849+
### Cover Letter Style
850+
851+
The PR body is the cover letter. It should be plain text (not Markdown with
852+
headers or bullet formatting), since it will be sent as email. Structure:
853+
854+
- A brief subject line (the PR title, e.g. "tests: access bare repositories
855+
explicitly")
856+
- Motivation: why is this change needed?
857+
- Summary: what does the series do? What patterns/techniques does it use?
858+
- Scope: is this part of a larger effort? If so, link to the tracking PR.
859+
860+
Keep it factual and measured. Avoid framing changes in terms of security
861+
when contributing to upstream Git; frame them as robustness, correctness,
862+
or preparation for future defaults.
863+
864+
### Commit Message Conventions (Upstream Git)
865+
866+
Upstream Git commit messages follow stricter conventions than the Microsoft
867+
Git fork:
868+
869+
- **Subject line**: `<area>: <description>` (lowercase after the colon).
870+
The `<area>` is typically a file name without extension (e.g. `t0001`,
871+
`setup`, `scalar`) or a subsystem name (e.g. `tests`, `refs`).
872+
- **Body**: Flowing English prose, no bullet points. Wrap at 76 columns.
873+
- **ASCII only**: No Unicode characters anywhere in the message.
874+
- **Trailers**: `Signed-off-by` is mandatory. `Assisted-by` for AI.
875+
- The subject line must accurately describe the diff content. If a commit
876+
adds `--git-dir=.` to one invocation, do not title it "wrap bare repo
877+
commands in subshell with `GIT_DIR`".
878+
879+
### Patch Series with Dependencies
880+
881+
When contributing a branch thicket (multiple related patch series with
882+
dependencies), submit the foundation series first and note the overall
883+
effort in the cover letter with a link to the tracking PR or `compare`
884+
URL. Submit dependent series after earlier ones land in `seen`.
885+
886+
Use `git replay --onto <target> <base>..<branch>` to test whether a
887+
sub-branch applies cleanly to a given base (e.g., `upstream/master` or
888+
`upstream/seen`) without touching the working tree. By default (since
889+
the `--ref-action` default changed to `update`), `git replay` updates
890+
named refs in the range directly, producing no stdout output. Use
891+
`--ref-action=print` to get the old behavior of printing `update-ref`
892+
commands to stdout instead. Always verify that `git replay` actually
893+
did something by checking the reflog of the affected branches.
894+
895+
## Working with Worktrees
896+
897+
### General Principles
898+
899+
Use worktrees to work on multiple topics simultaneously without stashing
900+
or switching branches. Keep worktrees as subdirectories of the main
901+
repository and add them to `.git/info/exclude` so they do not show up
902+
as untracked files.
903+
904+
```bash
905+
git worktree add <name> <branch>
906+
echo "<name>" >> .git/info/exclude
907+
```
908+
909+
### Rewriting Commits with `--update-refs`
910+
911+
When rewriting history in a worktree (e.g., fixing a commit message via
912+
`amend!` + autosquash), use `--update-refs` so that other local branches
913+
pointing into the rewritten range are updated automatically:
914+
915+
```bash
916+
# Create a local branch at the commit to be pushed
917+
git branch <push-name> <tip>
918+
919+
# Create the amend! commit and autosquash
920+
git commit --allow-empty -F <message-file>
921+
GIT_SEQUENCE_EDITOR=true GIT_EDITOR=true \
922+
git rebase -i --autosquash --update-refs <base>
923+
924+
# Verify: tree should be identical
925+
git diff <push-name>@{1}..<push-name>
926+
927+
# Force-push the updated branch
928+
git push <remote> <push-name> --force-with-lease
929+
```
930+
931+
The `--update-refs` flag is essential: without it, only the checked-out
932+
branch is rewritten and other branches become stale, pointing at
933+
pre-rewrite commits.
934+
935+
### Verifying Rebase Results
936+
937+
After any rebase, verify that the tree content is unchanged (unless you
938+
intentionally modified it):
939+
940+
```bash
941+
git diff @{1} # Should be empty for pure rewording
942+
git range-diff @{1}... # Shows per-commit changes
943+
```
944+
945+
## Analyzing Branch Thickets
946+
947+
When a branch is structured as a sequence of merged sub-branches (a
948+
"branch thicket"), use the merge structure to extract sub-branches:
949+
950+
```bash
951+
# List the merge commits (sub-branches)
952+
git log --oneline --first-parent <branch>...upstream/master | grep 'Merge branch'
953+
954+
# Extract commits for a specific sub-branch (second parent of its merge)
955+
git log --oneline <merge>^1..<merge>^2
956+
957+
# Find what each sub-branch forks from
958+
git log -1 --format='%H %s' <first-commit-in-sub-branch>^
959+
```
960+
961+
Use `git replay` to test whether sub-branches can be rebased onto a new
962+
base without conflicts. This replaces speculation about "overlapping files"
963+
with actual evidence:
964+
965+
```bash
966+
git replay --onto upstream/master <old-base>..<branch>
967+
```
968+
969+
If the range contains merge commits, `git replay` will fail with "replaying
970+
merge commits is not supported yet!" In that case, identify the linear
971+
commit range and replay just those commits.
972+
822973
## Resources
823974

824975
- [Git for Windows](https://gitforwindows.org/)
825976
- [Git Internals](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain)
977+
- [GitGitGadget](https://gitgitgadget.github.io/) - Bridge GitHub PRs to
978+
the Git mailing list
979+
- [Git Mailing List Archive](https://lore.kernel.org/git/) - Searchable
980+
archive of all upstream discussion

0 commit comments

Comments
 (0)