How to customize diff git to ignore yard date generation

Question

I'm using yard to generate the documenation of my project. Even thought the documentation can generated and so don't really need to be versionned, we decided to do so, because it makes it easier to see the impact of code (comment) change in the actual documenation.

The problem is each time yard generate the documenation, it changes the date at the beginning of each file resulting in all the files being seen as changed.

Is there a way to either tell git to ignore those line to detect if files have changed or alternatively a way to configure yard to not regenerate file if they are identical ?

Thanks

Update

I know I can do a script or whatever, which clean the files if only the date has changed. So my question is there is a Git way to do , .i.e should I bother read about diff drivers or should I do the clean script.

If I were going toward the cleaning path, would that be better to do so using a git hook or integrating it in the doc generation.

Ultimately, I'm interested in any other way to track changes due to a particular commit in the generated doc.

I haven't really explained what is my problem (and why I am trying to version things which don't need to be) so there we go.

Sometime, a little modification in the code screw up the documentation, therefore I would be able to see the impact of a commit regarding the documentation.

Example : I use modeline for vim (a comment at the first line of a file telling vim different information)

Know I have a file with the documentation of a module

#vi: my vim setting 
# Documentation of module A
module A
  .... some code

end

And somewhere else I use this module

#vi : my vim setting

           ( 2 blank lines)
module A
   .... some different code
end

At that point, everything is fine and the documentation for A would be Documentation of module A. However if some one (like me) delete a blank line in the last file and leave only one (yes I let 2 blanks lines between the modeline and the code), then yard think the modeline is the documentation for module A which will be vi : my vim setting.

The problem is, there is no way to detect the doc as been screwed up, except by looking at every single pages. Using git, I can quickly see and check what as changed and even find when (which is important, because then I can figure out why it changed).

Unseal

Alternate possibility: can you override the yard template footer (in html/footer.erb) to not generate the date? – Metacarpus

Answer 1

Is it sufficient to not have the dates in the files at all?

The yard-specific solution (but not git-specific), if you don't actually use those dates - get yard to not generate them in the first place:

create an empty file in customtemplates/default/layout/html/footer.erb and then include it in your template:

• using the command line

  yardoc --template-path ./customtemplates
  

• using a Rakefile

  YARD::Rake::YardocTask.new do |yardoc|
      yardoc.options = ["--template-path", "./customtemplates"]
  end
  

(Alternately, if you still want an acknowledgement to Yard, you can put the following in the customtemplates/default/layout/html/footer.erb file)

<div id="footer">
     Generated by <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>.
</div>

or you can put in your own footer, with your company logo or other information.

Metacarpus

Answer 2

Not a direct answer, only elements :

• git diff has the -G option to keep only patches that match a certain regexp. There doesn't seem to be a flag to exclude lines matching your date line, but maybe you will be imaginative enough to build a regexp that keeps anything but your date line.
• diff has such an option (diff -I), so if you can figure a way to feed the diff generated by git to diff, you are good to go.
• meld is a graphical diff viewer, which works well enough with git -- e.g. invoking meld dir/ on a directory of your project opens a window displaying all the files having differences with the HEAD -- and which can take regexps to ignore certain lines (Edit > Preferences > Text filters). It is packaged for linux distros (at least for Ubuntu), and the website claims it also runs on MacOS X and Windows (I haven't tried).
• I haven't tried all the available difftools that integrate with git, but they probably offer similar functionalities.

Humeral

I was more thinking about writing a custom driver or a pre-commit filter so git see , at a commit, level file as identical – Unseal

Here the some examples how the second approach might look like #4434846 – Raynard

Answer 3

I'm not familiar with yard but there is no way to make git ignore parts of a file.

The easiest solution would be modifying your build process to run a custom script that removes the data from the generated files or checks the git-diff if only the date was changed and in that case revert the date change.

However, not versioning any generated code/files at all would be much cleaner.

Racehorse

It doesn't hurt to version generated files, so I'm not sure about the "much cleaner". Anyway, my point of doing it is to be able to spot easily problems and what has changed during generation. – Unseal

Answer 4

Don't Do That

Assets that can be regenerated from source should not be versioned. It's a bad idea for exactly the reasons you're experiencing:

1. Your history tracks changes you don't care about.
2. You have to make an effort to ignore trivial changes that are irrelevant to your commit history.
3. You waste repository space and processing time on data that can be regenerated on demand.

See https://mcmap.net/q/1067037/-should-i-version-control-the-minified-versions-of-my-jquery-plugins for a related discussion on what to version and what to leave out.

If You Do It Anyway...

You can create a custom clean filter in Git (or a shell script or Rake task that runs whenever you update YARD) that removes your timestamps before you commit the documentation files. For example:

# Tested with: GNU findutils 4.4.2, GNU sed 4.2.1
find doc -type f -iname \*html -exec sed -i '/id="footer"/,/\/div/ d' {} +

This will strip out all the footers in your YARD documents, so that you aren't committing those lines to your history. This should address your specific issue.

Jackdaw

-1 I totally disagree with your first comment. I could agree with point 1 and 2 if 3 was relevant, but I'm sorry, point #3 is totally irrelevant. Yes I don't need to version them, but that doesn't hurt (even point #1 and #2 don't hurt). I think you have not understood why I'm versionning them. However I'll have a look at your clean filter and might accept your answer. – Unseal

Answer 5

I have almost the same issue. It's not the documentation, but source files in which IDE sets the date and time changed. Every time on save.

The requirement was to have this date and time 'pretty' before commit, meaning no seconds, minutes should be rounded to 15.

The best approach I think off is to create small git command to clean-up the code before commit. The plug-in. Named it git-cleanup And placed it in c:\Program Files (x86)\Git\libexec\git-core (I'm using Windows).

So now before doing git commit I'm running git cleanup and it does all the job. Actually, I think it even possible to run it in one go, like git cleanup && git commit -a -m "Commit message". Or create custom alias for this command.

I've used ruby for creating this small script. But you may use language of your choice. Git allows this.

Raynard

Answer 6

Modeline Solution for Updated Question

If the problem is really VIM modelines, rather than the date stored in the footer, then you can use a pre-commit hook (client side) or pre-receive or post-receive hook (server side) that checks for a newline immediately after the modeline. For example, using GNU sed:

sed -r '/^#[[:space:]]+vim?:/ {N; /\n[^\n]/q1}'

Your hook can then display a diff, an error message, or take some other action based on the exit status. The important thing is that your modeline will be properly separated from subsequent documentation blocks, and should be properly ignored by YARD.

Jackdaw

Alternately: modelines also work at the bottom of files, where they cannot be mistaken for documentation... – Metacarpus