Kevin Lyles reported that the git commit documentation says the contents of files named by a pathspec are staged on top of what was already staged. He found this holds only if the pre-commit hook does not modify the index. His example hook rewrites each staged file with extra text appended, via git update-index --index-info.
Chris Torek explained that the documentation speaks of "the" index, but with git commit --only or --include Git must be able to roll the index back if the commit is aborted. To do this, he said, Git internally needs two or even three indexes for the work tree, so a hook that edits the real index can be working with a different one from the index used for the commit.
Junio Hamano said the hook was designed for validation, to stop an undesirable commit from being created. He suggested two possible steps: clarifying the documentation to say hooks should not try to mutate the index, and detecting and erroring out when a hook does. He said he was not sure the second was feasible.
Kristoffer Haugsbakk said that the githooks documentation for pre-commit reads to him as describing validation or checking, not mutation, and that the reporter's use case does not sound reasonable. No patch has been posted.