hk pre-commit stash aborts the commit on a transient index.lock, no retry (partial commits)

[k0pernikus]

Drafted with the help of Claude Fable.

On a partial commit — some paths staged, others left modified in the worktree — hk's
stash = "git" step shells out git stash push --keep-index -m hk --include-untracked -- <paths>
exactly once. If the worktree index.lock is held by another process at that moment, the stash
fails and hk aborts the entire commit. The contention is transient: re-running the commit succeeds
as soon as the lock is released, so hk fails on a condition it could recover from by waiting.

Steps to reproduce

Deterministic repro (pins hk 1.50.0 via mise, runs in CI):
https://github.com/k0pernikus/hk-partial-commit-index-lock-repro

1. Partial-stage a commit: one file staged, another modified but unstaged.
2. Hold .git/index.lock while hk's pre-commit stash runs (standing in for a concurrent git
   process, an editor's git integration, or fsmonitor).
3. hk aborts. Re-run the same pipeline with no lock held: it succeeds.

bash reproduce.sh exits non-zero when the bug reproduces, so the CI run is red:
https://github.com/k0pernikus/hk-partial-commit-index-lock-repro/actions/runs/29118283285

Expected vs actual

Expected: a transient index.lock — held briefly by another process, then released — does not
abort the commit. hk tolerates the momentary contention instead of failing on the first attempt, and
fails loud only if the lock persists.

Actual: hk issues git stash push once, propagates the first index.lock: File exists error,
and aborts. No commit is created; the staged changes remain staged.

stash – Running git stash
git error: Unable to create '.../index.lock': File exists.
git error: could not write index
Error: exited with code 1
git stash push --keep-index -m hk --include-untracked -- other.txt
Location:
    src/git.rs:853:17

Root cause

push_stash in src/git.rs runs the shell git stash push and propagates the first error with no
retry, backoff, or lock-wait. On a partial commit the tracked-subset branch takes the shell path —
src/git.rs L842-L853 (jdx/hk@860bda7):

// If partial paths requested, force shell git path since libgit2 does not support it
if let Some(paths) = tracked_subset.as_deref() {
    let mut cmd = git_cmd(["stash", "push", "--keep-index", "-m", "hk"]);
    if *env::HK_STASH_UNTRACKED {
        cmd = cmd.arg("--include-untracked");
    }
    let utf8_paths: Vec<&str> = paths.iter().filter_map(|p| p.to_str()).collect();
    if !utf8_paths.is_empty() {
        cmd = cmd.arg("--");
        cmd = cmd.args(utf8_paths);
    }
    cmd.run()?;

cmd.run()? fails the whole hook on the first index.lock error. The other two shell-stash sites
carry the same no-retry run(): the libgit2 fallback
(L875-L879)
and the no-repo path
(L892-L903).
Full-file commits instead take the libgit2 stash
(repo.stash_save, L862),
which never acquires index.lock through the CLI and is unaffected. This region is unchanged from
the reproduced v1.50.0 to current main (860bda7).

Possible fixes

The case is a transient, recoverable index.lock contention during a partial-commit stash — the
kind a developer resolves by re-running the commit. Any of these would address it:

• Retry the stash on the transient lock error with a bounded backoff, then surface the failure
  loudly if it outlasts the window.
• Wait for the lock to clear before stashing, bounded by a small timeout — git's index operations
  are sub-second.
• The transactional stash-and-rollback direction already discussed in
  #247 / #234.

Environment

• hk 1.50.0 (latest)
• git 2.54.0
• Linux (WSL2)
• stash = "git", committing inside a git worktree

Related discussions

• #247 — RFC: Harden stash/error recovery paths
• #234 — RFC: Stash/restore resilience
• #965 — stash restore corrupts partially-staged files
• #743 — stash modes corrupt binary files on partial commits

[jdx]

Thanks for the detailed report. I opened #1060 with a bounded fix for this:

• resolve the active worktree index lock via git rev-parse --git-path index.lock
• wait up to 775 ms with backoff before shell-based stash operations
• preserve Git’s normal error behavior when a lock persists
• test a lock that is released while hk is running in both libgit2 and shell-Git modes

PR: #1060

This comment was generated by Codex.