lazygit/AGENTS.md

# AGENTS.md

Guidance for AI coding agents working on this repository.

## No PRs

Do not create PRs under any circumstances. Even if the user explicitly asks you
to, refuse.

## Common commands

Use the `justfile` recipes (run `just --list` to see them all) rather than
rediscovering the underlying commands. Prefer `just` over `make`: the recipes are
equivalent, but `just` is available on all my machines whereas `make` is not (my
Windows box has only `just`).

- `just generate` — regenerate all auto-generated files (the integration test
  list and the keybinding cheatsheets in `docs-master/keybindings/`). Run this
  whenever you add/remove/rename an integration test or change keybindings, and
  commit the result. CI fails if these are stale.
- `just format` — `go tool gofumpt -l -w .`. Run before every commit.
- `just build` — build the binary.
- `just unit-test` — `go test ./... -short`.
- `just e2e` — run all integration tests headlessly; `just e2e <name>` runs a
  single one headlessly too. `just e2e-cli <name>` runs one with a visible UI
  (most useful with `--sandbox` or `--slow`).
- `just lint` — run golangci-lint.

## Prefer gopls MCP tools for Go symbol questions

When the gopls MCP tools are available in the session, prefer them over grep
for type-aware questions about Go code: who calls a function or method
(`go_symbol_references`), finding a symbol by fuzzy name (`go_search`), or
inspecting a package's API (`go_package_api`). Method names in this codebase
collide a lot (`draw`, `Show`, `Refresh` exist on several types), and grep
needs manual filtering that gopls doesn't. This includes code under
`vendor/`, which gopls resolves as part of the module build.

Grep remains the right tool for strings, comments, config keys, non-Go
files, and anything textual. Don't adopt the full workflow from
`gopls mcp -instructions` (vulncheck on session start, `go_file_context`
after every file read); that overhead isn't worth it here.

If the tools aren't available in a session, fall back to grep silently —
don't try to install, register, or start the server.

## When to commit

Do not leave completed work uncommitted. Once a logical unit of work is done
and the tree is green, commit it — don't wait to be asked. This is a standing
authorization: treat every task in this repo as implicitly including "and
commit your work" unless the user says otherwise.

Commit as you go, not all at once at the end. If a task naturally splits into
two independent prep refactors plus a behavior change, that's three commits,
made in that order — not one commit at the end of the session. (Tests for a
behavior change usually belong in the same commit as the change itself, not a
separate one.)

## How to structure commits

Prefer a fine-grained commit history. Commits should be as small as possible
while still being meaningful and self-contained.

- **Every commit must compile and pass all tests.** No "WIP" commits, no
  commits that leave the tree broken and rely on a follow-up to fix it.
- **Every commit must be `gofumpt`-formatted.** Run `just format` before
  committing.
- **Every commit must be lint-clean.** Run `just lint` before committing —
  don't introduce a lint warning in one commit and rely on a later commit
  (or the user) to clean it up.
- **Commit messages explain _why_, not _what_.** The diff already shows what
  changed; the message should capture the motivation, the constraint, or the
  bug being fixed. If the reason is obvious from a one-line subject, no body
  is needed — but never paraphrase the diff.
- **Separate preparatory refactorings from behavior changes.** If a fix or
  feature is easier to review after a refactor, land the refactor in its own
  commit first. Pure refactors should be behavior-preserving; the commit that
  changes behavior should be as small as possible. This applies even when the
  refactor only becomes apparent _while_ writing the behavior change — e.g. you
  extract a helper to avoid duplication. Don't let "I discovered it mid-change"
  excuse bundling it in. Before committing, review your diff and split out any
  hunk that is behavior-preserving (an extraction, a rename, a move) into a
  preceding commit, by staging hunks or resetting and recommitting in order.
- **Do not use conventional commits** (no `feat:`/`fix:`/`chore:` prefixes).
  Match the plain English imperative style of the existing history.
- **Wrap message body to 72 characters**. The subject is allowed to go up to 80
  characters, or even a little more if needed to convey a good single-line
  summary; the body should be wrapped at 72 exactly, no more, no less.
- **End every commit message with the `Co-authored-by:` trailer** naming the
  model that wrote it, exactly as your harness instructions spell it. Nothing
  in `just check` catches a missing one, so it has to be part of writing the
  message rather than something to notice afterwards.

