Just a few I noticed that are dubious to be in a document that is meant to describe "best practices". "Do commit early and often" --------------------------- * "Personally ... history of this repository!". That looks somewhat out of place when you are trying to document "best practices". "Don't panic" ------------- * As we never "auto-stash", anything that is on stash is by definition what the user deliberately placed, just like a commit on a branch that the user may have forgotten. So it is strange to count it as one of the three places that "lost" commit may be hiding. If you make it four and add "a branch you might have forgotten" to the mix, it would make a bit more sense, though. * The example command line for gitk passes --all and also everything from "log -g" output, which should be OK for toy history, but wouldn't be such a good idea when you can expect tons of data from "log -g". Doesn't "gitk" itself accept -g these days? * Lost and found Why "git ls-tree -r"? Doesn't "git show" work eqully well? Also, the name of the hash we happen to use to produce the "object name" is "SHA-1", so either of these two are fine, but do not say "SHA" (throughout the document). "On Sausage Making" ------------------- * The desription of "downside" shows a bias against efforts to strive for useful history, and also shows ignorance of the true motivation behind such discipline. It is _not_ blame or ego. It is all about leaving a history others can later use to understand _why_ the code became the way it is now, to make it less likely for others to break it. If I were writing this, I would either remove that one paragraph altogether, or tone it down dramatically. There is a short-term downside that you would be spending time on perfecting the history instead of advancing the tip of the branch, especially when you know the tree at the tip of the perfected history will be identical to the tip of the messy history you currently have. If you plan to leave the project in a month or so and will never look back, that is totally wasted effort as maintaining the result will be other people's problem. But if you are planning to be involved in the project for a longer haul, the time and effort is worth spending to make less-than-useful history into useful one. "Do keep up to date" -------------------- * You explained in "Do choose a workflow" section that different workflows suite different projects. It would read better to rephrase this paragraph in which you are admitting that not everybody agrees with your "pull --rebase". Instead of saying "but they should agree with me", it would be more useful to say in what workflow and the workflow elements such as "pull --rebase" you advocate in this section are suited (you do not have to say in what other workflow they are inappropriate). I stopped reading at this point, but will look at the rest some other day. Thanks for a fun reading. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html