Make git to track auto-generated files but ignore from diff

Question

I have a repository with source code (mostly *.php, *.js) and documentation files (mostly *.md, *.html, *.svg) that are automatically generated from annotations. All documentation resides in a seperate sub-directory (./doc) within the repository.

On the one hand side, I want the documentation to be tracked via git and I want it to be committed/pushed to the server if it changes, because the it is vary comfortable to have a browsable and up-to-date documentation which is nicely displayed by github.

On the other hand side, it is very annoying to see the auto-generated files during an output of the git diff command. For example, if one line of source code is changed between two commits, then the git diff does not only output this single line but all auto-generated documentation, too, because the whole auto-generated documentation has changed.

Is there any way how to tell git to track the documentation but exclude it from diff by default? I would also be OK for me if git would consider all documentation files as blobs. Then at least diff would only claim that the files have changed, but not display all the documentation line-per-line.

Answer 1

I would also be OK for me if git would consider all documentation files as blobs.

You can use attributes for this. Just create a file doc/.gitattributes which contains * -diff, and then everything under that path will be treated as binary for diffs. See man gitattributes for details.

You can use git diff --text to override that when you do want to see their diffs.

Answer 2

I initially suggested a solution involving a local modification (updating the index (git update-index) of doc/ files in order to not detect any diff)

cd doc
git ls-files -z | xargs -0 git update-index --assume-unchanged

But, the OP rightly comments:

After --assume-unchanged, the files are not included into a commit either until I undo the change to the index via --no-assume-unchanged.
Hence, I must assure to call both directly before and after each git diff.

I was looking for a solution that is more kind of "permanent". A solution that works for every user who checks out the repository without paying particular attention and that also works within Github.
At the moment I cannot really use the "show history/difference" feature of Github, because Github stops to show the differences after processing a certain number of files and unfortunately it only shows the irrelevant part of changes in the auto-generated documentation but not in the actually important files

I agree.
Then another option is to isolate all those doc/ files in their own repo by:

• creating a submodule from the subfolder doc/,
• referencing that submodule in your current repo (which means GitHub will show docs as a gitlink, see "gray subfolder in GitHub")

That way (after a git submodule update --init), you can work in your main repo, and generate docs whenever you want: a git diff will only show the diff of the main (parent) repo, not the ones in (the submodule) doc/.

But when you push your main repo, you must first add, commit and push in doc/ (the submodule), before adding, committing and pushing the main repo.
That is because doc/ is seen by the main repo as a gitlink (a SHA1, special entry in the index), which will change when you commit in doc/, and which needs to be recorded by the main repo referencing it.