git-hunks-experience.md

Experience Using git hunks for Hunk-Level Staging

Question

Tell me about your experience using git hunks?

Response

It was a mixed result. Here's what happened:

What worked: git hunks list gave me a clear view of all the individual hunks across files, and git hunks add with the hunk IDs successfully staged specific hunks from cli.py — I staged the docstring update and the start-browser description change independently.

Where it broke down: I originally planned to split the browserctl changes into two commits — one for the Docker→apple/container migration, and one for the set-default-profile feature. But when I inspected the hunks, many of them were "mixed" — a single hunk contained both migration changes and default-profile changes interleaved together. For example:

• The constants hunk in helpers.py replaced DOCKER_IMAGE_REPO with CONTAINER_IMAGE (migration) and added DEFAULT_PROFILE_FILE (default profile) in the same few lines
• The imports hunk in run_start_browser.py swapped Docker imports for container imports and added get_default_profile
• The epilog hunk in cli.py updated the description text and added set-default-profile to the subcommands list

Since hunks are the smallest unit git hunks can stage, I couldn't split within a hunk. I ended up abandoning the two-commit plan and combined all browserctl changes into one commit.

Takeaway: git hunks is useful when changes are logically separated at the hunk boundary (different functions, different sections of a file). But when two concerns are interleaved within the same lines — which is common when a feature is built on top of a refactor — hunk-level staging isn't granular enough. You'd need git add -p with manual edit (e) to split within a hunk, and even that can be fragile.

---

Follow-up Question

What changes would you suggest to the author of git hunks to make it more usable?

Suggested Improvements

1. File filtering for git hunks list I tried git hunks list scripts/bin/commands/browserctl/run_start_browser.py and got Unknown option. When you have 20+ hunks across 8 files, filtering to one file would reduce noise significantly. Something like git hunks list --file <path> or just positional arguments.

2. Hunk splitting (git hunks split) The core limitation I hit. A hunk that replaces 5 constants with 5 different constants is one hunk to git, but may contain two logical concerns. git add -p handles this with the s (split) and e (edit) options. An equivalent like git hunks split <hunk-id> that breaks a hunk into smaller pieces, or git hunks edit <hunk-id> that opens the hunk in $EDITOR for manual line selection, would have let me actually achieve the two-commit split I wanted.

3. Stable IDs across staging operations When I staged one hunk from run_start_browser.py, the remaining hunk IDs for that file shifted, causing my next git hunks add to fail with "Hunk not found." I had to re-run git hunks list to get the new IDs. Either stable IDs that survive partial staging, or a warning in the output like "Note: remaining hunk IDs may have changed" would help.

4. Batch staging by file git hunks add --file <path> to stage all hunks from a specific file would have saved me from falling back to git add <file> when I decided to take all hunks from a file. Minor convenience, but it keeps you in the git hunks workflow.

The biggest gap is #2 — sub-hunk editing. That's exactly where I gave up and collapsed two planned commits into one. The other three are quality-of-life improvements around the existing functionality.