How do annotate a git repository?

Question

I have a git repository, where in each commit, several things have been done, and as such, my one-liner commit messages are insufficient to fully explain what is going on.

I would like to be able to come back to these things later on, for my own reference, as well be able to publish them in some form. I understand that if I were to push my local repository onto a git hosting provider, such as github or bitbucket, I am able to view each commit and diff-patch via their web interface and add comments to them, and onto individual lines too. I'll refer to these as diff annotations.

The drawback with this is that the git hosting provider holds all the diff annotation data, and my local git repository will not contain them.

• Is there a way to "export" or "download" these diff annotations from the git hosting provider?
• Is there a git tool or plugin that allows me to create diff annotations in my local repository (without the need to push to a git hosting provider)?

Answer 1

I think Git offers what you need, not sure how complex your scenario is but my suggestions are the following:

Small commits

You say that "in each commit, several things have been done, and as such, my one-liner commit messages are insufficient to fully explain what is going on.". Well, some people might say otherwise but I would keep commits as small and simple as possible so they can be explained in one line.

Even for big features you can generally split them out in smaller changes. I do commits where I just fix paddings, or expose an API without necessarily coding it. Small commits are good to detect bugs in the future, for example, if you're using git bisect.

Lengthy descriptions

I'm not sure if I'm saying something completely trivial, apologies if I am, but you don't need to do a one-liner commit message every time. Do you always do commit -am <message>? You know that if you type commit without the -m, your default editor will open? Then you can type a first line summary followed by the bible, if you please.

Coming back to review

Yes, GitHub will be great if you want to navigate source, but if you want to go back in time and check your comments/annotations on a given commit, you just need to search the commit via a git log for example and then, picking the commit id, you can just do git show <commitId>.

This will show you all the changes alongside with all your comments.