fixup! Add an AGENTS.md file to help with AI-assisted debugging/development

This adds an extensive section about resolving merge conflicts during
rebases, which happens quite often in Git for Windows' day-to-day.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

Author: dscho

.gitattributes

@@ -7,6 +7,7 @@
 *.py text eol=lf diff=python
 *.bat text eol=crlf
 *.png binary
+/AGENTS.md conflict-marker-size=32
 CODE_OF_CONDUCT.md -whitespace
 /Documentation/**/*.adoc text eol=lf whitespace=trail,space,incomplete
 /command-list.txt text eol=lf

AGENTS.md

@@ -415,6 +415,310 @@ git commit -sm "fixup! release: add Mac OSX installer build" path/to/file
 
 ## Rebasing Workflow
 
+Rebases are the bread and butter of Git for Windows: topic branches are
+rebased every time upstream Git releases a new version. This section covers
+the workflow for managing downstream patches through repeated rebases.
+
+### Merging-Rebases
+
+Git for Windows uses "merging-rebases" to maintain downstream patches. Unlike
+a flat series of commits, the downstream changes are organized as topic
+branches merged together, preserving the logical grouping of related changes.
+
+Each integration branch (`main`, `shears/next`, `shears/seen`) contains a
+marker commit with the message "Start the merging-rebase to \<version\>". This
+commit separates upstream history from downstream patches. Reference it with:
+
+```bash
+# Find the marker commit
+git log --oneline --grep="Start the merging-rebase" -1
+
+# Reference it using commit message search syntax
+origin/main^{/Start.the.merging-rebase}
+```
+
+When working with merging-rebases:
+
+- **Downstream patches start after the marker**: Use
+  `origin/main^{/Start.the.merging-rebase}..origin/main` to see all
+  downstream commits
+- **Topic branches are merged, not rebased flat**: Each logical feature or
+  fix is a branch merged into the integration branch
+- **Merge commits are preserved**: The rebase recreates the merge structure
+  on top of the new upstream base
+
+To compare downstream patches before and after a rebase:
+
+```bash
+# Compare the old and new downstream patch series
+git range-diff \
+  old-base^{/Start.the.merging-rebase}..old-branch \
+  new-base^{/Start.the.merging-rebase}..new-branch
+```
+
+### Starting a Merging-Rebase
+
+To rebase the downstream patches onto a new upstream version, create a marker
+commit and use it as the base for an interactive rebase:
+
+```bash
+# Variables for the commit message
+tag=v2.53.0
+# The previous marker - this becomes the exclusion point for --onto
+previousMergeOid=$(git rev-parse origin/main^{/Start.the.merging-rebase})
+tagOid=$(git rev-parse "$tag")
+tipOid=$(git rev-parse origin/main)
+
+# Create the marker commit with two parents: the tag and the current tip
+markerOid=$(git commit-tree "$tag^{tree}" -p "$tag" -p "$tipOid" -m "Start the merging-rebase to $tag
+
+This commit starts the rebase of $previousMergeOid to $tagOid")
+
+# Graft the marker to appear as if it has only the tag as parent
+git replace --graft "$markerOid" "$tag"
+
+# Use the marker as the base for rebasing (only commits after previousMergeOid)
+git rebase -r --onto "$markerOid" "$previousMergeOid" origin/main
+
+# After the rebase completes, delete the replace ref
+git replace -d "$markerOid"
+```
+
+The marker commit is created with two parents: the upstream tag and the
+current branch tip. The `git replace --graft` makes Git see only the tag as
+parent during the rebase, allowing the downstream commits to be cleanly
+rebased onto the new upstream. After the rebase completes, the replace ref
+is deleted to clean up.
+
+#### The shears/* Branches
+
+Upstream Git has four integration branches: `seen`, `next`, `master`, and
+`maint`. Git for Windows maintains a corresponding `shears/*` branch for each
+(`shears/seen`, `shears/next`, `shears/master`, `shears/maint`) that
+continuously rebases Git for Windows' `main` onto the respective upstream
+branch.
+
+These branches are updated incrementally rather than from scratch, avoiding
+re-resolution of merge conflicts. The update process leverages reachability:
+
+1. **Integrate new downstream commits**: If `origin/main` has commits not yet
+   in the shears branch, rebase them on top (using `-r` to preserve branch
+   structure). Update the marker commit's message and second parent.
+
+2. **Integrate new upstream commits**: If the upstream branch has commits not
+   yet integrated, rebase onto the new upstream tip. Update the marker commit
+   accordingly.
+
+The marker commit's second parent always points to the current `origin/main`
+tip, making it trivial to identify what downstream commits are included.
+Similarly, the marker's first parent (the upstream base) shows exactly which
+upstream version is integrated.
+
+### When to Skip a Patch
+
+Use `git rebase --skip` when the patch is already in the new base:
+
+- **Upstreamed**: The patch was accepted upstream and is now in `seen`
+- **Backported**: A fix we backported is now included in the upstream base
+- **Superseded**: HEAD already contains evolved code that includes this
+  change
+
+Signs to skip rather than resolve: HEAD has the functionality, the
+conflict would discard the patch entirely, or `git range-diff` shows
+the downstream and upstream patches are equivalent.
+
+To find the corresponding upstream commit for a conflicting patch:
+
+```bash
+git range-diff --left-only REBASE_HEAD^! REBASE_HEAD..
+```
+
+### Resolving Merge Conflicts
+
+When resolving merge conflicts during a rebase (especially when squashing
+fixups), the goal is to **apply the minimal surgical change** that the
+patch intended, not to reconstruct entire functions or add duplicate code.
+
+#### 1. Understand What the Patch Wants
+
+First, examine the patch being applied:
+
+```bash
+git show REBASE_HEAD
+```
+
+Look at the actual changes (lines starting with `-` and `+`):
+- What lines are being removed?
+- What lines are being added?
+- What is the context (function name, nearby code)?
+
+**Key insight**: The patch shows the *intent*---a specific small change to
+make. Focus on this, not on the conflict markers' content.
+
+**Code movement detection**: If the patch shows large changes, check with
+`--ignore-space-change`:
+
+```bash
+git show <conflicted-commit> --ignore-space-change
+```
+
+This reveals whether the commit is primarily **moving code** (lots of
+whitespace changes) or making **logic changes** (actual code modifications).
+When code was moved and re-indented, focus only on the non-whitespace
+changes when resolving the conflict.
+
+#### 2. Understand Where the Code Is Now
+
+The conflict occurred because the code moved or changed since the patch was
+created. Find where that code actually exists now:
+
+```bash
+# If the patch was changing a specific pattern, find all occurrences
+git grep -n "pattern from patch"
+
+# View the conflicted file around those locations
+```
+
+**Common mistake**: Assuming the conflict markers show you what to do. They
+do not---they just show where Git got confused.
+
+#### 3. Apply the Surgical Change
+
+Make **only** the change the patch intended, but in the current location:
+
+- If the patch adds `--abbrev=12` to a range-diff call, find where that
+  range-diff call is NOW and add it there
+- If the patch changes a `.split()` pattern, find where that pattern is NOW
+  and change it
+- Do not copy entire functions from the conflict markers
+- Do not create duplicates
+
+#### 4. Remove ALL Conflict Markers
+
+Conflict markers make the file invalid code:
+```
+<<<<<<< HEAD
+=======
+>>>>>>> commit-hash
+```
+
+**All three types of markers must be completely removed.**
+
+#### 5. Verify the Resolution
+
+**Critical**: After staging your resolution, verify it matches the patch
+intent:
+
+```bash
+# Compare your staged changes to the original patch
+git diff --cached
+git rebase --show-current-patch
+
+# Or more directly, compare to REBASE_HEAD
+git diff --cached
+git show REBASE_HEAD
+
+# For code that was moved/re-indented, ignore whitespace
+git diff --cached --ignore-space-change
+git show REBASE_HEAD --ignore-space-change
+```
+
+**Verify, verify, verify**: The output of `git diff --cached` should
+correspond closely to the diff in `git show REBASE_HEAD`. The line numbers
+and context will differ (because code moved), but the actual changes (the
+`-` and `+` lines) should match the patch intent.
+
+**After completing a rebase**, always verify the final result:
+
+```bash
+# Compare tree before and after rebase
+git diff @{1}
+
+# Shows what changed in each rebased commit
+git range-diff @{1}...
+```
+
+If the rebase was onto the same base commit (e.g., squashing fixups), the
+`git diff @{1}` should be empty---this proves the rebase only reorganized
+commits without changing the end result. If the rebase was onto a new base
+commit (e.g., rebasing onto a new upstream release), the diff should match
+the difference between the old and new base commits, modulo any changes
+from upstreamed or backported patches. The `git range-diff @{1}...` shows
+the intended amendments (like adding `--abbrev=12`) were correctly applied
+to each commit.
+
+### Conflict Resolution Red Flags
+
+These indicate you are doing it wrong:
+
+- Your diff adds hundreds of lines when the patch only changed 3
+- Conflict markers remain in the file
+- Functions appear twice in the file
+- You added `<<<<<<< HEAD` or `=======` to the staged changes
+- Syntax check fails after resolution
+
+### Key Conflict Resolution Lessons
+
+1. **Context changes, intent does not** - The patch's line numbers are
+   wrong, but the change is right
+2. **Conflict markers lie** - They show you where Git got confused, not
+   what you should do
+3. **One change at a time** - If the patch adds one line, your resolution
+   should add one line
+4. **Verify, verify, verify** - `git diff --cached` should match
+   `git show REBASE_HEAD` (modulo context)
+5. **Post-rebase verification** - `git diff @{1}` (empty) and
+   `git range-diff @{1}...` (shows amendments)
+6. **Ignore whitespace for code moves** - Use `--ignore-space-change` to
+   see the actual logic changes when code was moved and re-indented
+7. **When in doubt, look at the range-diff** - `git range-diff` shows if
+   you matched the intent
+
+### Useful Rebase Tools
+
+- `git rebase --show-current-patch` - See what change is being applied
+- `git show REBASE_HEAD` - Alternative to above, works better with
+  `--ignore-space-change`
+- `git show <commit> --ignore-space-change` - See only logic changes, not
+  whitespace/indentation
+- `git grep -n "pattern"` - Find where code moved to
+- `git log -L <start>,<end>:<file> REBASE_HEAD..HEAD` - See how upstream
+  modified a line range since the original patch; invaluable for
+  understanding how conflicting lines changed
+- `git diff --cached` - After staging resolution, verify it matches
+  REBASE_HEAD
+- `git diff @{1}` - After rebase, compare tree before/after
+- `git range-diff @{1}...` - After rebase, verify intended changes were made
+- `git range-diff A^! B^!` - Compare original patch to your resolution
+
+### Leveraging Rerere
+
+Git's "reuse recorded resolution" (`rerere`) feature automatically records
+how you resolve conflicts and replays those resolutions when the same
+conflict recurs. This is invaluable for repeated rebases where the same
+downstream patches conflict with similar upstream changes.
+
+When you see `Staged 'file' using previous resolution`, Git has applied a
+previously recorded resolution. Always verify these auto-resolutions are
+still correct---upstream context may have changed enough that the old
+resolution no longer applies cleanly.
+
+To enable rerere:
+```bash
+git config --global rerere.enabled true
+```
+
+### Automation Tips
+
+When running rebases in automated or scripted contexts, disable the pager
+to avoid hangs:
+
+```bash
+GIT_PAGER=cat git range-diff ...
+# or
+git --no-pager log ...
+```
+
 ### Fixup Commits
 
 Downstream patches sometimes require adjustment due to changes in the