GitHub - Shiny new commit styles(github.com)
github.com
GitHub - Shiny new commit styles
https://github.com/blog/926-shiny-new-commit-styles
26 comments
I think the present tense recommendation comes from the expectation that each commit works as a stand-alone patch. Thus the commit message does not describe what changes you did to the repository, but what the patch does to it.
Git provides a wealth of tools to craft perfect commits, and if you use them, it's not difficult to end up with a nice history of "add this, remove that, modify something else" changesets that (usually) would make sense even when separated from the surrounding history.
Git provides a wealth of tools to craft perfect commits, and if you use them, it's not difficult to end up with a nice history of "add this, remove that, modify something else" changesets that (usually) would make sense even when separated from the surrounding history.
"Git provides a wealth of tools to craft perfect commits"
Pointers please?
Pointers please?
Others already mentioned rebasing, but I think the most important tool is the index, or "the staging area". Lots of people not used to Git tend to see the index as an unnecessary extra step, but it's really what enables the good stuff.
In short, the index allows you to decide what goes in a single commit, regardless of the actual contents of a working directory. You can commit only a single line from a file if you want. If you learn how the index works and why it works like it does, understanding the rest becomes much easier.
You can also eg. resolve a conflict piece-by-piece by adding resolved parts to the index, diffing against the working directory, and then finally committing once the content of the index looks correct.
There are many tutorials and I'm not sure which one is the best but I think the book "Pro Git" does a good job at explaining the index among other things. It's freely available online at http://progit.org
In short, the index allows you to decide what goes in a single commit, regardless of the actual contents of a working directory. You can commit only a single line from a file if you want. If you learn how the index works and why it works like it does, understanding the rest becomes much easier.
You can also eg. resolve a conflict piece-by-piece by adding resolved parts to the index, diffing against the working directory, and then finally committing once the content of the index looks correct.
There are many tutorials and I'm not sure which one is the best but I think the book "Pro Git" does a good job at explaining the index among other things. It's freely available online at http://progit.org
Sorry I read your original as 'crafting perfect commit messages'.
git rebase
http://progit.org/book/ch6-4.html
http://progit.org/book/ch6-4.html
git amend
git rebate -i ...
Numbers in commit messages don't really make any sense. I don't understand what value they might have. The narrative of your codebase is hard to follow when large number of your commits don't have any message explaining what you've done.
I like to commit (quite) frequently when working on something, but later I feel that work-in-progress commits are just hindrance. When looking at project history after two year, I'll be glad if there is a single, larger commit "implemented feature x". Rebase is your friend.
I like to commit (quite) frequently when working on something, but later I feel that work-in-progress commits are just hindrance. When looking at project history after two year, I'll be glad if there is a single, larger commit "implemented feature x". Rebase is your friend.
"Numbers in commit messages don't really make any sense. I don't understand what value they might have."
I like to refer to 'commit 347' rather than 'commit a3bh'. There's an implicit sense of how old a commit is.
I like to refer to 'commit 347' rather than 'commit a3bh'. There's an implicit sense of how old a commit is.
I'm personally not that bothered by the difference in tenses, but I can see how it requires a slight mental-context-switch between reading various commits. Some peoples' eyes are more attuned to syntax and grammatical inconsistencies--for them it would be a bigger distraction.
In my mind, it's on par with inconsistent whitespace in code indentation. Sometimes I notice these things more and find it hard to focus on other details, but most of the time I can glance over them.
In my mind, it's on par with inconsistent whitespace in code indentation. Sometimes I notice these things more and find it hard to focus on other details, but most of the time I can glance over them.
I think the messages that are not in the suggested "do action" form are somewhat more ambiguous:
whitelist of un-GC'd syms - Did you implement a whitelist feature, write whitelist data, update whitelist data, work on whitelisting in general?
oops, hadn't fully finished a!b ssyntax - Did you finish the syntax, or did you work around it for now?
failing test for apply - Did you add the test, make the test pass?
As a non-native speaker I have to wonder if this is really about past tense vs. present tense though. How should I grammatically interpret the suggested "Fix bug" as opposed to the alternative "Fixed bug"?
Past: [I] fixed bug. [This] fixed bug.
Present: [I] fix bug. [This] fix bug. Fix bug!
Infinitive: [To] fix bug. [I want to] fix bug. [This serves to] fix bug.
The suggestion may actually be towards the last option that doesn't have a tense. It's like an item in a todo list. That would make the most sense?
whitelist of un-GC'd syms - Did you implement a whitelist feature, write whitelist data, update whitelist data, work on whitelisting in general?
oops, hadn't fully finished a!b ssyntax - Did you finish the syntax, or did you work around it for now?
failing test for apply - Did you add the test, make the test pass?
As a non-native speaker I have to wonder if this is really about past tense vs. present tense though. How should I grammatically interpret the suggested "Fix bug" as opposed to the alternative "Fixed bug"?
Past: [I] fixed bug. [This] fixed bug.
Present: [I] fix bug. [This] fix bug. Fix bug!
Infinitive: [To] fix bug. [I want to] fix bug. [This serves to] fix bug.
The suggestion may actually be towards the last option that doesn't have a tense. It's like an item in a todo list. That would make the most sense?
That's worth thinking about, thanks for the feedback!
What is with the numbers? Git is distributed, commits are inherently unordered, this will become very confusing if you have multiple committers.
Also provide useful messages, if you want to look up changes to something you really want to be able to do a `git log | grep foo`.
Also provide useful messages, if you want to look up changes to something you really want to be able to do a `git log | grep foo`.
There's no parallel development going on.
(see also http://news.ycombinator.com/item?id=2967295)
(see also http://news.ycombinator.com/item?id=2967295)
And you are assuming that there never will be a need for parallel development?
Further more, having that kind of naming scheme might actually hold you back from doing parallel development - aka using git to its full potential. I regularly make use of branching even in my personal projects. For example starting the development of new experimental feature while still continuing fixing bugs in the master branch.
The larger the commit numbers grow the smaller will be difference between a number 1935 and git hash af23cc. Besides, git provides easy means for referring to the most recent commits using HEAD, HEAD^, HEAD^^ and so on. There's also --since option for going further back in time.
As a result your commits now have two revision numbers: the hash used and maintained by git and the number used and maintained by you. But there's no escaping from hashes. You're forced to use them anyway. So why supplement them with your own revision numbers? That's like having a digital library system and maintaining a perfo-cards archive at parallel.
Further more, having that kind of naming scheme might actually hold you back from doing parallel development - aka using git to its full potential. I regularly make use of branching even in my personal projects. For example starting the development of new experimental feature while still continuing fixing bugs in the master branch.
The larger the commit numbers grow the smaller will be difference between a number 1935 and git hash af23cc. Besides, git provides easy means for referring to the most recent commits using HEAD, HEAD^, HEAD^^ and so on. There's also --since option for going further back in time.
As a result your commits now have two revision numbers: the hash used and maintained by git and the number used and maintained by you. But there's no escaping from hashes. You're forced to use them anyway. So why supplement them with your own revision numbers? That's like having a digital library system and maintaining a perfo-cards archive at parallel.
You'll notice that I am using branches. Branches != parallel development. Multiple developers != parallel development. This is a learning exercise. I don't need all the rush and hurly-burly of doing multiple things at once.
I'm not talking about referring to commits on the commandline. You're right, I use hashes for that[1]. I'm talking about referring to commits in later commits: http://github.com/akkartik/wart/commit/0f087dbaee. It's immediately obvious that I'd broken the app for a dozen commits.
If the project were ever to get so popular that people started submitting bugs and it needed parallel development I'd.. stop using numbers. If I were to get to 293547, ditto. But I think 1935 will be perfectly useable.
[1] I like hashes. I also like separating concerns. My friends have seen me wearing a woolen cap, a raincoat hoodie and a baseball cap, all at once. What? It gets cold and rainy and sunny all at once in Texas, and hoodies suck at keeping the sun out. Every cap or number should do one thing well.
I'm not talking about referring to commits on the commandline. You're right, I use hashes for that[1]. I'm talking about referring to commits in later commits: http://github.com/akkartik/wart/commit/0f087dbaee. It's immediately obvious that I'd broken the app for a dozen commits.
If the project were ever to get so popular that people started submitting bugs and it needed parallel development I'd.. stop using numbers. If I were to get to 293547, ditto. But I think 1935 will be perfectly useable.
[1] I like hashes. I also like separating concerns. My friends have seen me wearing a woolen cap, a raincoat hoodie and a baseball cap, all at once. What? It gets cold and rainy and sunny all at once in Texas, and hoodies suck at keeping the sun out. Every cap or number should do one thing well.
"provide useful messages"
My convention is that commits without messages only reorganized or refactored code, without adding behavior or tests.
My convention is that commits without messages only reorganized or refactored code, without adding behavior or tests.
is it just me, or does anyone else think that though the design is prettier, it kinda makes other parts of the app look bad - for instance compare the commit style to the tree listings. it's not that one or the other look bad, it's just the dissimilarity is jarring.
I agree, the new commits use a different motif than the old ones and it definitely looks odd (especially on the code tree pages). Maybe this is the sign of a coming design refresh?
I think it is, check out Kneath's (a designer at github) dribble:
http://dribbble.com/kneath
http://dribbble.com/kneath
GitHub is doing a fantastic job of building a consistent presence from top to bottom. The changes as a whole have been extremely impressive over the past few months. I, as a designer that uses GitHub on a daily basis at work, am very enthusiastic about the latest updates, the new commit styles included. The GitHub team has been extremely quick to iterate and launch updates recently. I'm sure there's plenty more to come.
Update GitHub:FI, please. :(
Here's an example changelog: http://github.com/akkartik/wart/commits/unstable. Criticisms?