{"thread":{"id":"10929","subject":"Git in a Nutshell guide","startedAt":"2007-11-19T13:05:04Z","lastAt":"2007-11-23T09:28:28Z","messageCount":40,"participants":["Jonas Juselius","Jakub Narebski","Brian Downing","Nicolas Pitre","Lars Hjemli","Benoit Sigoure","Matthieu Moy","J. Bruce Fields","Junio C Hamano","Daniel Barkalow","Jan Hudec","David Kågedal","Jonathan del Strother","Johannes Schindelin","jhud7196@artax.karlin.mff.cuni.cz"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"60298","messageId":"1195477504.8093.15.camel@localhost","threadId":"10929","inReplyTo":null,"subject":"Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas.juselius@chem.uit.no","sentAt":"2007-11-19T13:05:04Z","receivedAt":"2007-11-19T13:05:04Z","isPatch":false,"sender":{"key":"jonas.juselius@chem.uit.no","avatar":null},"body":"Hi everybody,\n\nI have been involved in a somewhat painful process of trying to convert\na bunch of scientific programmers from being CVS users to becoming git\nusers. In this process I ended up writing a sort of git in a nutshell\nguide for non-technical users. It struck me that this might be of\ninterest to others as well. I'm not a grand git wizard myself, so the\nguide is probably not entirely correct in every respect. All comments\nand suggestions are welcome! \nI have also written a CVS2git transition guide, which outlines one\npossible way of converting from CVS to git. This guide has some overlap\nwith the Git in a Nutshell guide, since I started with the CVS2git guide\nand then realised it was not quite enough. It would probably be a good\nidea to slim down the CVS2git guide, and move some of the discussion to\nthe Nushell guide instead. Let me know what you think. Both guides still\nneed quite a bit of polishing, but I hope they can be useful and\ninteresting in the crusade against CVS/SVN ;)If you think the guides\ncould benefit other users, they could maybe be posted (or at least\nlinked) on the git site.\n\nThe guides, including the LaTeX source, are available via gitweb:\nhttp://git.jonas.iki.fi/gitweb.cgi?p=git_guides.git;a=summary\n\n\n.jonas.\n"},{"id":"60306","messageId":"fhs33j$eg9$1@ger.gmane.org","threadId":"10929","inReplyTo":"1195477504.8093.15.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-19T13:29:23Z","receivedAt":"2007-11-19T13:29:23Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"A few comments (from what I checked so far):\n\n1. It is \"man git-checkout\" (or \"git checkout --help\"),\n   not \"man git checkout\"\n\n2. Instead of using 'verbatim' environment directly to show example CLI\n   session it would be I think better to define verbatim-like environment\n   for this ('example', 'commands', 'CLI', 'session'); perhaps replacing\n   verbatim by lstlisting from the listings/lstlisting package for syntax\n   highlighting.\n\nI'll send more comments after reading it in full...\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"60312","messageId":"loom.20071119T142453-421@post.gmane.org","threadId":"10929","inReplyTo":"fhs33j$eg9$1@ger.gmane.org","subject":"Re: Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas.juselius@chem.uit.no","sentAt":"2007-11-19T14:33:15Z","receivedAt":"2007-11-19T14:33:15Z","isPatch":false,"sender":{"key":"jonas.juselius@chem.uit.no","avatar":null},"body":"Jakub Narebski <jnareb <at> gmail.com> writes:\n> \n> A few comments (from what I checked so far):\n> \n> 1. It is \"man git-checkout\" (or \"git checkout --help\"),\n>    not \"man git checkout\"\n> \n> 2. Instead of using 'verbatim' environment directly to show example CLI\n>    session it would be I think better to define verbatim-like environment\n>    for this ('example', 'commands', 'CLI', 'session'); perhaps replacing\n>    verbatim by lstlisting from the listings/lstlisting package for syntax\n>    highlighting.\n> \n\nFirst, it seems that it was not entirely clear to everybody that it's possible\nto clone the repository:\n\ngit clone http://git.jonas.iki.fi/git_guides.git\n\nThanks for the comments: \n\n1. I did a global subst from the git-command to git\ncommand instead form, and forgot about the man pages ;)\n\n2. You are entirely right of course, but I was a bit lazy. I'll fix it at some\npoint. lstlistings is a very nice package.\n"},{"id":"60314","messageId":"20071119150209.GF6212@lavos.net","threadId":"10929","inReplyTo":"1195477504.8093.15.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Brian Downing","fromEmail":"bdowning@lavos.net","sentAt":"2007-11-19T15:02:09Z","receivedAt":"2007-11-19T15:02:09Z","isPatch":false,"sender":{"key":"bdowning@lavos.net","avatar":"https://avatars.githubusercontent.com/u/366426?v=4"},"body":"On Mon, Nov 19, 2007 at 02:05:04PM +0100, Jonas Juselius wrote:\n> I have also written a CVS2git transition guide, which outlines one\n> possible way of converting from CVS to git.\n\nYou write:\n\n> In order to save space you can also enable compression\n> $ git config --global core.compression 1\n> $ git config --global core.loosecompression 1\n\nI think this contradicts the git-config manpage:\n\n>  core.compression\n>      An integer -1..9, indicating a default compression level. -1 is the\n>      zlib default. 0 means no compression, and 1..9 are various\n>      speed/size tradeoffs, 9 being slowest.\n\n>  core.loosecompression\n>      An integer -1..9, indicating the compression level for objects that\n>      are not in a pack file. -1 is the zlib default. 0 means no\n>      compression, and 1..9 are various speed/size tradeoffs, 9 being\n>      slowest. If not set, defaults to core.compression. If that is not\n>      set, defaults to 0 (best speed).\n\nThe default, -1, is the zlib default, which is probably something like 3-6.\nSetting these to 1 will probably result in less compression, not more.\n\n-bcd\n"},{"id":"60315","messageId":"20071119150344.GG6212@lavos.net","threadId":"10929","inReplyTo":"20071119150209.GF6212@lavos.net","subject":"Re: Git in a Nutshell guide","fromName":"Brian Downing","fromEmail":"bdowning@lavos.net","sentAt":"2007-11-19T15:03:44Z","receivedAt":"2007-11-19T15:03:44Z","isPatch":false,"sender":{"key":"bdowning@lavos.net","avatar":"https://avatars.githubusercontent.com/u/366426?v=4"},"body":"On Mon, Nov 19, 2007 at 09:02:09AM -0600, Brian Downing wrote:\n> The default, -1, is the zlib default, which is probably something like 3-6.\n> Setting these to 1 will probably result in less compression, not more.\n\nIt's 6:\n\n>  Z_DEFAULT_COMPRESSION requests a default compromise between speed and\n>  compression (currently equivalent to level 6).\n\n-bcd\n"},{"id":"60319","messageId":"alpine.LFD.0.99999.0711191044500.19105@xanadu.home","threadId":"10929","inReplyTo":"20071119150209.GF6212@lavos.net","subject":"Re: Git in a Nutshell guide","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-11-19T15:48:08Z","receivedAt":"2007-11-19T15:48:08Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Mon, 19 Nov 2007, Brian Downing wrote:\n\n> On Mon, Nov 19, 2007 at 02:05:04PM +0100, Jonas Juselius wrote:\n> > I have also written a CVS2git transition guide, which outlines one\n> > possible way of converting from CVS to git.\n> \n> You write:\n> \n> > In order to save space you can also enable compression\n> > $ git config --global core.compression 1\n> > $ git config --global core.loosecompression 1\n> \n> I think this contradicts the git-config manpage:\n\nAlso, compression is always enabled by default with the adequate setting \nfor most usages anyway, so I think it is probably best not to talk about \nthose settings at all in a nutshell guide.\n\n\nNicolas\n"},{"id":"60321","messageId":"fhsc7b$k4g$1@ger.gmane.org","threadId":"10929","inReplyTo":"1195477504.8093.15.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-19T16:05:00Z","receivedAt":"2007-11-19T16:05:00Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jonas Juselius wrote:\n\n> The guides, including the LaTeX source, are available via gitweb:\n> http://git.jonas.iki.fi/gitweb.cgi?p=git_guides.git;a=summary\n\nBy the way, the description of this repository (for gitweb) is\n\"CVS to git migration guide\", the same as for CVS2git.git\n(shouldn't it be CVS2git_guide.git?).\n\n> First, it seems that it was not entirely clear to everybody that\n> it's possible to clone the repository:\n> \n>   git clone http://git.jonas.iki.fi/git_guides.git\n\nThanks.\n\nPerhaps you should have make gitweb.cgi with \n  GITWEB_BASE_URL=\"http://git.jonas.iki.fi\"\nthen, or configure @git_base_url_list in gitweb_config.perl.\n\nDo I understand correctly that you don't support cloning via git://\nprotocol?\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"60322","messageId":"1195488877.10573.29.camel@localhost","threadId":"10929","inReplyTo":"fhsc7b$k4g$1@ger.gmane.org","subject":"Re: Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas.juselius@chem.uit.no","sentAt":"2007-11-19T16:14:37Z","receivedAt":"2007-11-19T16:14:37Z","isPatch":false,"sender":{"key":"jonas.juselius@chem.uit.no","avatar":null},"body":"On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:\n> By the way, the description of this repository (for gitweb) is\n> \"CVS to git migration guide\", the same as for CVS2git.git\n> (shouldn't it be CVS2git_guide.git?).\n\nWell, it's the same repository. When I started out, I only planned to\nwrite the CVS2git manual. Then I wrote the Nutshell guide, and changed\nthe name of the repo, but I had already given the link to a bunch of\npeople so I kept the link.\n\n> \n> Perhaps you should have make gitweb.cgi with \n>   GITWEB_BASE_URL=\"http://git.jonas.iki.fi\"\n> then, or configure @git_base_url_list in gitweb_config.perl.\n> \n\nI'll look into that :)\n\n> Do I understand correctly that you don't support cloning via git://\n> protocol?\n\nYes, that is correct. The machine is behind a number of firewalls, and I\nsimply cannot be bothered to go through the bureaucracy...\n\n.j.\n\n"},{"id":"60326","messageId":"8c5c35580711190845s71a4880ek4ab28170d277e0e6@mail.gmail.com","threadId":"10929","inReplyTo":"1195477504.8093.15.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Lars Hjemli","fromEmail":"hjemli@gmail.com","sentAt":"2007-11-19T16:45:45Z","receivedAt":"2007-11-19T16:45:45Z","isPatch":false,"sender":{"key":"hjemli@gmail.com","avatar":null},"body":"On Nov 19, 2007 2:05 PM, Jonas Juselius <jonas.juselius@chem.uit.no> wrote:\n> All comments\n> and suggestions are welcome!\n\nVery nice introduction, but I have a couple of comments.\n\nIn \"Specifying revisions\" you say that '^' and '~' are equal, but that\nis not true. ^ is used to select the first parent of a commit, ^2\nselects the second parent of a merge commit (and ^3 selects the third\nparent of an octopus merge), while the '~' is used to go back any\nnumber of generations, following the first parents of each commit (~\nselects the first parent, ~2 selects the first grand-parent etc).\n\nAlso, I think you might scare users away from 'git reset':\n\n  git reset resets the branch to a specified state invisibly and\n  without possibility to go back. Ever. Your call.\n\nThat's not true, since any \"modern\" git has reflogs enabled. If you do\n'git reset --hard HEAD^^^' and then realize it was a mistake you can\njust 'git reset --hard HEAD@{1}'\n\n-- \nlarsh\n"},{"id":"60328","messageId":"3057F6F3-BEAA-447A-AB79-A0AFB7DB8826@lrde.epita.fr","threadId":"10929","inReplyTo":"1195488877.10573.29.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Benoit Sigoure","fromEmail":"tsuna@lrde.epita.fr","sentAt":"2007-11-19T16:49:21Z","receivedAt":"2007-11-19T16:49:21Z","isPatch":false,"sender":{"key":"tsunanet@gmail.com","avatar":"https://avatars.githubusercontent.com/u/128281?v=4"},"body":"On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:\n> On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:\n>> Do I understand correctly that you don't support cloning via git://\n>> protocol?\n>\n> Yes, that is correct. The machine is behind a number of firewalls,  \n> and I\n> simply cannot be bothered to go through the bureaucracy...\n\nYou can create a repository on repo.or.cz then :)\n\nAs it is often the case different people happen to work on similar  \nthings without knowing each other.  I started http://repo.or.cz/w/ \ntutorial.git which is meant to be a big Beamer presentation that  \npresents Git thoroughly.  I wrote some ideas but didn't start to  \nwrite the slides.  Just in case you want to have a look.\n\nOne of the things you said in your guide is that Git is easy to  \nlearn.  I think this is wrong.  Git is way more complicated than most  \nother SCMs, especially compared to SVN.  Its documentation is far  \nbehind, compared to what other SCMs have.  There is no real user  \nguide and the man pages are incomplete, at best.  I know saying this  \nis a bit harsh, especially to the people out there that are working  \nand sending patches to improve the documentation, but I think we have  \nto admit that it's true, even though Git is making progress on this  \naspect.\n\nWhat I hope to achieve, when I'll have time to write my slides, is to  \nhave some sort of equivalent of the wonderful Autotools tutorial  \n(http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/ \nautotools.html) which is definitely the only thing you need to read  \nwhen you want to learn the Autotools (which are also quite  \ncomplicated, let's admit it).\n\nPlease don't flame me by saying that Git isn't hard to use and  \neverything.  It's the typical reaction of people who know how the  \nthings work.  Git is pretty simple to use once you know how it  \nworks.  But compared to SVN (for instance) it's hard to learn.   \nPeople have to change the way they work to take all the benefits of  \nGit, and to do this, they have to understand why that new way of  \nworking differently is better for them.\n\n-- \nBenoit Sigoure aka Tsuna\nEPITA Research and Development Laboratory\n\n\n"},{"id":"60332","messageId":"1195491382.10573.34.camel@localhost","threadId":"10929","inReplyTo":"8c5c35580711190845s71a4880ek4ab28170d277e0e6@mail.gmail.com","subject":"Re: Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas.juselius@chem.uit.no","sentAt":"2007-11-19T16:56:22Z","receivedAt":"2007-11-19T16:56:22Z","isPatch":false,"sender":{"key":"jonas.juselius@chem.uit.no","avatar":null},"body":"\nOn Mon, 2007-11-19 at 17:45 +0100, Lars Hjemli wrote:\n> \n> Very nice introduction, but I have a couple of comments.\n> \nThank you :)\n\n> In \"Specifying revisions\" you say that '^' and '~' are equal, but that\n> is not true. ^ is used to select the first parent of a commit, ^2\n> selects the second parent of a merge commit (and ^3 selects the third\n> parent of an octopus merge), while the '~' is used to go back any\n> number of generations, following the first parents of each commit (~\n> selects the first parent, ~2 selects the first grand-parent etc).\n> \n\nThanks for the the clarification. I've never done an octopus, so I\nsimply ignored the matter. I'll correct the text and add a footnote.\n\n> Also, I think you might scare users away from 'git reset':\n> \n>   git reset resets the branch to a specified state invisibly and\n>   without possibility to go back. Ever. Your call.\n> \n> That's not true, since any \"modern\" git has reflogs enabled. If you do\n> 'git reset --hard HEAD^^^' and then realize it was a mistake you can\n> just 'git reset --hard HEAD@{1}'\n> \nThis was new to me ;) I'll correct and add a note on reflogs.\n\n.j.\n"},{"id":"60330","messageId":"E983072E-E9FD-499E-A418-B630A275C4F3@lrde.epita.fr","threadId":"10929","inReplyTo":"8c5c35580711190845s71a4880ek4ab28170d277e0e6@mail.gmail.com","subject":"Re: Git in a Nutshell guide","fromName":"Benoit Sigoure","fromEmail":"tsuna@lrde.epita.fr","sentAt":"2007-11-19T16:57:50Z","receivedAt":"2007-11-19T16:57:50Z","isPatch":false,"sender":{"key":"tsunanet@gmail.com","avatar":"https://avatars.githubusercontent.com/u/128281?v=4"},"body":"On Nov 19, 2007, at 5:45 PM, Lars Hjemli wrote:\n\n> On Nov 19, 2007 2:05 PM, Jonas Juselius  \n> <jonas.juselius@chem.uit.no> wrote:\n> Also, I think you might scare users away from 'git reset':\n>\n>   git reset resets the branch to a specified state invisibly and\n>   without possibility to go back. Ever. Your call.\n>\n> That's not true, since any \"modern\" git has reflogs enabled. If you do\n> 'git reset --hard HEAD^^^' and then realize it was a mistake you can\n> just 'git reset --hard HEAD@{1}'\n\nYes, I've always been very scared of git-reset until I had a somewhat  \nbetter understanding of Git internals.  In fact the only danger of  \n`git reset --hard' is that you loose dirty changes (not yet in the  \nindex) and staged changes (in the index).  git-reset will never, ever  \ndelete objects from your repo.  Thus, you can perfectly well remember  \nthe current revision sha1 (let's call it `A') and then git reset -- \nhard HEAD~42 and then git reset --hard A.  In between the two Git  \ncommands, it's possible that all the objects of the history from  \nHEAD~42..A be unreachable.  Nothing wrong with this, it just that if  \nrun, say, git gc --prune (note the --prune) you will loose them.\n\nUnderstanding this is very important because ``error humanum est'',  \nand people happen to screw up their hard work and they don't realize  \nthat they can go back without even knowing what the hell the reflog  \nis or how to use it (I personally don't know -- but I'd like to, give  \nme pointers please :D).  For instance, I once rebased a dozen of  \ncommits on a given branch and I realised that I completely screwed my  \nnice patch series by collapsing changes, introducing changes at the  \nwrong revision etc.  I could start over again by simply doing a git  \nreset --hard <HEAD_sha1_before_rebase>.\n\nCheers,\n\n-- \nBenoit Sigoure aka Tsuna\nEPITA Research and Development Laboratory\n\n\n"},{"id":"60333","messageId":"8c5c35580711190904v5975e81k3d515dc44fee9c21@mail.gmail.com","threadId":"10929","inReplyTo":"E983072E-E9FD-499E-A418-B630A275C4F3@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Lars Hjemli","fromEmail":"hjemli@gmail.com","sentAt":"2007-11-19T17:04:11Z","receivedAt":"2007-11-19T17:04:11Z","isPatch":false,"sender":{"key":"hjemli@gmail.com","avatar":null},"body":"On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:\n> Understanding this is very important because ``error humanum est'',\n> and people happen to screw up their hard work and they don't realize\n> that they can go back without even knowing what the hell the reflog\n> is or how to use it (I personally don't know -- but I'd like to, give\n> me pointers please :D).\n\nYou can simply try 'git reflog', and then 'man git-reflog' ;-)\n\n--\nlarsh\n"},{"id":"60336","messageId":"vpqejemtbc3.fsf@bauges.imag.fr","threadId":"10929","inReplyTo":"E983072E-E9FD-499E-A418-B630A275C4F3@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T17:05:32Z","receivedAt":"2007-11-19T17:05:32Z","isPatch":false,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n\n>  git reset --hard HEAD~42 and then git reset --hard A.\n\nAnd if you don't \"remember\" A, the reflog is here for you.\n\n$ git reflog show HEAD\n$ git reset --hard HEAD@{42} # not \"the 42th ancestor\"\n                             # but \"where HEAD was 42 moves ago\".\n\nBy default, the reflog will expire after IIRC, 3 months, and git-prune\nwill not prune the objects while they are reachable.\n\nSo, it's even safer than you say ;-).\n\n-- \nMatthieu\n"},{"id":"60342","messageId":"25CF3422-A236-46CE-B243-3F01117B7743@lrde.epita.fr","threadId":"10929","inReplyTo":"8c5c35580711190904v5975e81k3d515dc44fee9c21@mail.gmail.com","subject":"Re: Git in a Nutshell guide","fromName":"Benoit Sigoure","fromEmail":"tsuna@lrde.epita.fr","sentAt":"2007-11-19T18:10:07Z","receivedAt":"2007-11-19T18:10:07Z","isPatch":false,"sender":{"key":"tsunanet@gmail.com","avatar":"https://avatars.githubusercontent.com/u/128281?v=4"},"body":"On Nov 19, 2007, at 6:04 PM, Lars Hjemli wrote:\n\n> On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:\n>> Understanding this is very important because ``error humanum est'',\n>> and people happen to screw up their hard work and they don't realize\n>> that they can go back without even knowing what the hell the reflog\n>> is or how to use it (I personally don't know -- but I'd like to, give\n>> me pointers please :D).\n>\n> You can simply try 'git reflog', and then 'man git-reflog' ;-)\n\nDid you only read the man?  It doesn't explain how to use the reflog  \nor I must have a very hard time understanding it.  I don't know where  \nthe HEAD@{N} syntax is documented, but surely not in man git-reflog.\n\nCheers,\n\n-- \nBenoit Sigoure aka Tsuna\nEPITA Research and Development Laboratory\n\n\n"},{"id":"60343","messageId":"20071119181358.GG10450@fieldses.org","threadId":"10929","inReplyTo":"25CF3422-A236-46CE-B243-3F01117B7743@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-19T18:13:58Z","receivedAt":"2007-11-19T18:13:58Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Nov 19, 2007 at 07:10:07PM +0100, Benoit Sigoure wrote:\n> On Nov 19, 2007, at 6:04 PM, Lars Hjemli wrote:\n>\n>> On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:\n>>> Understanding this is very important because ``error humanum est'',\n>>> and people happen to screw up their hard work and they don't realize\n>>> that they can go back without even knowing what the hell the reflog\n>>> is or how to use it (I personally don't know -- but I'd like to, give\n>>> me pointers please :D).\n>>\n>> You can simply try 'git reflog', and then 'man git-reflog' ;-)\n>\n> Did you only read the man?  It doesn't explain how to use the reflog or I \n> must have a very hard time understanding it.  I don't know where the \n> HEAD@{N} syntax is documented, but surely not in man git-reflog.\n\nMy copy at least has this paragraph:\n\n\tThe subcommand \"show\" (which is also the default, in the absence of any\n       subcommands) will take all the normal log options, and show the log of\n       HEAD, which will cover all recent actions, including branch switches.\n       It is basically an alias for git log -g --abbrev-commit\n       --pretty=oneline, see git-log(1).\n\nBut, yeah, HEAD@{N} isn't documented there or in git-log(1), it's in\ngit-rev-parse(1).  I agree that the git-reflog manpage should at least\nreference all of this, as it's the obvious first place people will go to learn\nabout reflogs....\n\n--b.\n"},{"id":"60344","messageId":"vpqtznirtlk.fsf@bauges.imag.fr","threadId":"10929","inReplyTo":"25CF3422-A236-46CE-B243-3F01117B7743@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T18:13:59Z","receivedAt":"2007-11-19T18:13:59Z","isPatch":false,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n\n> Did you only read the man?  It doesn't explain how to use the reflog\n> or I must have a very hard time understanding it.  I don't know where\n> the HEAD@{N} syntax is documented, but surely not in man git-reflog.\n\nhttp://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html\n\nI'll post a patch adding a link to that in the reflog man page.\n\n-- \nMatthieu\n"},{"id":"60348","messageId":"1195497342-26334-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"10929","inReplyTo":"vpqtznirtlk.fsf@bauges.imag.fr","subject":"[PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T18:35:42Z","receivedAt":"2007-11-19T18:35:42Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The HEAD@{...} syntax was documented in git-rev-parse manpage, which\nis hard to find by someone looking for the documentation of porcelain.\ngit-reflog is probably the place where one expects to find this.\n\nWhile I'm there, \"git revlog show whatever\" was also undocumented.\n---\n Documentation/git-reflog.txt |   11 +++++++++--\n 1 files changed, 9 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 5c7316c..aeac6f0 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -19,7 +19,7 @@ depending on the subcommand:\n git reflog expire [--dry-run] [--stale-fix] [--verbose]\n \t[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...\n \n-git reflog [show] [log-options]\n+git reflog [show] [log-options] [<ref>]\n \n Reflog is a mechanism to record when the tip of branches are\n updated.  This command is to manage the information recorded in it.\n@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].\n \n The subcommand \"show\" (which is also the default, in the absence of any\n subcommands) will take all the normal log options, and show the log of\n-`HEAD`, which will cover all recent actions, including branch switches.\n+`HEAD`, or of the reference provided in the command-line, which will\n+cover all recent actions, including branch switches.\n It is basically an alias for 'git log -g --abbrev-commit\n --pretty=oneline', see gitlink:git-log[1].\n \n+The reflog is useful in various git commands, to specify the old value\n+of a reference. For example, `HEAD@\\{2\\}` means \"where HEAD used to be\n+two moves ago\", `master@\\{one.week.ago\\}` means \"where master used to\n+point to one week ago\", and so on. See gitlink:git-rev-parse[1] for\n+more details.\n+\n \n OPTIONS\n -------\n-- \n1.5.3.5.724.g49d9d\n"},{"id":"60357","messageId":"7vtznim1s5.fsf@gitster.siamese.dyndns.org","threadId":"10929","inReplyTo":"1195497342-26334-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-19T20:13:46Z","receivedAt":"2007-11-19T20:13:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy <Matthieu.Moy@imag.fr> writes:\n\n> The HEAD@{...} syntax was documented in git-rev-parse manpage, which\n> is hard to find by someone looking for the documentation of porcelain.\n> git-reflog is probably the place where one expects to find this.\n>\n> While I'm there, \"git revlog show whatever\" was also undocumented.\n\nThanks.  The new HEAD@{N} description is concise and nice.\n\n>  The subcommand \"show\" (which is also the default, in the absence of any\n>  subcommands) will take all the normal log options, and show the log of\n> -`HEAD`, which will cover all recent actions, including branch switches.\n> +`HEAD`, or of the reference provided in the command-line, which will\n> +cover all recent actions, including branch switches.\n>  It is basically an alias for 'git log -g --abbrev-commit\n>  --pretty=oneline', see gitlink:git-log[1].\n\nBut the wording added with \"While I'm there\" change seems wrong\nto me.  \"..., which will cover all recent actions\" is about the\nreflog attached to HEAD but the new phrase inserted in the\nmiddle makes it unclear.\n"},{"id":"60359","messageId":"1195504133-7823-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"10929","inReplyTo":"7vtznim1s5.fsf@gitster.siamese.dyndns.org","subject":"[PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T20:28:53Z","receivedAt":"2007-11-19T20:28:53Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The HEAD@{...} syntax was documented in git-rev-parse manpage, which\nis hard to find by someone looking for the documentation of porcelain.\ngit-reflog is probably the place where one expects to find this.\n\nWhile I'm there, \"git revlog show whatever\" was also undocumented.\n\nSigned-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>\n---\n Documentation/git-reflog.txt |   11 +++++++++--\n 1 files changed, 9 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 5c7316c..aeac6f0 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -19,7 +19,7 @@ depending on the subcommand:\n git reflog expire [--dry-run] [--stale-fix] [--verbose]\n \t[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...\n \n-git reflog [show] [log-options]\n+git reflog [show] [log-options] [<ref>]\n \n Reflog is a mechanism to record when the tip of branches are\n updated.  This command is to manage the information recorded in it.\n@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].\n \n The subcommand \"show\" (which is also the default, in the absence of any\n subcommands) will take all the normal log options, and show the log of\n-`HEAD`, which will cover all recent actions, including branch switches.\n+`HEAD`, or of the reference provided in the command-line, which will\n+cover all recent actions, including branch switches.\n It is basically an alias for 'git log -g --abbrev-commit\n --pretty=oneline', see gitlink:git-log[1].\n \n+The reflog is useful in various git commands, to specify the old value\n+of a reference. For example, `HEAD@\\{2\\}` means \"where HEAD used to be\n+two moves ago\", `master@\\{one.week.ago\\}` means \"where master used to\n+point to one week ago\", and so on. See gitlink:git-rev-parse[1] for\n+more details.\n+\n \n OPTIONS\n -------\n-- \n1.5.3.5.724.g49d9d\n"},{"id":"60360","messageId":"vpqoddqq8n5.fsf@bauges.imag.fr","threadId":"10929","inReplyTo":"1195504133-7823-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T20:31:58Z","receivedAt":"2007-11-19T20:31:58Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Matthieu Moy <Matthieu.Moy@imag.fr> writes:\n\n> -`HEAD`, which will cover all recent actions, including branch switches.\n> +`HEAD`, or of the reference provided in the command-line, which will\n> +cover all recent actions, including branch switches.\n\nOoops, appologize. I didn't commit my change, this patch isn't any\nbetter than the previous.\n\nThe one below should be correct (the sentence was getting long, I've\nsplitted it):\n\n\n\n>From d71c6c8e24a5a08600f3347b4ad014e459f9f3df Mon Sep 17 00:00:00 2001\nFrom: Matthieu Moy <Matthieu.Moy@imag.fr>\nDate: Mon, 19 Nov 2007 19:25:11 +0100\nSubject: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.\n\nThe HEAD@{...} syntax was documented in git-rev-parse manpage, which\nis hard to find by someone looking for the documentation of porcelain.\ngit-reflog is probably the place where one expects to find this.\n\nWhile I'm there, \"git revlog show whatever\" was also undocumented.\n\nSigned-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>\n---\n Documentation/git-reflog.txt |   11 +++++++++--\n 1 files changed, 9 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 5c7316c..1bd54c5 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -19,7 +19,7 @@ depending on the subcommand:\n git reflog expire [--dry-run] [--stale-fix] [--verbose]\n \t[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...\n \n-git reflog [show] [log-options]\n+git reflog [show] [log-options] [<ref>]\n \n Reflog is a mechanism to record when the tip of branches are\n updated.  This command is to manage the information recorded in it.\n@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].\n \n The subcommand \"show\" (which is also the default, in the absence of any\n subcommands) will take all the normal log options, and show the log of\n-`HEAD`, which will cover all recent actions, including branch switches.\n+the reference provided in the command-line (or `HEAD`, by default).\n+The log will cover all recent actions, including branch switches.\n It is basically an alias for 'git log -g --abbrev-commit\n --pretty=oneline', see gitlink:git-log[1].\n \n+The reflog is useful in various git commands, to specify the old value\n+of a reference. For example, `HEAD@\\{2\\}` means \"where HEAD used to be\n+two moves ago\", `master@\\{one.week.ago\\}` means \"where master used to\n+point to one week ago\", and so on. See gitlink:git-rev-parse[1] for\n+more details.\n+\n \n OPTIONS\n -------\n-- \n1.5.3.5.724.g49d9d\n"},{"id":"60365","messageId":"60891A14-1D6E-4114-ACEF-4C981D326CFA@lrde.epita.fr","threadId":"10929","inReplyTo":"vpqtznirtlk.fsf@bauges.imag.fr","subject":"Re: Git in a Nutshell guide","fromName":"Benoit Sigoure","fromEmail":"tsuna@lrde.epita.fr","sentAt":"2007-11-19T21:15:21Z","receivedAt":"2007-11-19T21:15:21Z","isPatch":false,"sender":{"key":"tsunanet@gmail.com","avatar":"https://avatars.githubusercontent.com/u/128281?v=4"},"body":"On Nov 19, 2007, at 7:13 PM, Matthieu Moy wrote:\n\n> Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n>\n>> Did you only read the man?  It doesn't explain how to use the reflog\n>> or I must have a very hard time understanding it.  I don't know where\n>> the HEAD@{N} syntax is documented, but surely not in man git-reflog.\n>\n> http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html\n>\n> I'll post a patch adding a link to that in the reflog man page.\n\nNo please stop adding links from on man page to another.  If you read  \nman git-reflog, you surely want to learn the HEAD@{N} syntax and see  \npractical uses cases.  One of the complaints against Git (which also  \ncame up in the Git Users' Survey) is that man pages are harder to use  \nbecause they often refer to each other and they tend to list their  \nnumerous arguments out of order.  Many arguments are clearly plumbing  \nand should be mentioned in a different section (I guess it would be  \nbetter to list the most useful arguments in alphabetical order first  \nand then list the remaining arguments in another section, still in  \nalphabetical order).\n\n-- \nBenoit Sigoure aka Tsuna\nEPITA Research and Development Laboratory\n\n\n"},{"id":"60366","messageId":"vpq63zxq5s2.fsf@bauges.imag.fr","threadId":"10929","inReplyTo":"60891A14-1D6E-4114-ACEF-4C981D326CFA@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T21:33:49Z","receivedAt":"2007-11-19T21:33:49Z","isPatch":false,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n\n> No please stop adding links from on man page to another.  If you read\n> man git-reflog, you surely want to learn the HEAD@{N} syntax and see\n> practical uses cases.\n\nI don't understand your point.\n\nYes, if I read man git-reflog, I do surely want to learn HEAD@{N}\nsyntax, but that is _precisely_ what my patch does.\n\n-- \nMatthieu\n"},{"id":"60367","messageId":"0E0AA90A-2282-4AFE-8B94-EA0E35B57D65@lrde.epita.fr","threadId":"10929","inReplyTo":"vpq63zxq5s2.fsf@bauges.imag.fr","subject":"Re: Git in a Nutshell guide","fromName":"Benoit Sigoure","fromEmail":"tsuna@lrde.epita.fr","sentAt":"2007-11-19T21:51:35Z","receivedAt":"2007-11-19T21:51:35Z","isPatch":false,"sender":{"key":"tsunanet@gmail.com","avatar":"https://avatars.githubusercontent.com/u/128281?v=4"},"body":"On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:\n\n> Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n>\n>> No please stop adding links from on man page to another.  If you read\n>> man git-reflog, you surely want to learn the HEAD@{N} syntax and see\n>> practical uses cases.\n>\n> I don't understand your point.\n>\n> Yes, if I read man git-reflog, I do surely want to learn HEAD@{N}\n> syntax, but that is _precisely_ what my patch does.\n\nBy telling you to read another man page which is annoying and a  \nrecurring complaint.\n\n-- \nBenoit Sigoure aka Tsuna\nEPITA Research and Development Laboratory\n\n\n"},{"id":"60368","messageId":"Pine.LNX.4.64.0711191617150.12193@iabervon.org","threadId":"10929","inReplyTo":"3057F6F3-BEAA-447A-AB79-A0AFB7DB8826@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2007-11-19T22:01:23Z","receivedAt":"2007-11-19T22:01:23Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Mon, 19 Nov 2007, Benoit Sigoure wrote:\n\n> On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:\n> >On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:\n> > >Do I understand correctly that you don't support cloning via git://\n> > >protocol?\n> >\n> >Yes, that is correct. The machine is behind a number of firewalls, and I\n> >simply cannot be bothered to go through the bureaucracy...\n> \n> You can create a repository on repo.or.cz then :)\n> \n> As it is often the case different people happen to work on similar things\n> without knowing each other.  I started http://repo.or.cz/w/tutorial.git which\n> is meant to be a big Beamer presentation that presents Git thoroughly.  I\n> wrote some ideas but didn't start to write the slides.  Just in case you want\n> to have a look.\n> \n> One of the things you said in your guide is that Git is easy to learn.  I\n> think this is wrong.  Git is way more complicated than most other SCMs,\n> especially compared to SVN.\n\nI convinced my little company to switch to git (from arch, so take this \nwith a grain of salt). I'd previously written a document explaining how to \nuse arch, and I wrote a version for git, which said practically nothing, \nbecause everything I'd been able to do in arch is trivial to do in git. \nBut I used the same format, anyway, to be sure to cover everything. I also \ntold them to ask me if they were trying to do something and couldn't. I \nbelieve that all of the questions I've gotten were on how to use \"advanced \nfeatures\" (i.e., things not included in my document because I never \nfigured out how to do them with arch and decided to just live without), \nand people are using git successfully.\n\nThe main difference I see is that \"save\" and \"publish\" are separate \noperations with git and the same with other SCMs, but the separate \nconcepts are obvious to anybody who's emailled a word processor document \nto somebody, and the distinction just has to be mentioned.\n\nThe challenge in writing a good introduction to git is leaving out \nexplanations of all of the wonderful things that git can do that people \ndon't expect to be within the abilities of an SCM. If you limit yourself \nto saying how to do things that SCMs can traditionally do, and therefore \nonly explain how to do what people know they want to do, it's not to hard \nfor people to learn. Of course, that's not enough to make good use of git, \nbut it's enough to declare a transition from SVN or CVS successful.\n\nI personally think it would be worth having a pair of documents, with the \nfirst being \"everything you need to know\", and the second being \"things \nyou'll find helpful that aren't strictly necessary\".\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"60371","messageId":"20071119222305.GE22293@fieldses.org","threadId":"10929","inReplyTo":"0E0AA90A-2282-4AFE-8B94-EA0E35B57D65@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-11-19T22:23:05Z","receivedAt":"2007-11-19T22:23:05Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Nov 19, 2007 at 10:51:35PM +0100, Benoit Sigoure wrote:\n> On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:\n>\n>> Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n>>\n>>> No please stop adding links from on man page to another.  If you read\n>>> man git-reflog, you surely want to learn the HEAD@{N} syntax and see\n>>> practical uses cases.\n>>\n>> I don't understand your point.\n>>\n>> Yes, if I read man git-reflog, I do surely want to learn HEAD@{N}\n>> syntax, but that is _precisely_ what my patch does.\n>\n> By telling you to read another man page which is annoying and a recurring \n> complaint.\n\nAre we looking at the same patch?  It both gives examples of the syntax\n*and* refers to another page.  I thought it was the lack of the former,\nrather than the presence of the latter, that was the recurring\ncomplaint....\n\n--b.\n"},{"id":"60374","messageId":"7v7ikdna24.fsf@gitster.siamese.dyndns.org","threadId":"10929","inReplyTo":"0E0AA90A-2282-4AFE-8B94-EA0E35B57D65@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-19T22:29:39Z","receivedAt":"2007-11-19T22:29:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n\n> On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:\n>\n>> Benoit Sigoure <tsuna@lrde.epita.fr> writes:\n>>\n>>> No please stop adding links from on man page to another.  If you read\n>>> man git-reflog, you surely want to learn the HEAD@{N} syntax and see\n>>> practical uses cases.\n>>\n>> I don't understand your point.\n>>\n>> Yes, if I read man git-reflog, I do surely want to learn HEAD@{N}\n>> syntax, but that is _precisely_ what my patch does.\n>\n> By telling you to read another man page which is annoying and a\n> recurring complaint.\n\nWhich is a valid point.  We could move that part into a separate\nsource file and include it from different places appropriately,\njust we have done for the common diff options.\n\nHowever, you need to think about what's appropriate.  Any\ncommand that potentially takes a ref as (one of) its parameter?\nThat means almost everybody.\n\nI think the ref naming syntax is so commonly used and\nfundamental that we could treat it as prerequiste for individual\nmanual pages.  Maybe move the section to git(7)?  That would\ncertainly be better than having it in git-rev-parse(1), but does\nnot reduce the cross referencing complaints.\n"},{"id":"60378","messageId":"vpqd4u5zvs3.fsf@bauges.imag.fr","threadId":"10929","inReplyTo":"7v7ikdna24.fsf@gitster.siamese.dyndns.org","subject":"Re: Git in a Nutshell guide","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-11-19T22:59:40Z","receivedAt":"2007-11-19T22:59:40Z","isPatch":false,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> I think the ref naming syntax is so commonly used and\n> fundamental that we could treat it as prerequiste for individual\n> manual pages.  Maybe move the section to git(7)?  That would\n> certainly be better than having it in git-rev-parse(1), but does\n> not reduce the cross referencing complaints.\n\nWell, obviously, something which isn't addressed by my patch is the\nfact that some of the documentation an average user needs is in the\nplumbing man pages.\n\n(Gosh, I was going to cite the manpage for git-log and git-rev-parse\nas an example, but it has already been fixed :-). Good job !)\n\ngit-rev-parse(1) is full of terribly usefull information, and that\ninformation is definitely not in the place an average user would look\nat.\n\nI have no ideal solution for that. git(7) is already really long.\nPerhaps some \"topic man pages\" would be good. By \"topic man page\", I\nmean \"man git-something\" where \"something\" isn't a git command, but a\ncrosscutting concept. For example, here, \"man git-refspec\" to document\nreference specifiers like HEAD@{42}, master~55, d71c6c8e24a and\nfriends. \"man git-i18n\" would be another candidate.\n\nAnyway, my patch is definitely a step forward, even if it's just the\nfirst, small one ;-).\n\n-- \nMatthieu\n"},{"id":"60380","messageId":"7v3av1n8ad.fsf@gitster.siamese.dyndns.org","threadId":"10929","inReplyTo":"vpqd4u5zvs3.fsf@bauges.imag.fr","subject":"Re: Git in a Nutshell guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-19T23:07:54Z","receivedAt":"2007-11-19T23:07:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy <Matthieu.Moy@imag.fr> writes:\n\n> I have no ideal solution for that. git(7) is already really long.\n> Perhaps some \"topic man pages\" would be good. By \"topic man page\", I\n> mean \"man git-something\" where \"something\" isn't a git command, but a\n> crosscutting concept. For example, here, \"man git-refspec\" to document\n> reference specifiers like HEAD@{42}, master~55, d71c6c8e24a and\n> friends. \"man git-i18n\" would be another candidate.\n\nYeah, gitattributes(5), gitignore(5) and gitmodules(5) can take\nadvantage of the fact that they define file formats and describe\nthe underlying concepts in their own corner while describing the\nfile format.  But there are many other things (e.g. syntax for\nrefspec, ref naming) that would benefit from having their own\ntopic-centric documents, without defining their own file format,\nso git-refspec(5) trick is not an option for them.\n"},{"id":"60405","messageId":"1195558478.10369.8.camel@localhost","threadId":"10929","inReplyTo":"3057F6F3-BEAA-447A-AB79-A0AFB7DB8826@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas.juselius@chem.uit.no","sentAt":"2007-11-20T11:34:38Z","receivedAt":"2007-11-20T11:34:38Z","isPatch":false,"sender":{"key":"jonas.juselius@chem.uit.no","avatar":null},"body":"On Mon, 2007-11-19 at 17:49 +0100, Benoit Sigoure wrote:\n> You can create a repository on repo.or.cz then :)\nI will :=)\n> \n> As it is often the case different people happen to work on similar  \n> things without knowing each other.  I started http://repo.or.cz/w/ \n> tutorial.git which is meant to be a big Beamer presentation that  \n> presents Git thoroughly.  I wrote some ideas but didn't start to  \n> write the slides.  Just in case you want to have a look.\nThanks, there are certainly some things in that document that I ought to\nconsider incorporating in the guide. But for now I'll let it rest for a\nlittle while, because I don't have time to mess with it. Patches are\nalways welcome ;)\n\n> One of the things you said in your guide is that Git is easy to  \n> learn.  I think this is wrong.  Git is way more complicated than most  \n> other SCMs, especially compared to SVN.  Its documentation is far  \n> behind, compared to what other SCMs have.  There is no real user  \n> guide and the man pages are incomplete, at best.  I know saying this  \n> is a bit harsh, especially to the people out there that are working  \n> and sending patches to improve the documentation, but I think we have  \n> to admit that it's true, even though Git is making progress on this  \n> aspect.\nWell, you are right to some extent. But it's this gap I would like to\nfill with the nutshell guide. The \"for normal people\" slogan is meant to\nrefer to non-technical developers (like scientists). I should probably\ninclude a little section in the intro describing distributed vs.\ncentralised SCMs in general.\n\nThanks for the input,\n\n.jonas.\n"},{"id":"60445","messageId":"fhvs95$5qk$1@ger.gmane.org","threadId":"10929","inReplyTo":"3057F6F3-BEAA-447A-AB79-A0AFB7DB8826@lrde.epita.fr","subject":"Re: Git in a Nutshell guide","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-20T23:57:28Z","receivedAt":"2007-11-20T23:57:28Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Benoit Sigoure wrote:\n\n> On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:\n>> On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:\n>>> Do I understand correctly that you don't support cloning via git://\n>>> protocol?\n>>\n>> Yes, that is correct. The machine is behind a number of firewalls,  \n>> and I simply cannot be bothered to go through the bureaucracy...\n> \n> You can create a repository on repo.or.cz then :)\n\nWhich can then function as a mirror.\n\n> One of the things you said in your guide is that Git is easy to  \n> learn.  I think this is wrong.  Git is way more complicated than most  \n> other SCMs, especially compared to SVN.  Its documentation is far  \n> behind, compared to what other SCMs have.  There is no real user  \n> guide \n\nWhat about \"Git User's Manual\"?\n\n> and the man pages are incomplete, at best.  I know saying this   \n> is a bit harsh, especially to the people out there that are working  \n> and sending patches to improve the documentation, but I think we have  \n> to admit that it's true, even though Git is making progress on this  \n> aspect.\n\nThat's sadly true, and confirmed (somewhat) by the fact that both in 2006\nuser's survey and in 2007 survey (see Git Wiki for summaries) one of more\ncommon requests are for \"better documentation\" and \"The Git Book\" (showing\nsvnbook and hgbook as examples).\n\n[cut]\n\nI think that writing proper \"Git Guide\" aka \"The Git Book\" is hard because\nof some things:\n\n 1. Git has many useful advanced features. Describing those advanced\n    features is not easy. For example git uses multiple branches in single\n    repository paradigm freely, which makes learning curve a bit steeper;\n    IIRC hgbook describes one branch per repos situation (at least at\n    beginning), which is easier.\n\n 2. Git has some historical cruft, including the fact that it began as\n    series of low level tools (plumbing) and became proper SCM (acquired\n    proper porcelain) later, what can be even now seen in documentation...\n\n 3. Explanation of some features (like object model) would be much easier\n    with some graphics (diagrams etc.), but chosen documentation format,\n    AsciiDoc, doesn't make it easy...\n\nYust my 2 eurocents.\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"60557","messageId":"20071121194507.GA3569@efreet.light.src","threadId":"10929","inReplyTo":"fhvs95$5qk$1@ger.gmane.org","subject":"Re: Git in a Nutshell guide","fromName":"Jan Hudec","fromEmail":"bulb@ucw.cz","sentAt":"2007-11-21T19:45:07Z","receivedAt":"2007-11-21T19:45:07Z","isPatch":false,"sender":{"key":"bulb@ucw.cz","avatar":null},"body":"On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:\n> I think that writing proper \"Git Guide\" aka \"The Git Book\" is hard because\n> of some things:\n> \n>  1. Git has many useful advanced features. Describing those advanced\n>     features is not easy. For example git uses multiple branches in single\n>     repository paradigm freely, which makes learning curve a bit steeper;\n>     IIRC hgbook describes one branch per repos situation (at least at\n>     beginning), which is easier.\n\nI think I saw the \"sharp curve\" and \"double sharp curve\" paragraphs in other\nplaces besides the the TeXbook. I even have an impression (without actually\nlooking) that it was documentation of some version control system.\n\nThat deals with difficult to read, but it does make it more difficult to\nwrite.\n\n>  2. Git has some historical cruft, including the fact that it began as\n>     series of low level tools (plumbing) and became proper SCM (acquired\n>     proper porcelain) later, what can be even now seen in documentation...\n\nMost plumbing can be safely ignored through most of the book or covered by\nthose \"double sharp curve\" paragraphs. It unfortunately does make it harder\nto write, because the author has to consider what to cover and what to hide.\n\n>  3. Explanation of some features (like object model) would be much easier\n>     with some graphics (diagrams etc.), but chosen documentation format,\n>     AsciiDoc, doesn't make it easy...\n\nI dare to disagree here. Asciidoc supports generating image tags for\nrespective output formats and it really does not look hard. We could have\nPNGs and if we wanted higher press quality even SVG or EPS and convert them\nto PNGs for the HTML version (and use EPS for latex output).\n\n-- \n\t\t\t\t\t\t Jan 'Bulb' Hudec <bulb@ucw.cz>\n"},{"id":"60569","messageId":"200711212232.33791.jnareb@gmail.com","threadId":"10929","inReplyTo":"20071121194507.GA3569@efreet.light.src","subject":"Re: Git in a Nutshell guide","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-21T21:32:33Z","receivedAt":"2007-11-21T21:32:33Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:\n> On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:\n\n>>  2. Git has some historical cruft, including the fact that it began as\n>>     series of low level tools (plumbing) and became proper SCM (acquired\n>>     proper porcelain) later, what can be even now seen in documentation...\n\nWhat I meant here that some of important documentation can be only\nfound in plumbing commands man pages.\n\n>>  3. Explanation of some features (like object model) would be much easier\n>>     with some graphics (diagrams etc.), but chosen documentation format,\n>>     AsciiDoc, doesn't make it easy...\n> \n> I dare to disagree here. Asciidoc supports generating image tags for\n> respective output formats and it really does not look hard. We could have\n> PNGs and if we wanted higher press quality even SVG or EPS and convert them\n> to PNGs for the HTML version (and use EPS for latex output).\n\nThe problem is that 1) language used to generate images must be easy\nto understand and readable in text form (so sources are enough to\nunderstand); 2) one of the main formats is manpage (although that would\nnot matter for \"Git Guide\" / \"The Git Book\").\n\nShould we choose PIC? Or perhaps DOT? I can write little MetaPost, but\nI don't think that would be good format for git diagrams, even if it \ncan be converted to PDF, SVG and PNG.\n\n-- \nJakub Narebski\nPoland\n"},{"id":"60614","messageId":"87tzneu1tw.fsf@lysator.liu.se","threadId":"10929","inReplyTo":"fhs33j$eg9$1@ger.gmane.org","subject":"Re: Git in a Nutshell guide","fromName":"David Kågedal","fromEmail":"davidk@lysator.liu.se","sentAt":"2007-11-22T08:22:19Z","receivedAt":"2007-11-22T08:22:19Z","isPatch":false,"sender":{"key":"davidk@lysator.liu.se","avatar":"https://avatars.githubusercontent.com/u/60530?v=4"},"body":"Jakub Narebski <jnareb@gmail.com> writes:\n\n> A few comments (from what I checked so far):\n>\n> 1. It is \"man git-checkout\" (or \"git checkout --help\"),\n>    not \"man git checkout\"\n\nOr \"git help checkout\", which is what I usually use (for some reason).\n\n-- \nDavid Kågedal\n"},{"id":"60683","messageId":"1195737303.19260.27.camel@localhost","threadId":"10929","inReplyTo":"fhsc7b$k4g$1@ger.gmane.org","subject":"Re: Git in a Nutshell guide","fromName":"Jonas Juselius","fromEmail":"jonas@iki.fi","sentAt":"2007-11-22T13:15:03Z","receivedAt":"2007-11-22T13:15:03Z","isPatch":false,"sender":{"key":"jonas@iki.fi","avatar":null},"body":"I'm planning to write a section in the \"Nutshell guide\" on rewriting\nhistory and rebasing. I have a question related to rewriting history. As\nusual, I'll assume that the part of the history I'm mucking with has not\nbeen pushed or pulled by anyone. \nSuppose I have been working on some topic branch for a while and been\noverly trigger happy, i.e. I have produced a ridiculous number of\ncommits along the way. At some point when I'm done I want to publish my\nchanges, but doing so would create an insanely obese history full of\nnear nonsense commits. What I want to do is to slim down the commit log\ninto pieces that actually makes sense. What is the preferred (or best,\nmost convenient) way of doing this? The way I have done this previously\nis essentially:\n\n1.  git branch -m mytopic tmp_mytopic  # rename\n2.  git branch mytopci tmp_mytpoic~42  # go back in history\nLoop:\n3.1 git log; git diff; git annotate...\n3.2 git diff tmp_mytopic~42..tmp_mytopic~33 | git-apply\n3.3 git commit -m \"sane commit message\" -a\n4.  git branch -d tmp_mytopic\n\nIf I need to reorder commits I can first use git-rebase -i to get\neverything streamlined. There must be a better way of doing this, right?\n\n.jonas.\n"},{"id":"60688","messageId":"128F468C-B1A2-4671-8804-F462D1D4B9D8@steelskies.com","threadId":"10929","inReplyTo":"1195737303.19260.27.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Jonathan del Strother","fromEmail":"maillist@steelskies.com","sentAt":"2007-11-22T14:19:55Z","receivedAt":"2007-11-22T14:19:55Z","isPatch":false,"sender":{"key":"jon.delstrother@bestbefore.tv","avatar":"https://gravatar.com/avatar/754e21ab701c00e2d21fc261187254c34b2a1c0b959d9ee5be1a295990be3081?d=mp&s=160"},"body":"On 22 Nov 2007, at 13:15, Jonas Juselius wrote:\n\n> I'm planning to write a section in the \"Nutshell guide\" on rewriting\n> history and rebasing. I have a question related to rewriting  \n> history. As\n> usual, I'll assume that the part of the history I'm mucking with has  \n> not\n> been pushed or pulled by anyone.\n> Suppose I have been working on some topic branch for a while and been\n> overly trigger happy, i.e. I have produced a ridiculous number of\n> commits along the way. At some point when I'm done I want to publish  \n> my\n> changes, but doing so would create an insanely obese history full of\n> near nonsense commits. What I want to do is to slim down the commit  \n> log\n> into pieces that actually makes sense. What is the preferred (or best,\n> most convenient) way of doing this? The way I have done this  \n> previously\n> is essentially:\n>\n> 1.  git branch -m mytopic tmp_mytopic  # rename\n> 2.  git branch mytopci tmp_mytpoic~42  # go back in history\n> Loop:\n> 3.1 git log; git diff; git annotate...\n> 3.2 git diff tmp_mytopic~42..tmp_mytopic~33 | git-apply\n> 3.3 git commit -m \"sane commit message\" -a\n> 4.  git branch -d tmp_mytopic\n>\n> If I need to reorder commits I can first use git-rebase -i to get\n> everything streamlined. There must be a better way of doing this,  \n> right?\n\n\nI may be missing something here, but you know that you can edit  \ncommits and squash commits together (using something like \"git rebase  \n--interactive mytopic~42\"), right?\n"},{"id":"60689","messageId":"Pine.LNX.4.64.0711221522540.4725@wbgn129.biozentrum.uni-wuerzburg.de","threadId":"10929","inReplyTo":"1195737303.19260.27.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-22T14:24:23Z","receivedAt":"2007-11-22T14:24:23Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 22 Nov 2007, Jonas Juselius wrote:\n\n> Suppose I have been working on some topic branch for a while and been \n> overly trigger happy, i.e. I have produced a ridiculous number of \n> commits along the way. At some point when I'm done I want to publish my \n> changes, but doing so would create an insanely obese history full of \n> near nonsense commits. What I want to do is to slim down the commit log \n> into pieces that actually makes sense. What is the preferred (or best, \n> most convenient) way of doing this? The way I have done this previously \n> is essentially:\n> \n> 1.  git branch -m mytopic tmp_mytopic  # rename\n> 2.  git branch mytopci tmp_mytpoic~42  # go back in history\n> Loop:\n> 3.1 git log; git diff; git annotate...\n> 3.2 git diff tmp_mytopic~42..tmp_mytopic~33 | git-apply\n> 3.3 git commit -m \"sane commit message\" -a\n> 4.  git branch -d tmp_mytopic\n> \n> If I need to reorder commits I can first use git-rebase -i to get\n> everything streamlined. There must be a better way of doing this, right?\n\nYes, you can squash commits into previous commits with rebase -i.  Just \nreplace the second \"pick\" command (and if you want to squash more than \ntwo, the later commands, too) with \"squash\".\n\nHth,\nDscho\n"},{"id":"60694","messageId":"60224.194.138.12.144.1195749434.squirrel@artax.karlin.mff.cuni.cz","threadId":"10929","inReplyTo":"200711212232.33791.jnareb@gmail.com","subject":"Re: Git in a Nutshell guide","fromName":"","fromEmail":"jhud7196@artax.karlin.mff.cuni.cz","sentAt":"2007-11-22T16:37:14Z","receivedAt":"2007-11-22T16:37:14Z","isPatch":false,"sender":{"key":"jhud7196@artax.karlin.mff.cuni.cz","avatar":null},"body":"> Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:\n>> On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:\n>\n>>>  2. Git has some historical cruft, including the fact that it began as\n>>>     series of low level tools (plumbing) and became proper SCM\n>>> (acquired\n>>>     proper porcelain) later, what can be even now seen in\n>>> documentation...\n>\n> What I meant here that some of important documentation can be only\n> found in plumbing commands man pages.\n\nYes, that's true. And does indeed make /writing/ the book harder, because\nthe information is harder to compile. Fortunately it should not make it\nso much harder to read.\n\n>>>  3. Explanation of some features (like object model) would be much\n>>> easier\n>>>     with some graphics (diagrams etc.), but chosen documentation\n>>> format,\n>>>     AsciiDoc, doesn't make it easy...\n>>\n>> I dare to disagree here. Asciidoc supports generating image tags for\n>> respective output formats and it really does not look hard. We could\n>> have\n>> PNGs and if we wanted higher press quality even SVG or EPS and convert\n>> them\n>> to PNGs for the HTML version (and use EPS for latex output).\n>\n> The problem is that 1) language used to generate images must be easy\n> to understand and readable in text form (so sources are enough to\n> understand); 2) one of the main formats is manpage (although that would\n> not matter for \"Git Guide\" / \"The Git Book\").\n\nAd 1), I don't think we have to generate the images. For most images\nit is easier to just draw them in a vector image editor.\n\nAs you say, 2) does not matter for \"Git Guide\"/\"The Git Book\". The man\npages will have to do without graphics or with Ascii-art replacements.\n\n> Should we choose PIC? Or perhaps DOT? I can write little MetaPost, but\n> I don't think that would be good format for git diagrams, even if it\n> can be converted to PDF, SVG and PNG.\n\nI'd use DOT for things that can be done with it (ie. visualizing\nhistories) and just hand-draw the rest in SVG (prefered) or PNG\n(for illustrations).\n\n--\n                                               Jan Hudec <bulb@ucw.cz>\n"},{"id":"60695","messageId":"47297.194.138.12.144.1195750630.squirrel@artax.karlin.mff.cuni.cz","threadId":"10929","inReplyTo":"1195737303.19260.27.camel@localhost","subject":"Re: Git in a Nutshell guide","fromName":"","fromEmail":"jhud7196@artax.karlin.mff.cuni.cz","sentAt":"2007-11-22T16:57:10Z","receivedAt":"2007-11-22T16:57:10Z","isPatch":false,"sender":{"key":"jhud7196@artax.karlin.mff.cuni.cz","avatar":null},"body":"> I'm planning to write a section in the \"Nutshell guide\" on rewriting\n> history and rebasing. I have a question related to rewriting history. As\n> usual, I'll assume that the part of the history I'm mucking with has not\n> been pushed or pulled by anyone.\n> Suppose I have been working on some topic branch for a while and been\n> overly trigger happy, i.e. I have produced a ridiculous number of\n> commits along the way. At some point when I'm done I want to publish my\n> changes, but doing so would create an insanely obese history full of\n> near nonsense commits. What I want to do is to slim down the commit log\n> into pieces that actually makes sense. What is the preferred (or best,\n> most convenient) way of doing this? The way I have done this previously\n> is essentially:\n>\n> 1.  git branch -m mytopic tmp_mytopic  # rename\n> 2.  git branch mytopci tmp_mytpoic~42  # go back in history\n> Loop:\n> 3.1 git log; git diff; git annotate...\n> 3.2 git diff tmp_mytopic~42..tmp_mytopic~33 | git-apply\n> 3.3 git commit -m \"sane commit message\" -a\n> 4.  git branch -d tmp_mytopic\n>\n> If I need to reorder commits I can first use git-rebase -i to get\n> everything streamlined. There must be a better way of doing this, right?\n\nIIRC rebase -i is also capable of merging the commits. So you can use it\nfor the whole thing.\n\n--\n                                              Jan Hudec <bulb@ucw.cz>\n"},{"id":"60744","messageId":"200711231028.29010.jnareb@gmail.com","threadId":"10929","inReplyTo":"87tzneu1tw.fsf@lysator.liu.se","subject":"Re: Git in a Nutshell guide","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-11-23T09:28:28Z","receivedAt":"2007-11-23T09:28:28Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, 22 Nov 2007, David Kågedal wrote:\n> Jakub Narebski <jnareb@gmail.com> writes:\n> \n>> A few comments (from what I checked so far):\n>>\n>> 1. It is \"man git-checkout\" (or \"git checkout --help\"),\n>>    not \"man git checkout\"\n> \n> Or \"git help checkout\", which is what I usually use (for some reason).\n\nOr, at least for now \"git checkout --help\", which requires only\nadding \"--help\" at the end. At least for now because some commands\nreturn short summary for \"--help\" and I think it is considered\nthat it should be done that way for all porcelain commands.\n\n-- \nJakub Narebski\nPoland\n"}]}