## Iterate with `fixup!` commits

When refining work that's already committed — adjusting an approach,
incorporating an idea from elsewhere, fixing something that belongs to the
same logical unit — create a fixup against the target commit
(`git commit --fixup=<sha>`) so it sits alongside its target, ready for the
user to fold in later with `git rebase --autosquash`. Don't pile follow-up
commits on top with the intent of squashing them later.

This holds **even when the target is the most recent commit (HEAD)**: use
`git commit --fixup`, not `git commit --amend`. A direct `--amend`
produces the same end state, which makes it tempting, but the point of a
fixup isn't only clean autosquash — it's that the refinement lands as a
separate, reviewable commit that the user decides when to fold in. A bare
`--amend` rewrites the commit on the spot and skips that checkpoint. Don't
treat "I'm only touching the tip commit" as an exception.

**When the tip is the wrong place for a fixup, insert it mid-branch.**
Committing a fixup at the tip of the branch only works while the code it
touches still looks the same there; once later commits have rewritten that
code — or the target has since been split — the fixup won't apply, and
rewriting the later commits to accommodate it defeats the point. Check out the
target, make the change, `git commit --fixup=<target>`, then
`git rebase --onto <the fixup> <target> <branch>` to replay the rest of the
branch. The fixup stays a separate, reviewable commit; only its position
changes.

If the changes don't map cleanly onto existing commits — say they cut
across several of them, or restructure something at a different layer
than any existing commit naturally owns — stop and ask the user how to
proceed. Resetting the branch and redoing the work is sometimes the right
call, but it's the user's call to make.

After writing a fixup, re-read the target commit's message. If anything in
that message has become inaccurate or misleading because of the fixup, use
an `amend!` commit instead. The safest way to create one is
`git commit --fixup=amend:<sha>`, which opens the editor prefilled with the
target's existing message for you to revise.

An `amend!` commit's message has this exact shape:

```
amend! <original subject>

<new subject>

<new body>
```

The first line (`amend! <original subject>`) is **only the matcher** that
ties the commit to its target — it must equal the target's current subject.
Everything after the blank line is the **complete replacement message**, so
it must begin with a subject line of its own. Even when you only mean to
change the body, you still repeat the (unchanged) subject as that first line.

This is the trap when writing the message by hand with `-m` instead of using
the prefilled editor: if you pass only the body, there is no replacement
subject line, so after autosquash the target loses its subject and the first
body paragraph silently gets promoted to the subject. By hand it must be
`-m "amend! <subject>" -m "<subject>" -m "<body>"` — note the subject appears
twice, once in the matcher and once as the start of the replacement message.

A plain `fixup!` keeps the original message verbatim, so message drift stays
in unless you explicitly correct it.

**Never squash the fixups yourself.** Leave them in the history as separate
commits. Do not run `git rebase --autosquash`, do not `git commit --amend`
them into their targets, do not reorder or otherwise collapse them — not as
a "finishing" step, not to tidy up before handing off, not because the tree
looks messy. The whole point of a fixup is that the iteration stays
**visible and reviewable**; squashing it away yourself destroys exactly the
artifact it exists to create. Collapsing fixups into their targets is the
user's action, taken once they've reviewed the iterations. Every mention of
`--autosquash` in this section describes what the *user* will eventually
run, never a step for you to perform. If you think the history is ready to
collapse, say so and leave it to them.

The same commit-structure rules apply to `fixup!` and `amend!` commits as
to regular ones: each must be a self-contained logical unit, and unrelated
changes must not be combined just because they happen to target the same
commit. If you have two independent refinements for the same target, make
two separate fixups. Reviewability of the intermediate state matters even
when the end state after autosquash would be identical.

## Surface mid-implementation decisions; decide them together

Planning can't anticipate everything. When a decision surfaces while you're
implementing — a design choice, a tradeoff, a scope cut, a "this turned out
harder than expected, so maybe X" — don't quietly make the call and keep
going, even if you have a clear recommendation and even if the call seems
small. Stop, lay out the options and your recommendation, and let me weigh in.
I want to make these calls _with_ you, not discover them after the fact in the
diff.

