3

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)?
Improve this question

1 Answer 1

Reset to default
3

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Thanks for the answer @bitoiu, however I was looking for a way to add comments to individual lines within a diff-patch. I tend to shy away from line-by-line commits, because my style is to incrementally get one more thing to work before each commit, and sometimes that means several files and lines get modified.
@bguiz, commits should be as simple/small as possible. If pieces need separate explanation, the commit is too complex. Your commit message might very well be much larger than the patch itself. In git, commits are lightweight and fast. Use this to advantage.
@vonbrand surely you do not mean to say that I should be committing one line at a time? What I am asking for here is the ability to commit several lines at a time, but be able to annotate each commit at the line level. That level of granularity is possible with committing one line at a time, however, I do not wish to do that.
@bguiz, if the change only afects one line, so be it. Many won't be one-liners, some will touch almost all files. Having atomic changes is critical if you want to use tools like git bisect.
from my original answer: "Small commits are good to detect bugs in the future, for example, if you're using git bisect."

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.