Interaction between pre-commit hook and git commit <pathspec>

Hello, folks,

The documentation for the pathspec option of the commit command claims: "The contents of these files are also staged for the next commit on top of what have been staged before." However, that appears to only be true if the pre-commit hook doesn't modify the index contents.

Here's an example pre-commit script:
    #!/bin/sh
    
    git diff --staged --name-only | while read -r file
    do
      {
        git cat-file blob :"$file"
        echo '# Extra text'
      } |
        {
          echo -n "100644 blob "
          echo -n $(git hash-object -w -t blob --path "$file" --stdin)
          echo -e "\t$file"
        } |
          git update-index --index-info
      echo '# Extra text' >> "$file"
    done

This always appends "# Extra text" to the end of any staged files, in both the index and the worktree. It serves to illustrate the issue, without getting into the weeds of what my pre-commit hook is doing. Suffice to say that my hook is (sometimes) modifying files in both the index (to make sure the updated contents are committed) and the worktree (to reduce spurious diffs when file contents are changed).

Here's a set of steps to reproduce the issue:
1. Create a new repository with `git init'
2. Set up the pre-commit script above
3. Create a file and commit it
4. Modify that file
5. Run `git commit <file path>'
6. See that the worktree includes the pre-commit changes, but the index
   is missing them.  Alternatively, see that running `git add <file>'
   results in that file having no changes.

If any other files are already staged between steps 3 and 5, those are included in the commit and the index includes the pre-commit changes. Additionally, adding the file and then committing without specifying a file path results in the expected behavior: both the index and worktree end up with the pre-commit changes.

Are these differences in behavior intentional?

It's possible that there is a better way to achieve my goal than a pre-commit hook. I'm open to suggestions. However, anything that would run per-file instead of per-commit will likely be too slow to use in our (~4x the Linux kernel repository by file count) repository, at least for some large commits.

Thank you, Kevin

Kevin Lyles (he/him) Epic R&D - Hyperspace klyles@epic.com