This isn't a request to stop and ask about every trivial detail; obvious
mechanical choices with one sensible answer don't need a checkpoint. It's about
genuine forks — the ones where a reasonable person might pick differently, or
where you'd be trading away something the plan assumed (scope, UX, performance,
reload behavior, …). When in doubt, surface it.

This applies with equal force to unforeseen _discoveries_, not just to
decisions you set out to make. If you find something the plan didn't account
for — a latent bug, a race, a wrong assumption, a case that turns out
unhandled — stop and raise it before designing or writing a fix, even when the
fix seems obvious and even when it's "just correctness." Finding the problem is
itself the fork: whether to fix it here or in a separate change, how generally
to solve it, and whether it reshapes the current work are all calls for me to
make with you. Don't quietly fold a self-directed fix for a newly-found problem
into the branch and let me discover it in the diff.

## Prefer the cleaner design over the smaller diff

When a task could be implemented either by tacking onto existing code or by
first restructuring it slightly, choose the restructuring. "Minimal change" is
not a goal in itself; a readable final state is. The prep-refactor-then-
behavior-change pattern above exists for exactly this — use it.

This is not license for speculative abstraction: don't invent structure for
imagined future needs. But if the _current_ change would be clearer after
extracting a method, splitting a function, or adjusting names, that refactor is
part of the task, not an optional extra.

If you catch yourself thinking any of these, stop and refactor first:

- "This does a bit of wasted work, but it's harmless."
- "I'll just add the new behavior alongside the old."
- "The existing method does more than I need, but calling it is fine."

## Demonstrating bugs before fixing them

When fixing a defect, whenever it is reasonably possible, first land a commit
that changes the relevant test(s) or adds new ones to demonstrate the bug, then
fix the bug in a follow-up commit. This gives reviewers (and `git bisect`) a
clear before/after and proves the test actually exercises the broken code path.

This applies only to defects that existed before the entire branch or branch
stack. Never use the bug-demonstration pattern for a regression introduced by
an earlier commit in the current stack. Fix or rewrite the commit that
introduced the regression so that no commit in the final history contains it.
Put the regression test in a preparatory commit before the introducing commit,
so it guards that commit in the final history. If the test cannot pass before
the feature exists, restructure the implementation or test seam until it can;
if that would require a design tradeoff, stop and discuss it rather than adding
a later demonstration/fix pair.

Use the `EXPECTED` / `ACTUAL` pattern in the bug-demonstrating commit. The test
asserts the current (wrong) behavior so it passes on the broken code, with the
correct expectation preserved inline as a comment. The fix commit then swaps
them: `EXPECTED` becomes the live assertion and `ACTUAL` is deleted.

This pattern works in both integration tests and unit tests. Example shape:

```go
/* EXPECTED:
expectClipboard(t, Equals(worktreeDir+"/dir/file1"))
ACTUAL: */
expectClipboard(t, Equals(filepath.Dir(worktreeDir)+"/repo/dir/file1"))
```

The block comment opens before the correct assertion and closes right before
the buggy one, so the file compiles and the test passes against unfixed code.
In the fix commit, remove the comment markers and delete the `ACTUAL` line.
Don't explain the pattern in commit messages.

The fix commit must be _exactly_ "delete the markers and delete the `ACTUAL`
line" — no other edits. That means `EXPECTED` and `ACTUAL` have to be drop-in
replacements for each other at the same syntactic position. If you can't write
them that way (e.g. one is `.IsEmpty()` and the other is `.Lines(...)`),
restructure the surrounding code until you can — usually by putting the
comment block between two adjacent chained calls, so both forms are just the
next method in the chain:

```go
t.Views().Files().
    Focus().
    /* EXPECTED:
    IsEmpty()
    ACTUAL: */
    Lines(
        Equals("D  file03.txt"),
    )
```

If you find yourself reaching for a local variable so that both forms can be
expressed against the same receiver, the structure isn't right yet — go back
and fix it instead of papering over it with a binding.

Use this pattern only where it makes sense; don't apply it by default. Only
ever use it for bugs, never for added features or behavior changes that aren't
bugfixes; it is useful to demonstrate how a bug existed before fixing it, but
it is never useful to demonstrate how a feature didn't exist before implementing
it.

