14

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.

dreftymac
  • 31,404
  • 26
  • 119
  • 182
user2690527
  • 1,729
  • 1
  • 22
  • 38

2 Answers2

19

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.

Josh Stone
  • 841
  • 9
  • 7
  • This seems to be more straightforward than the accepted answer. It may be reasonable to come back to this and add any pitfalls or drawbacks relative to the accepted answer, if there are any. – dreftymac Sep 09 '16 at 19:21
  • Precisely what I wanted, thank you! – Ravan Scafi Jul 26 '23 at 16:12
1

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:

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.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • But if I understand the solution correctly, after `--assume-unchanged` the files are not included into a `commit` either until I undo the change to the index via `--no-assume-unchanged`. Am I correct? Hence, I must assure to call both directly before and after each `git diff`. So this is only a work-around to temporarily switch off `git diff` for a subtree but it is not a permanent solution. – user2690527 Jun 28 '15 at 15:16
  • @user2690527 I agree. It was one workaround based on Git I could think of, but not a permanent solution. – VonC Jun 28 '15 at 15:22
  • 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. – user2690527 Jun 28 '15 at 17:39
  • @user2690527 Ok. I propose an alternative in my edited answer. – VonC Jun 28 '15 at 17:48
  • That is what I needed. Thank you! – user2690527 Jun 29 '15 at 13:43