{"thread":{"id":"27174","subject":"git-work, git-base: an example of how to use it.","startedAt":"2011-04-25T10:43:12Z","lastAt":"2011-12-10T15:54:48Z","messageCount":2,"participants":["Jon Seymour","Adam Spiers"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"166309","messageId":"BANLkTim07-a5VwSAt7_vLMzOES_JZad9DA@mail.gmail.com","threadId":"27174","inReplyTo":null,"subject":"git-work, git-base: an example of how to use it.","fromName":"Jon Seymour","fromEmail":"jon.seymour@gmail.com","sentAt":"2011-04-25T10:43:12Z","receivedAt":"2011-04-25T10:43:12Z","isPatch":false,"sender":{"key":"jon.seymour@gmail.com","avatar":"https://avatars.githubusercontent.com/u/207131?v=4"},"body":"I haven't had much feedback about git-work, to this point. Peter\nBaumann mentioned it was a little hard to grok. So, I have updated my\ngithub fork with a README.md that shows how I use git work  and git\nbase to manage the README.md and the master branch of my git fork on\ngithub.\n\nThe text of the section \"HOW I MAINTAIN THIS DOCUMENT\" is included\nhere for the convenience of readers, or you may prefer to read the\nformatted version:\n\n   https://github.com/jonseymour/git\n\nWhenever I edit this document, I do the usual:\n\n   git add README.md\n   git commit -m \"Updates to README\"\n\nThen I do:\n\n   git work update jonseymour HEAD~1\n\nThe git work command above:\n  * updates the jonseymour branch with the last commit,\n  * merges that commit with $(git base) and updates $(git base) to\nrefer to that merge\n  * rebases remaining unpublished work on top of the new $(git base)\n\nThen, I publish the new base and the updated topic to github with:\n\n    git push public $(git base):master jonseymour:jonseymour\n\nThe net effect is that:\n\n  * My changes to README.md go to my jonseymour branch.\n  * My public github branch reflects the work I have stabilised with\ngit work update - it contains my stable dependencies, but not work in\nprogress.\n  * I keep my work in progress rebased on top of my public github master branch.\n  * I keep my unpublished work private.\n  * My working tree remains stable - git work update doesn't change\nthe tree, it only changes the history.\n\njon.\n"},{"id":"180804","messageId":"CAOkDyE8BZgVw7TYydz7+WnJ_7EjPeEcVUzjFV+NGRuDn2+cg6g@mail.gmail.com","threadId":"27174","inReplyTo":"BANLkTim07-a5VwSAt7_vLMzOES_JZad9DA@mail.gmail.com","subject":"Re: git-work, git-base: an example of how to use it.","fromName":"Adam Spiers","fromEmail":"git@adamspiers.org","sentAt":"2011-12-10T15:54:48Z","receivedAt":"2011-12-10T15:54:48Z","isPatch":false,"sender":{"key":"git@adamspiers.org","avatar":"https://avatars.githubusercontent.com/u/100738?v=4"},"body":"Hi Jon,\n\nI've only just discovered git-work, and it looks extremely\ninteresting.  From what I can tell so far, it is exactly what I was\nlooking for and could have recently saved me considerable pain!\nHere's some initial feedback.\n\nOn Mon, Apr 25, 2011 at 11:43 AM, Jon Seymour <jon.seymour@gmail.com> wrote:\n> I haven't had much feedback about git-work, to this point. Peter\n> Baumann mentioned it was a little hard to grok.\n\nI suspect that there is a strong correlation between these two points.\nI also found it hard to grok, although I think this could be easily\nfixed with a few tweaks to your existing docs.  Hopefully this would\nresult in more feedback.\n\nFirst some comments about Documentation/git-work.txt:\n\nThe existing DESCRIPTION really isn't a description, but merely a\nlegend for the COMMANDS section, which is where it really should\nbelong IMHO.  Also, the first sentence refers to the \"base\" of\n{branch} without explaining what that means.  This is currently the\nfirst full sentence a potential user is likely to read about git-work,\nbut for me at least, unfortunately it triggered a \"huh?\" reaction\nwhich sapped my will to continue reading.  Subsequently I discovered\nthat git-base.txt gives a definition of the \"base\" of a working\nbranch, but it's such a key ingredient in understanding the whole\nworkflow that it needs to be covered in the primary document, not in\nthe manual page for the git-base helper command which, if I understand\ncorrectly, is rarely meant to be invoked directly by the user anyway.\nFurthermore, the \"base\" is defined in terms of the user's \"current\nwork\", but that is not clearly defined.\n\nIn contrast, the contents of the DISCUSSION section are very helpful;\nmy initial reaction was \"yes! this is exactly what I need!\"  So I\nthink *this* should be the DESCRIPTION section, so that it's the first\nthing a potential user encounters, other than the SYNOPSIS section\nwhich by necessity of convention has to be at the top.  BTW, there's\nan \"integraton\" typo which needs to be fixed.\n\nThe EXAMPLES section which immediately follows the DISCUSSION is just\nsequence of one-liners and it's not clear how they are related to each\nother (if at all), and why/when you would want to use each one.\n\nIt would be better if the EXAMPLES section showed a use case \"story\"\nwhich starts with examples of simple usage and then builds up to more\nsophisticated workflows.  You seem to have already started to address\nthis with your README.md example, but the first step in that is a 'git\nadd' without even explaining which branch you are on at the time, what\ncommits are already on that branch, or how it relates to other\nbranches.  So currently (for my small brain, at least) there is too\nmuch of a \"WTF\" factor for it to be useful at first sight.\n\nPerhaps part of the confusion arises from a clash between your concept\nof a private working branch which is regularly rebased by 'git work',\nand many people's concept of master, which is often a public branch\nwhich as such is expected to be safe to regularly merge from.  Maybe\nyou could avoid this by recommending that a user adopting a workflow\nbased on 'git work' should use it to control an obviously private\nbranch, e.g. one named 'private' / 'working' / 'unstable' rather than\n'master'.\n\nIn another email to this list (Subject: [PATCH 00/23] RFC: Introducing\ngit-test, git-atomic, git-base and git-work) you give some more\nworkflow examples, which are useful and could be incorporated into a\nuse case story.\n\nA well-constructed story would answer questions implicitly raised\nwithin the (current) DISCUSSION section, such as:\n\n  - How are dependencies tracked?\n\n  - Can you have chains of dependencies?  If so, what does the\n    dependency graph look like?  Can a branch have multiple (direct)\n    dependencies?\n\n  - In what order are dependencies included in the base of the working\n    branch?\n\nBy the way, one of the EXAMPLES one-liners is described as \"start\ngitk, showing only the current work\", but looks like it might be a\ntypo; shouldn't it read:\n\n    $ gitk $(git work)\n\n?\n\nAnother suggestion to encourage people to try your work out: provide a\nquick \"how to try this out\" guide, preferably one which doesn't\ninvolve building the whole of git.\n\nFinally, please wrap all lines in git-work.txt etc. to less than 80\ncolumns to conform to existing style.  Currently these files are\nunreadable in certain contexts, e.g.\n\n  https://github.com/jonseymour/git/blob/master/Documentation/git-work.txt\n\ndue to the unreadably long lines.\n\nI hope that's useful feedback.  I will continue experimenting with it ...\n\nAdam\n"}]}