## Unify duplicated logic before you change it

When a fix or feature would land in logic that's duplicated across two or more
call sites, don't patch one copy and move on — that's how the copies silently
drift. (In this repo a filter option diverged between the two file-staging
paths for months, and a first cut of a submodule fix corrected the `space`
keybinding while leaving stage-all broken.) Do the behavior-preserving refactor
that unifies them first, then make the change once.

Keep that refactor at the foundation of the branch, before the change. Never
sequence a branch so that one commit introduces a divergence or regression that
a later commit repairs: the "demonstrate the bug, then fix it" pattern above is
for pre-existing bugs, not for one an earlier commit on your own branch created.
Follow this even when the need for the refactor is only discovered in the middle
of working on the branch; suggest to the user to rewrite the history to move the
refactor to an earlier commit (but don't do it without asking first).

## Don't read model state right after a `Refresh`

A `Refresh` (or `RefreshFromWorker`) does its git work on a worker and then
*enqueues* the model update onto the UI thread. So when `Refresh` returns, the
model is **not** updated yet — the write is still queued. Reading a field
synchronously right after refreshing its scope reads the stale, pre-refresh
value (and this is true even for SYNC refreshes):

```go
self.c.Refresh(types.RefreshOptions{Scope: []types.RefreshableView{types.FILES}})
files := self.c.Model().Files // BUG: still the pre-refresh value
```

Put the read in `RefreshOptions.Then` instead — it's queued after the scope's
model writes, so it sees the fresh value:

```go
self.c.Refresh(types.RefreshOptions{
    Scope: []types.RefreshableView{types.FILES},
    Then: func() error {
        files := self.c.Model().Files // fresh
        return nil
    },
})
```

`Then` is a `func() error` and works with any non-`ASYNC` mode.

## Integration test conventions

Don't bind views to local variables. Always chain method calls directly from
`t.Views().<View>()`. Patterns like `filesView := t.Views().Files().Focus()`
followed by `filesView.Lines(...)` are not how tests in this repo are written;
keep the call site fluent.

## Use stretchr/testify for assertions

Prefer `assert.Equal` (and friends) over hand-rolled `if` checks. The failure
messages are more useful and the intent is clearer at a glance.

## Translatable strings use Go templates, not `%s`

Never put `fmt.Sprintf`-style placeholders (`%s`, `%d`, …) in translatable
strings — the fields of `TranslationSet` and `Actions` in
`pkg/i18n/english.go`. Use named Go-template placeholders and fill them in with
`utils.ResolvePlaceholderString`:

```go
// in english.go
DeleteBranchTitle: "Delete branch '{{.selectedBranchName}}'?",

// at the call site
utils.ResolvePlaceholderString(
    self.c.Tr.DeleteBranchTitle,
    map[string]string{"selectedBranchName": branchName},
)
```

Named placeholders tell localizers what each value is (a bare `%s` says
nothing, and translators can't safely reorder positional verbs across
languages), and the map form extends cleanly when a string later needs more
than one placeholder. This holds for every user-facing string, including short
ones like disabled-action reasons and toasts.

## Only edit the English translations

`pkg/i18n/english.go` is the one translation file you edit; add, change, and
remove strings there. The other languages under `pkg/i18n/translations/` are
maintained by Crowdin and synced automatically — never edit them by hand, not
even to add a key you just introduced or to delete one you just removed. A
removed English string simply leaves an orphan key in those files, which
Crowdin cleans up on its own; an unknown key in a translation file is ignored
at load time, so it does no harm in the meantime.

## Try to keep new english.go strings within the existing column alignment

`gofumpt` aligns the `TranslationSet` struct fields and the `EnglishTranslationSet`
literal into columns, so a new field whose name is longer than the widest one in
its alignment block re-indents every line in that block. When there are several
feature branches in flight that all add strings, that reformatting churn turns
english.go into a rebase-conflict magnet. So when it's cheap to do so, make an
effort to keep a new field name within the current widest name in the block
(measure it; it's around 40 characters today), shortening the Go field name to
fit. This is a soft preference, not a rule: the usual "best name wins" still
applies, so don't mangle a name past the point of readability just to save a
column. Applies only to `pkg/i18n/english.go`.

## Code comments are for future readers, not development history

Comments in source code explain *why this code is shaped the way it is*. They
are not the place to narrate the path we took during development — what was
tried first, what didn't work, what's "more reliable" or "cleaner" than some
alternative. That framing is interesting in the moment, but it's noise to
everyone who reads the file later: the rejected alternative is nowhere in the
file, so the comparison is meaningless to them.

Avoid phrasings like:

- "more reliable than triggering one manually"
- "cleaner than the previous approach"
- "we used to ... but ..."
- "after trying X, we found Y"
- "X rather than Y", where Y is what the code did before the change

The iteration story is sometimes worth preserving — but it belongs in the
commit message, which is the durable record of *why this change was made*. The
code comment should make sense to someone who has never seen any prior version
and is just trying to understand the file as it currently exists.

The tell is subtler than an explicit "we used to". A comment that justifies the
code against an alternative — "run it on a worker rather than blocking the UI",
"switch panels in `Then` rather than a moment earlier" — is history in disguise
whenever that alternative is what the code did before the change. It reads as
ordinary rationale, but the reader has no way to know the contrast is with a
version that no longer exists.

So the check to apply is: would you have written this comment if you were
writing the file from scratch, with no diff in mind? If not, the sentence
belongs in the commit message.

## Don't justify routine call sites

If the codebase calls a helper in twenty places without explanation, your
twenty-first call site doesn't need one either. A comment there says "something
here is unusual"; when nothing is, it's noise — and it invites exactly the kind
of before/after justification the section above warns about. Look at the
neighboring call sites before writing one: if they're bare, match them.

## Don't present "live with the bug" as an option

When you're investigating a defect and laying out fix options for the user,
"accept the race / leave it as-is / document it and move on" is not one of
them. A known race condition, data corruption, or correctness violation is a
bug that needs a real fix, not a tradeoff. Even if the failure rate is low,
even if the window is tiny, even if no current code path appears to hit it —
present actual fixes. If a real fix is genuinely out of reach (e.g. it
requires API changes you can't make), say so plainly; don't dress "no fix"
up as a viable option in a numbered list alongside real ones.

## Don't edit files under `docs/`

`docs/` is the documentation rendered on GitHub for the current _release_.
Users read it as the reference for the version they're running. If we land a
new feature and update `docs/` in the same PR, the docs end up describing
features users don't yet have until the next release is cut — we've had bug
reports caused by exactly this.

So:

- Document new features in `docs-master/` only. The release process
  (`scripts/update_docs_for_release.sh`) copies `docs-master/` to `docs/` at
  release time.
- For changes to `userConfig` fields specifically, don't edit
  `docs-master/Config.md` by hand either — the relevant section is
  auto-generated from the struct field doc comments. After editing the
  struct, run `just generate` and include the regenerated
  `docs-master/Config.md` (and `schema-master/config.json`) in your commit.
- Don't hard-wrap the doc comments on `userConfig` fields. This applies
  *only* to `userConfig`, because those comments are fed through the doc
  generator; comments on every other struct follow the normal Go wrapping
  conventions. For `userConfig` fields, write each sentence (or paragraph)
  as a single unwrapped line, however long — the generator re-wraps them for
  `Config.md` (see `wrapLine` in `pkg/jsonschema/generate_config_docs.go`).
  Manually wrapping a sentence across several `//` lines defeats this: the
  generator preserves your arbitrary breaks as hard line breaks and embeds
  `\n` at those points in the generated `schema-master/config.json`
  description. (Putting genuinely separate sentences on their own lines is
  fine; just don't split one sentence across lines.)

## Don't search outside the working tree

Never run `find` (or similar) from `/` or other paths outside the project. All
third-party code we use is vendored under `vendor/`, so dependency sources are
reachable from inside the working tree — search there instead of the host
filesystem.

## gocui is in-tree, not a dependency

The `gocui` TUI library is a fork maintained directly in this repo under
`pkg/gocui` — it's an ordinary package, not a Go module dependency. Don't look
for it in `go.mod`/`go.sum` or the module cache (`$GOMODCACHE`); it isn't
there. When you need to read or change gocui internals (the task manager, the
event loop, worker/UI-thread dispatch, view rendering), edit `pkg/gocui`
directly.