{"thread":{"id":"29773","subject":"Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","startedAt":"2012-02-28T13:04:30Z","lastAt":"2012-03-04T23:26:44Z","messageCount":6,"participants":["Seth Robertson","Jeff King","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"185618","messageId":"201202281304.q1SD4U8W018223@no.baka.org","threadId":"29773","inReplyTo":null,"subject":"Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Seth Robertson","fromEmail":"in-gitvger@baka.org","sentAt":"2012-02-28T13:04:30Z","receivedAt":"2012-02-28T13:04:30Z","isPatch":false,"sender":{"key":"in-gitvger@baka.org","avatar":null},"body":"\nI would like to announce three git documents I have written which\nothers (primarily on #git) have thought to be very useful, and so I\nwould like to share them with the wider community.\n\n\nCommit Often, Perfect Later, Publish Once: Git Best Practices\n----------------------------------------------------------------------\nhttp://sethrobertson.github.com/GitBestPractices\n\nThis first document covers a variety of topics, providing references\nand recommendations for using git.  These best practices have been\nbuilt up through decades of professional software management and\ndevelopment, years of git usage, and countless hours helping people on\n#git.\n\nTable of Contents:\n\nDo read about git                  On Sausage Making\nDo commit early and often\t   Do keep up to date\nDon't panic\t\t\t   Do periodic maintenance\nDo backups\t\t\t   Do enforce Standards\nDon't change published history\t   Do use useful tools\nDo choose a workflow\t\t   Do integrate with external tools\nDo divide work into repositories   Miscellaneous \"Do\"s\nDo make useful commit messages\t   Miscellaneous \"Don't\"s\n\n\n\nOn undoing, fixing, or removing commits or mistakes in git\n----------------------------------------------------------------------\nhttp://sethrobertson.github.com/GitFixUm\n\nThis next document covers the process of recovering from mistakes made\neither while or when using git.  It is a choose-your-own-adventure(1)\nstyle document which asks a series of questions to try and understand\nexactly what you did and what you want to do.  Currently it provides\ntwenty different solutions to various problems I have seen people\nhave.  This was primarily developed to stop answering the same\nquestions over and over again in #git, and worse, providing the wrong\nanswers when questioners either failed to provide critical information\nor totally misunderstood what was going on.\n\n\n\nPost-Production Editing using Git\n----------------------------------------------------------------------\nhttp://sethrobertson.github.com/GitPostProduction\n\nThis most recent document covers the topic of how to use git to make\nyour commits appear like they were made perfectly to the outside\nworld.  Doing so is something which is required by some projects, is\nrecommended in gitworkflows(7) and the best practices document (On\nSausage Making), and is a major feature of git.  However, I have not\nfound good documentation on exactly how to use git to accomplish this.\nThe git-rebase man page is quite extensive, but also fairly confusing\nto the uninitiated.\n\n\nI would appreciate comments, suggestions, or contributions for all\nthree documents.\n\n\n                                        -Seth Robertson\n\n(1) Not affiliated with Chooseco, LLC's \"Choose Your Own\nAdventure\"ⓡ. Good books, but a little light on the details of\nrecovering from git merge errors.\n"},{"id":"185678","messageId":"20120228225205.GA23804@sigill.intra.peff.net","threadId":"29773","inReplyTo":"201202281304.q1SD4U8W018223@no.baka.org","subject":"Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-02-28T22:52:05Z","receivedAt":"2012-02-28T22:52:05Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 28, 2012 at 08:04:30AM -0500, Seth Robertson wrote:\n\n> Commit Often, Perfect Later, Publish Once: Git Best Practices\n> ----------------------------------------------------------------------\n> http://sethrobertson.github.com/GitBestPractices\n\nI have only read the first of the three so far, but it looks very nice.\nI did notice a few things which were worth commenting on (I'll quote\ndirectly from the page in question below).\n\n> [section Don't Panic, subsection Lost and Found]\n>\n> Dangling Commit\n>\n> These are the most likely candidates for finding lost data. A dangling\n> commit is a commit no longer reachable by any branch or tag. This can\n> happen due to resets and rebases and are normal. git show SHA will let\n> you inspect them.\n\nResets and rebases record the commits in the reflog (at the very least\nin the HEAD reflog), and should generally not be the cause of dangling\ncommits (the objects should usually expire in the same \"git gc\" that\nexpires the reflog entries). I suspect a more common cause is deleting\nbranches, which leaves no reflog (the commits may be in the HEAD reflog\nif they were ever checked out, though).\n\nIt's somewhat minor; the overall advice (\"do not worry about dangling\ncommits\") holds. But it might be worth pointing out that the method for\nrecovering an accidentally deleted branch is usually:\n\n  1. look in the HEAD reflog\n\n  2. if you can't find it there, try dangling commits\n\n> [section Do make useful commit messages]\n\nThis talks about formatting, but not about content. I have long wanted\nto write a nice essay on what should go into a good commit message, but\nwhen I've tried it ends up very specific to the project, the type of\ncommit, and the individual change. I wonder if anybody knows of\nsomething good you could link to.\n\n> [section On Sausage Making]\n>\n> Some people like to hide the sausage making, or in other words pretend to\n> the outside world that their commits sprung full-formed in utter\n> perfection into their git repository. Certain large public projects\n> demand this, others demand smushing all work into one large commit, and\n> still others do not care.\n>\n> A good reason to hide the sausage making is if you feel you may be\n> cherry-picking commits a lot (though this too is often a sign of bad\n> workflow). Having one or a small number of commits to pick is much\n> easier than having to find one commit here, one there, and half of this\n> other one. The latter approach makes your problem much much harder and\n> typically will lead to merge conflicts when the donor branch is finally\n> merged in.\n>\n> Another good reason is to ensure each commit compiles and/or passes\n> regression tests, and represents a different easily understood concept\n> (important for archeology). The former allows git-bisect to chose any\n> commit and have a good chance of that commit doing something useful, and\n> the latter allows for easy change review, understanding, and\n> cherry-picking.\n\nThis is a nice overview of the motivation, but I think it misses one\nof the main reasons we clean up patches in git.git: code review. When\nyou publish patches, you have several audiences. One of those audiences\nis the end user who will compile release v1.5. They only care about the\nend result of the patches. Another is people bisecting, who care that\neverything intermediate builds and is reasonable; you can satisfy that\nby checking each commit against a test suite. Another is people reading\nthe logs later to find out what happened; it's OK for them to see that a\nbug was in the initial version, and then fixed 5 minutes later.\n\nBut yet another audience is reviewers who will read your changes and\ndecide they should be applied, rejected, or re-worked. For those people,\nit is much harder to review a series that introduces a bug in patch 1,\nbut fixes it in patch 5. The reviewer may also notice the bug, take time\nthinking about and writing an analysis, and then get frustrated to find\nthat their work was wasted when they get to patch 5.\n\nThe alternative is that they stop thinking about individual patches and\nconsider the whole series (e.g., when they see patch 1 has a bug, stop\nreading and look through the other patches for a fix). But that makes\nreview much harder, because you have to think about a much larger series\nof changes.\n\nBy cleaning up patches into single, logical changes that build on one\nanother, and which don't individually regress (i.e., they are always\nmoving towards some desirable common endpoint), the author is writing a\nchronological story not of what happened, but what _should_ happen, with\nthe intent that the audience (i.e., reviewers) are convinced that the\nchange is the right thing to do.\n\nI really liked your movie analogy. Patch series are really just\ndocumentaries about a change, arranged for greatest impact on the\nviewer. :)\n\n> [Do periodic maintenance]\n>\n> Compact your repo (git gc --aggressive)\n>\n> This will removed outdated dangling objects (after the two+ week grace\n> period). It will also compress any loose objects git has added since\n> your last gc. git will run gc automatically after certain commands, but\n> doing a manual --aggressive will save space and speed git operations.\n\nMost people shouldn't be using \"--aggressive\". Unless you have an\nexisting pack that is poorly packed (e.g., because you did a\nfast-import that did not do much delta searching), you are not going to\nsee much benefit, and it will take a lot longer. Basically the three\nlevels of \"gc\" are:\n\n  1. git gc --auto; if there are too many loose objects, they will all\n     go into a new incremental pack. If there are already too many\n     packs, all of the existing packs will get re-packed together.\n\n     If we are making an incremental pack, this is by far the fastest,\n     because the speed is independent of the existing history. If we\n     pack everything together, it should be more or less the same as (2)\n     below.\n\n  2. git gc; this packs everything into a single pack. It does not use\n     high window and depth parameters, but more importantly, it reuses\n     existing deltas. That makes the delta compression phase _much_\n     faster, and it often makes the writing phase faster (because for\n     older objects, we are primarily streaming them right out of the\n     existing pack). On a big repo, though, it does do a lot of I/O,\n     because it has to rewrite the whole pack.\n\n  3. git gc --aggressive; this is often way slower than the above\n     because we throw out all of the existing deltas and recompute them\n     from scratch. The higher window parameter means it will spend a bit\n     more time computing, and it may end up with a smaller pack.\n\nIn practical applications, I would expect (2) to achieve similar results to (3). If\nthat isn't the case, then I think we should be tuning up the default\nwindow and depth parameters for non-aggressive \"git gc\" a bit.\n\n> [section Miscellaneous \"don't\"s]\n>\n> create very large repositories (when possible)\n>\n> Git can be slow in the face of large repositories. There are\n> git-config options that can help. pack.threads=1 pack.deltaCacheSize=1\n> pack.windowMemory=512m core.packedGitWindowSize=16m\n> core.packedGitLimit=128m. Other likely ones exist.\n\nIt might help to qualify \"big\" here. To some people, 10,000 files,\n50,000 commits, and a 200M packfile is big. But that's a fraction of\nlinux-2.6, which most people use. I think big here is probably getting\ninto 100K-200K files (where the time to stat() files becomes noticeable,\ncommits are probably not relevant (because git is usually good at only\nlooking at recent bits of history for most operations), and packfiles\nabove 1G or so start to get cumbersome (mostly because of the I/O on a\nfull repack; but then you should consider marking a pack as .keep).\n\nBut those numbers are just pulled out of a hat based on the last few\nyears. Your OS, your hardware, and your expectations make a huge\ndifference in what seems reasonable.\n\nYour config recommendations seem mostly related to relieving memory\npressure for packing (at the expense of making the pack a lot slower).\nDropping --aggressive from your gc might help a lot with that, too. It\nmight be worth noting that you should only start twiddling these options\nif you are running out of memory during a repack. They will not affect\ngit performance for day-to-day commands.\n\nI don't think you should need to adjust core.packedGitWindowSize or\ncore.packedGitLimit at all. Those files are mmap'd, so it is up to the\nOS to be reasonable about faulting in or releasing the memory. The main\nmotivation of pack windows is not memory _usage_, but rather getting a\nlarge contiguous chunk of the address space. mmap-ing a 4G packfile on a\n32-bit system just doesn't work. But the defaults are set to reasonable\nvalues for each architecture.\n\n-Peff\n"},{"id":"185687","messageId":"7v399uxxkq.fsf@alter.siamese.dyndns.org","threadId":"29773","inReplyTo":"201202281304.q1SD4U8W018223@no.baka.org","subject":"Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-02-29T01:00:53Z","receivedAt":"2012-02-29T01:00:53Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Just a few I noticed that are dubious to be in a document that is meant to\ndescribe \"best practices\".\n\n\"Do commit early and often\"\n---------------------------\n\n* \"Personally ... history of this repository!\".  That looks somewhat out\n  of place when you are trying to document \"best practices\".\n\n\n\"Don't panic\"\n-------------\n\n* As we never \"auto-stash\", anything that is on stash is by definition\n  what the user deliberately placed, just like a commit on a branch that\n  the user may have forgotten.  So it is strange to count it as one of the\n  three places that \"lost\" commit may be hiding.  If you make it four and\n  add \"a branch you might have forgotten\" to the mix, it would make a bit\n  more sense, though.\n\n* The example command line for gitk passes --all and also everything from\n  \"log -g\" output, which should be OK for toy history, but wouldn't be\n  such a good idea when you can expect tons of data from \"log -g\".\n\n  Doesn't \"gitk\" itself accept -g these days?\n\n* Lost and found\n\n  Why \"git ls-tree -r\"?  Doesn't \"git show\" work eqully well?\n\n  Also, the name of the hash we happen to use to produce the \"object name\"\n  is \"SHA-1\", so either of these two are fine, but do not say \"SHA\"\n  (throughout the document).\n\n\n\"On Sausage Making\"\n-------------------\n\n* The desription of \"downside\" shows a bias against efforts to strive for\n  useful history, and also shows ignorance of the true motivation behind\n  such discipline. It is _not_ blame or ego. It is all about leaving a\n  history others can later use to understand _why_ the code became the way\n  it is now, to make it less likely for others to break it.\n\n  If I were writing this, I would either remove that one paragraph\n  altogether, or tone it down dramatically.  There is a short-term\n  downside that you would be spending time on perfecting the history\n  instead of advancing the tip of the branch, especially when you know the\n  tree at the tip of the perfected history will be identical to the tip of\n  the messy history you currently have.  If you plan to leave the project\n  in a month or so and will never look back, that is totally wasted effort\n  as maintaining the result will be other people's problem.  But if you\n  are planning to be involved in the project for a longer haul, the time\n  and effort is worth spending to make less-than-useful history into\n  useful one.\n\n\n\"Do keep up to date\"\n--------------------\n\n* You explained in \"Do choose a workflow\" section that different workflows\n  suite different projects.  It would read better to rephrase this\n  paragraph in which you are admitting that not everybody agrees with your\n  \"pull --rebase\".  Instead of saying \"but they should agree with me\", it\n  would be more useful to say in what workflow and the workflow elements\n  such as \"pull --rebase\" you advocate in this section are suited (you do\n  not have to say in what other workflow they are inappropriate).\n\nI stopped reading at this point, but will look at the rest some other day.\nThanks for a fun reading.\n"},{"id":"186045","messageId":"201203041920.q24JK15L024778@no.baka.org","threadId":"29773","inReplyTo":"20120228225205.GA23804@sigill.intra.peff.net","subject":"Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Seth Robertson","fromEmail":"in-gitvger@baka.org","sentAt":"2012-03-04T19:20:01Z","receivedAt":"2012-03-04T19:20:01Z","isPatch":false,"sender":{"key":"in-gitvger@baka.org","avatar":null},"body":"\nFirst, I'd like to thank you for your comments.  They certainly\nimproved the document and made me think and experiment.\n\nIn message <20120228225205.GA23804@sigill.intra.peff.net>, Jeff King writes:\n\n    On Tue, Feb 28, 2012 at 08:04:30AM -0500, Seth Robertson wrote:\n\n    > [section Don't Panic, subsection Lost and Found]\n    >\n    > Dangling Commit\n    >\n    > These are the most likely candidates for finding lost data. A dangling\n    > commit is a commit no longer reachable by any branch or tag. This can\n    > happen due to resets and rebases and are normal. git show SHA will let\n    > you inspect them.\n\n    Resets and rebases record the commits in the reflog (at the very least\n    in the HEAD reflog), and should generally not be the cause of dangling\n    commits (the objects should usually expire in the same \"git gc\" that\n    expires the reflog entries). I suspect a more common cause is deleting\n    branches, which leaves no reflog (the commits may be in the HEAD reflog\n    if they were ever checked out, though).\n\nI get them all of time and I never delete branches.\n\n    It's somewhat minor; the overall advice (\"do not worry about dangling\n    commits\") holds. But it might be worth pointing out that the method for\n    recovering an accidentally deleted branch is usually:\n\n      1. look in the HEAD reflog\n      2. if you can't find it there, try dangling commits\n\nMy understanding is that if a commit gets packed, it sticks around for\na few weeks longer than the reflog since the clock gets reset when it\ngets evicted from a pack.\n\n    > [section Do make useful commit messages]\n\n    This talks about formatting, but not about content. I have long wanted\n    to write a nice essay on what should go into a good commit message, but\n    when I've tried it ends up very specific to the project, the type of\n    commit, and the individual change. I wonder if anybody knows of\n    something good you could link to.\n\nI'd certainly like to see such a thing.  I did touch on the subject\nfurther when I started talking about integration with bug tracking\nsystems.\n\n    > [section On Sausage Making]\n    >\n    > Some people like to hide the sausage making, or in other words pretend to\n    > the outside world that their commits sprung full-formed in utter\n    > perfection into their git repository. Certain large public projects\n    > demand this, others demand smushing all work into one large commit, and\n    > still others do not care.\n    >\n    > A good reason to hide the sausage making is if you feel you may be\n    > cherry-picking commits a lot (though this too is often a sign of bad\n    > workflow). Having one or a small number of commits to pick is much\n    > easier than having to find one commit here, one there, and half of this\n    > other one. The latter approach makes your problem much much harder and\n    > typically will lead to merge conflicts when the donor branch is finally\n    > merged in.\n    >\n    > Another good reason is to ensure each commit compiles and/or passes\n    > regression tests, and represents a different easily understood concept\n    > (important for archeology). The former allows git-bisect to chose any\n    > commit and have a good chance of that commit doing something useful, and\n    > the latter allows for easy change review, understanding, and\n    > cherry-picking.\n\n    This is a nice overview of the motivation, but I think it misses one\n    of the main reasons we clean up patches in git.git: code review.\n\nWell, I said \"change review\" instead of \"code review\".  I added the\nword \"code\" specifically, but I'll stick some wording on why it is\nimportant to code review.  I already touched on people who wanted to\nbisect.\n\n    By cleaning up patches into single, logical changes that build on one\n    another, and which don't individually regress (i.e., they are always\n    moving towards some desirable common endpoint), the author is writing a\n    chronological story not of what happened, but what _should_ happen, with\n    the intent that the audience (i.e., reviewers) are convinced that the\n    change is the right thing to do.\n\nI'll add this paragraph as well.\n\n    > [Do periodic maintenance]\n    >\n    > Compact your repo (git gc --aggressive)\n    >\n    > This will removed outdated dangling objects (after the two+ week grace\n    > period). It will also compress any loose objects git has added since\n    > your last gc. git will run gc automatically after certain commands, but\n    > doing a manual --aggressive will save space and speed git operations.\n\n    Most people shouldn't be using \"--aggressive\".\n\nI'll add `git gc` as an intermediate stage and take wording from the\nmanual to run `git gc --aggressive` every few hundred changesets.\n\nI suppose it all depends on your definition of the period in periodic\nmaintenance.\n\n    > [section Miscellaneous \"don't\"s]\n    >\n    > create very large repositories (when possible)\n    >\n    > Git can be slow in the face of large repositories. There are\n    > git-config options that can help. pack.threads=1 pack.deltaCacheSize=1\n    > pack.windowMemory=512m core.packedGitWindowSize=16m\n    > core.packedGitLimit=128m. Other likely ones exist.\n\n    It might help to qualify \"big\" here. ... I think big here is\n    probably getting into 100K-200K files (where the time to stat()\n\n    files becomes noticeable, commits are probably not relevant\n    (because git is usually good at only looking at recent bits of\n    history for most operations), and packfiles above 1G or so start\n    to get cumbersome (mostly because of the I/O on a full repack; but\n    then you should consider marking a pack as .keep).\n\n    But those numbers are just pulled out of a hat based on the last few\n    years. Your OS, your hardware, and your expectations make a huge\n    difference in what seems reasonable.\n\nThat was why I didn't mention any specific limits.  However, since you\nwere kind enough to do provide some, I will include them.  I will also\nadd that my suggested configuration values are only needed if you are\nexperiencing memory pressure on packing.\n\n    Your config recommendations seem mostly related to relieving memory\n    pressure for packing (at the expense of making the pack a lot slower).\n\nVery true, that was the problem I was running into.  I will\nspecifically make that comment.  I'll make a wild recommendation\nabout sizing these variables, which I'd certainly accept corrections\nto or advice on.  Specifically the next sentence:\n\n----------------------------------------------------------------------\nMy gut tells me that sizing (\"deltaCacheSize\" + \"windowMemory\" +\nmin(\"core.bigFileThreshold[512m]\", TheSizeOfTheLargestObject)) *\n\"threads\" to be around *half* the amount of RAM you can dedicate to\nrunning `git gc` will optimize your packing experience, but I will be\nthe first to admit that made up that formula based on a very few\nsamples and it could be drastically wrong.\n------------------------------------------------------------------\n\n    I don't think you should need to adjust core.packedGitWindowSize or\n    core.packedGitLimit at all.\n\nWell, certainly git takes up a ton (specifically double or just over\n1GB additional) more RAM during gc with them unset, and caused some\nlimited swapping of other processes (but no thrashing).  However, the\nreal question is, did it take more time?  It did, but the amount of\nadded time was about 3% and thus probably well under my test accuracy.\n\n\t\t\t\t\t-Seth Robertson\n"},{"id":"186047","messageId":"201203041920.q24JKk3h024813@no.baka.org","threadId":"29773","inReplyTo":"7v399uxxkq.fsf@alter.siamese.dyndns.org","subject":"Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Seth Robertson","fromEmail":"in-gitvger@baka.org","sentAt":"2012-03-04T19:20:46Z","receivedAt":"2012-03-04T19:20:46Z","isPatch":false,"sender":{"key":"in-gitvger@baka.org","avatar":null},"body":"\nIn message <7v399uxxkq.fsf@alter.siamese.dyndns.org>, Junio C Hamano writes:\n\n    Just a few I noticed that are dubious to be in a document that is meant to\n    describe \"best practices\".\n\nThanks for the comments.  I will incorporate most of them and\ncertainly thought hard about all of them.\n\n    \"Don't panic\"\n    -------------\n\n    * As we never \"auto-stash\", anything that is on stash is by definition\n      what the user deliberately placed, just like a commit on a branch that\n      the user may have forgotten.  So it is strange to count it as one of the\n      three places that \"lost\" commit may be hiding.  If you make it four and\n      add \"a branch you might have forgotten\" to the mix, it would make a bit\n      more sense, though.\n\nI do.  That was the next bullet \"misplaced\".  I also expand on this a\nbit during the second document about finding and fixing mistakes.\n\n    * The example command line for gitk passes --all and also everything from\n      \"log -g\" output, which should be OK for toy history, but wouldn't be\n      such a good idea when you can expect tons of data from \"log -g\".\n\nMy reasoning is that the live/referenced history provides context.\nSeeing a series of commits going back in time is nice and all, but\nknowing that at some point it branched from some particular\nstill-referenced branch allows you to concentrate only on the commits\nthat were \"lost\" (abandoned/replaced/etc), lets you have a better idea\non whether those commits are relevant, and perhaps you will even see\nsimilar commits nearby on a still referenced branch.\n\nYes, for projects with dozens of simultaneously active branches it may\ncause information overload.  Ideally there would be an easy way to\nonly have gitk show relevant branches without a lot of work.  Right\nnow, the only way I can think of is to find the --contains of the\nfirst referenced parent of the unreferenced commits and then pick the\nclosest named branch to display using some algorithm.  I'll also\nsuggest using `git log -Sfoo -g` in addition to my current alternate\nsuggestion of looking at the reflog directly.\n\nAnyway, someone managing dozens of branches should know what --all\ndoes and that they can remove it.\n\n      Doesn't \"gitk\" itself accept -g these days?\n\nMy gitk (1.7.9.2) accepts -g but doesn't show the reflog.\n\n    * Lost and found\n\n      Why \"git ls-tree -r\"?  Doesn't \"git show\" work eqully well?\n\nI find the added information of ls-tree more useful since you can more\neasily examine the contents/blobs of the tree.\n\ngit show    |  git ls-tree -r\n------------|--------------------------------------------------------------\ntree 51e4   |\n            |\nA           | 100644 blob e900b1c81c65dc52463027be827c1418fc7ff505    A\nasdf/       | 100644 blob 8b137891791fe96927ad78e64b0aad7bded08bdc    asdf/a\nx           | 100644 blob e900b1c81c65dc52463027be827c1418fc7ff505    x\n\n\n\n    \"On Sausage Making\"\n    -------------------\n\n    * The desription of \"downside\" shows a bias against efforts to strive for\n      useful history, and also shows ignorance of the true motivation behind\n      such discipline. It is _not_ blame or ego. It is all about leaving a\n      history others can later use to understand _why_ the code became the way\n      it is now, to make it less likely for others to break it.\n\nI have included that last sentence in the argument for creating a\nperfected history.  I personally believe that there are many contexts\nin which a perfected history is critical, but I also feel there are\nmany cases where it is entirely overkill, which is why I talk about\nboth sides of the issue.  But I think it important enough that I made\nit one of the three things I mention in the title of the document\n(perfect later) *and* I wrote the third document describing how\nsomeone might actually go about the process.\n\n\n    \"Do keep up to date\"\n    --------------------\n\n    * You explained in \"Do choose a workflow\" section that different workflows\n      suite different projects.  ... it\n      would be more useful to say in what workflow and the workflow elements\n      such as \"pull --rebase\" you advocate in this section are suited (you do\n      not have to say in what other workflow they are inappropriate).\n\nIn the pull --rebase section, I spend one short paragraph talking\nabout why I think it is a good idea and four providing arguments\nagainst it.  In my opinion, it rebase should always be used when it is\npossible, and I did specifically mark it as my opinion and that people\ndisagree with me.  I think I did about as good as I can presenting the\nnegative side, but if you have more specific arguments against rebase,\nI'll be happy to include them.  Perhaps it will even change my stance\nabout using rebase.\n\n\t\t\t\t\t-Seth Robertson\n"},{"id":"186057","messageId":"7vhay46j7v.fsf@alter.siamese.dyndns.org","threadId":"29773","inReplyTo":"201203041920.q24JKk3h024813@no.baka.org","subject":"Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-04T23:26:44Z","receivedAt":"2012-03-04T23:26:44Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Seth Robertson <in-gitvger@baka.org> writes:\n\n> In message <7v399uxxkq.fsf@alter.siamese.dyndns.org>, Junio C Hamano writes:\n>     Just a few I noticed that are dubious to be in a document that is meant to\n>     describe \"best practices\".\n> ...\n>     \"Don't panic\"\n>     -------------\n>\n>     * As we never \"auto-stash\", anything that is on stash is by definition\n>       what the user deliberately placed, just like a commit on a branch that\n>       the user may have forgotten.  So it is strange to count it as one of the\n>       three places that \"lost\" commit may be hiding.  If you make it four and\n>       add \"a branch you might have forgotten\" to the mix, it would make a bit\n>       more sense, though.\n>\n> I do.\n\nYou don't.  You say \"There are THREE places where \"last\" changes can be\nhiding\" and list these three things, not four.\n\n>     \"Do keep up to date\"\n>     --------------------\n>\n>     * You explained in \"Do choose a workflow\" section that different workflows\n>       suite different projects.  ... it\n>       would be more useful to say in what workflow and the workflow elements\n>       such as \"pull --rebase\" you advocate in this section are suited (you do\n>       not have to say in what other workflow they are inappropriate).\n>\n> In the pull --rebase section, I spend one short paragraph talking\n> about why I think it is a good idea and four providing arguments\n> against it.  In my opinion,...\n\nI do not know if you have updated the version seen on the web since the\nreview comments, but I was merely suggesting that \"what I recommend here\nmay not be desirable for some workflows\" without spelling out what these\nworkflows are would be less helpful to readers than being more explicit,\ni.e. \"these suggestions are good for this and that workflows\".\n\nThis section by nature of what is discussed is bound to be incomplete and\nwill not be \"universal truth\" as there does no \"universal truth\" exist.\nLetting the users know that for what kind of workflows these are good\nsuggestions upfront will help them to decide if the recommendations are\napplicalble to them.\n"}]}