{"thread":{"id":"9311","subject":"[PATCH] user-manual: mention git gui citool (commit, amend)","startedAt":"2007-07-30T16:11:20Z","lastAt":"2007-08-06T19:43:27Z","messageCount":34,"participants":["Steffen Prohaska","Shawn O. Pearce","J. Bruce Fields","Junio C Hamano","David Kastrup","Johannes Schindelin","Steven Grimm","Robin Rosenberg"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"49106","messageId":"11858118802945-git-send-email-prohaska@zib.de","threadId":"9311","inReplyTo":null,"subject":"[PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-07-30T16:11:20Z","receivedAt":"2007-07-30T16:11:20Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"git gui is especially useful because it allows to select diff hunks.\nNow it is at least mentioned in the user-manual.\n\nSigned-off-by: Steffen Prohaska \n---\n Documentation/user-manual.txt | 21 ++++++++++++++++++++-\n 1 files changed, 20 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 0071cd0..de4ec0b 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1079,6 +1079,24 @@ $ git diff HEAD\t # difference between HEAD and working tree; what\n $ git status\t # a brief per-file summary of the above.\n -------------------------------------------------\n \n+Another approach for creating commits is git gui:\n+\n+-------------------------------------------------\n+$ git gui citool\n+-------------------------------------------------\n+\n+starts the commit tool (Note, \"`git gui`\" starts the full gui, which\n+provides more options).\n+\n+Beyond the basic operation of staging and unstaging complete files,\n+git gui can also selectively stage diff hunks. You can do so by\n+selecting a modified or staged file and right-click on the diff view\n+in the lower part of the gui. A pop-up will appear that lets you\n+select a specific hunk and stage or unstage it for the next commit.\n+This is particular useful for slicing large, ugly commits into smaller\n+pieces, for example when cherry-picking (see\n+<>).\n+\n [[creating-good-commit-messages]]\n Creating good commit messages\n -----------------------------\n@@ -2480,7 +2498,8 @@ $ gitk origin..mywork &\n And browse through the list of patches in the mywork branch using gitk,\n applying them (possibly in a different order) to mywork-new using\n cherry-pick, and possibly modifying them as you go using commit\n---amend.\n+--amend. git gui may be especially useful to amend commits as it\n+lets you selectively stage and unstage single diff hunks.\n \n Another technique is to use git-format-patch to create a series of\n patches, then reset the state to before the patches:\n-- \n1.5.3.rc3.122.g4978\n"},{"id":"49167","messageId":"20070731002448.GV20052@spearce.org","threadId":"9311","inReplyTo":"11858118802945-git-send-email-prohaska@zib.de","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-07-31T00:24:48Z","receivedAt":"2007-07-31T00:24:48Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"Steffen Prohaska wrote:\n> git gui is especially useful because it allows to select diff hunks.\n> Now it is at least mentioned in the user-manual.\n \n> +Another approach for creating commits is git gui:\n> +\n> +-------------------------------------------------\n> +$ git gui citool\n> +-------------------------------------------------\n\nActually `git citool` is an alias for `git gui citool`. Because the\nformer is much faster to type when you want to make a quick commit.\n:-)\n\n> +\n> +starts the commit tool (Note, \"`git gui`\" starts the full gui, which\n> +provides more options).\n\nBut this note is also really useful. So maybe talking about the\nlonger form in the user manual is a good way to introduce git-gui.\n\n> +Beyond the basic operation of staging and unstaging complete files,\n> +git gui can also selectively stage diff hunks. You can do so by\n> +selecting a modified or staged file and right-click on the diff view\n> +in the lower part of the gui. A pop-up will appear that lets you\n> +select a specific hunk and stage or unstage it for the next commit.\n> +This is particular useful for slicing large, ugly commits into smaller\n> +pieces, for example when cherry-picking (see\n> +<>).\n\nYes. Now if only someone would teach it how to let you highlight a\nsection and stage/unstage just the selection. Never mind splitting\na hunk. Selection based stage/unstage would really be cool...\nespecially when combined with git-stash. Where you could first\nstash everything, reset back to the last committed state, then\nselectively unstash changes into the working directory, test them,\nstage everything for commit, then unstash more, etc...\n\nSince git-stash is modeled as a commit, it could also work for\ncherry-picking. Which is very useful when cleaning up a series.\nHmm. Wishlist for git-gui!\n\n> @@ -2480,7 +2498,8 @@ $ gitk origin..mywork &\n> And browse through the list of patches in the mywork branch using gitk,\n> applying them (possibly in a different order) to mywork-new using\n> cherry-pick, and possibly modifying them as you go using commit\n> ---amend.\n> +--amend. git gui may be especially useful to amend commits as it\n> +lets you selectively stage and unstage single diff hunks.\n\nYes. Except git-gui (currently) destroys the author information\nwhen it does an amend. Bad git-gui! Bad! No prize for you! :-)\n\n-- \nShawn.\n"},{"id":"49454","messageId":"20070802181853.GB31885@fieldses.org","threadId":"9311","inReplyTo":"11858118802945-git-send-email-prohaska@zib.de","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-02T18:18:53Z","receivedAt":"2007-08-02T18:18:53Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Jul 30, 2007 at 06:11:20PM +0200, Steffen Prohaska wrote:\n> git gui is especially useful because it allows to select diff hunks.\n> Now it is at least mentioned in the user-manual.\n\nHm, OK. I think the user manual's only departures from the commandline\nright now are a few mentions of gitk (which don't actually explain how\nto use it; I assume that's self-explanatory).\n\nBut this seems interesting enough to be worth a mention, thanks.\n\n> +Another approach for creating commits is git gui:\n> +\n> +-------------------------------------------------\n> +$ git gui citool\n> +-------------------------------------------------\n> +\n> +starts the commit tool (Note, \"`git gui`\" starts the full gui, which\n> +provides more options).\n> +\n> +Beyond the basic operation of staging and unstaging complete files,\n> +git gui can also selectively stage diff hunks. You can do so by\n> +selecting a modified or staged file and right-click on the diff view\n> +in the lower part of the gui. A pop-up will appear that lets you\n> +select a specific hunk and stage or unstage it for the next commit.\n> +This is particular useful for slicing large, ugly commits into smaller\n> +pieces, for example when cherry-picking (see\n> +<>).\n\nI wonder whether we could get away with just the brief list of features\n(\"lets you view changes in the index and the working file, lets you\nindividually select diff hunks for inclusion in the index\"), and leave\nthe how-to stuff to online guit-gui help, if it's necessary?\n\nAlso, I like the verb \"stage\" as a way to explain the part of the index\nfile in creating commits, but I've been consistently using the word\n\"index\" throughout the user manual, and I think that's consistent with\nthe rest of the documentation--so don't avoid it here.\n\n--b.\n"},{"id":"49503","messageId":"107BD473-E055-47D0-9720-9D878BDAB954@zib.de","threadId":"9311","inReplyTo":"20070802181853.GB31885@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-02T22:24:10Z","receivedAt":"2007-08-02T22:24:10Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 2, 2007, at 8:18 PM, J. Bruce Fields wrote:\n\n> On Mon, Jul 30, 2007 at 06:11:20PM +0200, Steffen Prohaska wrote:\n\n>> +Another approach for creating commits is git gui:\n>> +\n>> +-------------------------------------------------\n>> +$ git gui citool\n>> +-------------------------------------------------\n>> +\n>> +starts the commit tool (Note, \"`git gui`\" starts the full gui, which\n>> +provides more options).\n>> +\n>> +Beyond the basic operation of staging and unstaging complete files,\n>> +git gui can also selectively stage diff hunks. You can do so by\n>> +selecting a modified or staged file and right-click on the diff view\n>> +in the lower part of the gui. A pop-up will appear that lets you\n>> +select a specific hunk and stage or unstage it for the next commit.\n>> +This is particular useful for slicing large, ugly commits into \n>> smaller\n>> +pieces, for example when cherry-picking (see\n>> +<>).\n>\n> I wonder whether we could get away with just the brief list of \n> features\n> (\"lets you view changes in the index and the working file, lets you\n> individually select diff hunks for inclusion in the index\"), and leave\n> the how-to stuff to online guit-gui help, if it's necessary?\n\nMaybe, this would be sufficient. I mentioned the pop-up explicitly\nbecause it wasn't obvious to me right away. The reason might be that\nmy brain adjusted too much to the Mac I'm using. Right-clicking and\npop-ups are rarely used on Macs as the only access point to essential\nfeatures, such as selectively staging diff hunks. Typically an icon\nor menu entry guides you explicitly to every feature. Pop-ups are only\nused for 'optimized' access but never as the only access point.\n\n\n> Also, I like the verb \"stage\" as a way to explain the part of the \n> index\n> file in creating commits, but I've been consistently using the word\n> \"index\" throughout the user manual, and I think that's consistent with\n> the rest of the documentation--so don't avoid it here.\n\n\"staging/unstaging\" is how git gui calls adding/removing files to and\nfrom the index.\n\n\tSteffen\n"},{"id":"49504","messageId":"20070802223132.GA15212@fieldses.org","threadId":"9311","inReplyTo":"107BD473-E055-47D0-9720-9D878BDAB954@zib.de","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-02T22:31:32Z","receivedAt":"2007-08-02T22:31:32Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Aug 03, 2007 at 12:24:10AM +0200, Steffen Prohaska wrote:\n>\n> On Aug 2, 2007, at 8:18 PM, J. Bruce Fields wrote:\n>\n>> I wonder whether we could get away with just the brief list of features\n>> (\"lets you view changes in the index and the working file, lets you\n>> individually select diff hunks for inclusion in the index\"), and leave\n>> the how-to stuff to online guit-gui help, if it's necessary?\n>\n> Maybe, this would be sufficient. I mentioned the pop-up explicitly\n> because it wasn't obvious to me right away.\n\nI took a quick look and it wasn't obvious to me either. It'd be nice if\nthis could be fixed in the interface or the documentation in git-gui\nitself instead of here, but perhaps saying it here is easiest for now.\n\n>> Also, I like the verb \"stage\" as a way to explain the part of the index\n>> file in creating commits, but I've been consistently using the word\n>> \"index\" throughout the user manual, and I think that's consistent with\n>> the rest of the documentation--so don't avoid it here.\n>\n> \"staging/unstaging\" is how git gui calls adding/removing files to and\n> from the index.\n\nI understand what you meant, but a reader of the user manual at this\npoint might not, since it's been consistently saying things like \"to add\nthe contents of a new file to the index, use git add\". So we should use\nthe same language here. Unless we want to update the whole thing to use\n\"stage\" and \"unstage\". I'd rather not.\n\n--b.\n"},{"id":"49524","messageId":"7vodhpscrz.fsf@assigned-by-dhcp.cox.net","threadId":"9311","inReplyTo":"20070802181853.GB31885@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-03T00:05:36Z","receivedAt":"2007-08-03T00:05:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"J. Bruce Fields\" writes:\n\n> I wonder whether we could get away with just the brief list of features\n> (\"lets you view changes in the index and the working file, lets you\n> individually select diff hunks for inclusion in the index\"), and leave\n> the how-to stuff to online guit-gui help, if it's necessary?\n\nLet's do that.\n\n> Also, I like the verb \"stage\" as a way to explain the part of the index\n> file in creating commits, but I've been consistently using the word\n> \"index\" throughout the user manual, and I think that's consistent with\n> the rest of the documentation--so don't avoid it here.\n\nI tend to agree. The verb \"to stage\" is really just a way to\nsay \"the act of adding contents to the index\" and explain what\nit implies (i.e. \"prepare it to be included in the next commit\").\nSaying \"you can _think_ of the index as a staging area\" is fine,\nbut the official name of that thing is \"the index\", and I do not\nthink avoiding that term adds clarity to the documentation.\n"},{"id":"49534","messageId":"20070803030101.GI20052@spearce.org","threadId":"9311","inReplyTo":"107BD473-E055-47D0-9720-9D878BDAB954@zib.de","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-08-03T03:01:01Z","receivedAt":"2007-08-03T03:01:01Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"Steffen Prohaska wrote:\n> Maybe, this would be sufficient. I mentioned the pop-up explicitly\n> because it wasn't obvious to me right away. The reason might be that\n> my brain adjusted too much to the Mac I'm using. Right-clicking and\n> pop-ups are rarely used on Macs as the only access point to essential\n> features, such as selectively staging diff hunks. Typically an icon\n> or menu entry guides you explicitly to every feature. Pop-ups are only\n> used for 'optimized' access but never as the only access point.\n\nSteffen, you seem to be more in-tune with the Mac UI standards\nthan I am. Any suggestions on what I can do in git-gui to make\nthis feature more obvious to users?\n\nI myself use a Mac OS X based PowerBook as my primary development\nsystem, but I have to admit, I'm not the best GUI developer that has\never walked on this planet. Far far far from it. I get by, if that.\nThe fact that git-gui is even usable by mortals is a minor miracle.\n\nSo I'd really love to do better. But frankly I'm at a loss here\nand just don't know what sort of change to make.\n\n\nSide note: Someone recently asked me how to move individual files\nto the left side of the UI (to stage them). Apparently this person\nhad been using git-gui for months by just clicking \"Add Existing\"\n(recently renamed to \"Stage Changed\"). It never occurred to the\nuser to try clicking the file's individual icons. Or to select\nthe files they were interested in and look for a menu option that\nmight work on that selection.\n\n-- \nShawn.\n"},{"id":"49535","messageId":"20070803030459.GJ20052@spearce.org","threadId":"9311","inReplyTo":"20070802181853.GB31885@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-08-03T03:04:59Z","receivedAt":"2007-08-03T03:04:59Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"\"J. Bruce Fields\" wrote:\n> > +Beyond the basic operation of staging and unstaging complete files,\n> > +git gui can also selectively stage diff hunks. You can do so by\n...\n> \n> I wonder whether we could get away with just the brief list of features\n> (\"lets you view changes in the index and the working file, lets you\n> individually select diff hunks for inclusion in the index\"), and leave\n> the how-to stuff to online guit-gui help, if it's necessary?\n\nOnline help? In git-gui? :-)\n\nWe don't have an online help system yet. Basically no documentation\nhas been written for git-gui. No thought has been put into how one\nshould be organized, maintained, or displayed to the poor human\nwho is just trying to learn more about Git and this gui thing it\ncame with.\n\nYes, Help->Online Documentation is abvailable to most users, but\nthat just opens your web browser (if it can find one) and points\nit to kernel.org's git manual. Not exactly the best material for\nlearning more about git-gui itself.\n\n-- \nShawn.\n"},{"id":"49539","messageId":"B14C42A6-F4BD-40D7-AEAF-66FFF492AB9B@zib.de","threadId":"9311","inReplyTo":"20070802223132.GA15212@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-03T05:08:44Z","receivedAt":"2007-08-03T05:08:44Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 3, 2007, at 12:31 AM, J. Bruce Fields wrote:\n\n>>> Also, I like the verb \"stage\" as a way to explain the part of the \n>>> index\n>>> file in creating commits, but I've been consistently using the word\n>>> \"index\" throughout the user manual, and I think that's consistent \n>>> with\n>>> the rest of the documentation--so don't avoid it here.\n>>\n>> \"staging/unstaging\" is how git gui calls adding/removing files to and\n>> from the index.\n>\n> I understand what you meant, but a reader of the user manual at this\n> point might not, since it's been consistently saying things like \n> \"to add\n> the contents of a new file to the index, use git add\". So we \n> should use\n> the same language here. Unless we want to update the whole thing \n> to use\n> \"stage\" and \"unstage\". I'd rather not.\n\nAgree. But we could briefly introduce git gui's dialect, something like\n\n\"git gui lets you select files (use menu 'Commit > Stage to Commit') or\nindividually diff hunks (use 'Stage Hunk For Commit' in context menu of\ndiff view) for inclusion in the index.\"\n\n\tSteffen\n"},{"id":"49589","messageId":"20070803125601.GA28323@fieldses.org","threadId":"9311","inReplyTo":"20070803030101.GI20052@spearce.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-03T12:56:01Z","receivedAt":"2007-08-03T12:56:01Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:\n> Steffen, you seem to be more in-tune with the Mac UI standards\n> than I am. Any suggestions on what I can do in git-gui to make\n> this feature more obvious to users?\n> \n> I myself use a Mac OS X based PowerBook as my primary development\n> system, but I have to admit, I'm not the best GUI developer that has\n> ever walked on this planet. Far far far from it.\n\nYou're way ahead of me!\n\n> So I'd really love to do better. But frankly I'm at a loss here\n> and just don't know what sort of change to make.\n\nThe one thing that struck me when I fired up git-gui was that it wasn't\nobvious to me which things I should try clicking on.\n\nFor example: the buttons, drop-down menus, and check-boxes all cry out\nto be played with. But the filenames in the lists at the top are less\nobvious, and it might never have occurred to me on my own to right-click\non the diff hunks at the bottom. That just looks like passive colorized\ntext to me.\n\nI don't know what sort of user-interface conventions say \"play with\nme!\", though. Random ideas:\n\n\t- maybe the cursor should change shape over the diff hunks (or\n\t just the headers?)\n\t- maybe buttons, hunk headers, file names, etc., should all be\n\t in the same color?\n\t- maybe the hunk headers could benefit from a little more\n\t decoration? I don't know how to do that without just making\n\t the display look more cluttered, though.\n\t- maybe left-clicking on diff hunks should do something too?\n\nI dunno.\n\n--b.\n"},{"id":"49590","messageId":"20070803125634.GB28323@fieldses.org","threadId":"9311","inReplyTo":"B14C42A6-F4BD-40D7-AEAF-66FFF492AB9B@zib.de","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-03T12:56:34Z","receivedAt":"2007-08-03T12:56:34Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Aug 03, 2007 at 07:08:44AM +0200, Steffen Prohaska wrote:\n>\n> On Aug 3, 2007, at 12:31 AM, J. Bruce Fields wrote:\n>\n>>>> Also, I like the verb \"stage\" as a way to explain the part of the index\n>>>> file in creating commits, but I've been consistently using the word\n>>>> \"index\" throughout the user manual, and I think that's consistent with\n>>>> the rest of the documentation--so don't avoid it here.\n>>>\n>>> \"staging/unstaging\" is how git gui calls adding/removing files to and\n>>> from the index.\n>>\n>> I understand what you meant, but a reader of the user manual at this\n>> point might not, since it's been consistently saying things like \"to add\n>> the contents of a new file to the index, use git add\". So we should use\n>> the same language here. Unless we want to update the whole thing to use\n>> \"stage\" and \"unstage\". I'd rather not.\n>\n> Agree. But we could briefly introduce git gui's dialect, something like\n>\n> \"git gui lets you select files (use menu 'Commit > Stage to Commit') or\n> individually diff hunks (use 'Stage Hunk For Commit' in context menu of\n> diff view) for inclusion in the index.\"\n\nSounds good to me. Somebody do that!\n\n--b.\n"},{"id":"49591","messageId":"20070803125846.GC28323@fieldses.org","threadId":"9311","inReplyTo":"20070803030459.GJ20052@spearce.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-03T12:58:47Z","receivedAt":"2007-08-03T12:58:47Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Thu, Aug 02, 2007 at 11:04:59PM -0400, Shawn O. Pearce wrote:\n> Online help? In git-gui? :-)\n> \n> We don't have an online help system yet. Basically no documentation\n> has been written for git-gui. No thought has been put into how one\n> should be organized, maintained, or displayed to the poor human\n> who is just trying to learn more about Git and this gui thing it\n> came with.\n> \n> Yes, Help->Online Documentation is abvailable to most users, but\n> that just opens your web browser (if it can find one) and points\n> it to kernel.org's git manual. Not exactly the best material for\n> learning more about git-gui itself.\n\nFair enough.\n\nThough I'd like to keep the main body of the manual focused on the major\ncommand line tools, I'd have no objection to a separate chapter (or\nappendix?) devoted to git-gui; then you could point directly at that.\nWould that make sense?\n\n--b.\n"},{"id":"49671","messageId":"20070804062010.GQ20052@spearce.org","threadId":"9311","inReplyTo":"20070803125846.GC28323@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-08-04T06:20:10Z","receivedAt":"2007-08-04T06:20:10Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"\"J. Bruce Fields\" wrote:\n> On Thu, Aug 02, 2007 at 11:04:59PM -0400, Shawn O. Pearce wrote:\n> > Online help? In git-gui? :-)\n> > \n> > We don't have an online help system yet.\n> \n> Fair enough.\n> \n> Though I'd like to keep the main body of the manual focused on the major\n> command line tools, I'd have no objection to a separate chapter (or\n> appendix?) devoted to git-gui; then you could point directly at that.\n> Would that make sense?\n\nYea, that makes a lot of sense. git-gui isn't a full replacement\nfor the command line anyway, so I would never suggest a wholesale\nrewrite of the user manual to slant the entire thing towards git-gui.\nDoing so would only point out the many shortcomings in git-gui. :)\n\nI haven't explored any in-Tk rendering options yet, been too busy\nwith other projects. Ideally I'd like to just render the asciidoc\nmarkup directly, but I don't think anyone has done an asciidoc\nviewer for Tk. I can't imagine it would be that difficult to get\nsome sort of parser working though...\n\n\nBut at this point in git (and git-gui's) life I think it would\nbe very worthwhile to devote an entire (new) chapter to git-gui,\nmaybe as part of git 1.5.4/git-gui 0.9.0. I think we're far too\nlate in the 1.5.3 cycle to do it now. I personally won't have the\ntime to even try to rough draft something anytime soon, let alone\nlet others copy-edit me before Juino releases 1.5.3. :)\n\nBeing bundled with core git has brought git-gui a sizeable and\ngrowing userbase, and more and more users are discovering it\neach day. We're now seeing it be translated into many different\nlanguages, and it is a somewhat core part of the MSYS port as many\nWindows users prefer to click in GUIs over type in cmd.exe terminal\nwindows (can't say I blame them, cmd.exe is aweful!).\n\nIn other words I think git-gui should get roughly as much attention\nfrom the user manual as git-add/rm/mv/commit/checkout/branch get,\nas it offers the same feature set. But it shouldn't distract from\nthe command line part of the manual.\n\nMaybe we should write parts of the manual in a \"choose your own\nadventure style\" and use different chapters for different paths.\nI think users can easily decide between the command line \"i like to\ntype\" vs. the gui \"i like to click\" paths and focus their attention\nto the material they are most interested in. :-)\n\n-- \nShawn.\n"},{"id":"49672","messageId":"20070804063353.GR20052@spearce.org","threadId":"9311","inReplyTo":"20070803125601.GA28323@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-08-04T06:33:53Z","receivedAt":"2007-08-04T06:33:53Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"\"J. Bruce Fields\" wrote:\n> On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:\n> > So I'd really love to do better. But frankly I'm at a loss here\n> > and just don't know what sort of change to make.\n> \n> The one thing that struck me when I fired up git-gui was that it wasn't\n> obvious to me which things I should try clicking on.\n\nYea, that I have noticed with other newbies. I have recently had\nthe chance to observe a few new users work with git-gui for the\nfirst time and I have noticed that they just don't quite know what\nto poke at and experiment with. Unlike with many other applications\nwhere its more obvious what's there for the poking...\n \n> For example: the buttons, drop-down menus, and check-boxes all cry out\n> to be played with. But the filenames in the lists at the top are less\n> obvious, and it might never have occurred to me on my own to right-click\n> on the diff hunks at the bottom. That just looks like passive colorized\n> text to me.\n\nIt doesn't just look like colored text to me anymore. Which is a\nhuge problem for me as an interface designer. I know what's there.\n\nBTW, the reason why there's a context menu in the diff viewer?\nI right clicked in there one day and nothing happened. The fact\nthat nothing happen surprised the hell out of me. Even though I\nhad written all of that code myself. So I went off and added\nthat context menu.\n\nLater I realized I wanted to just stage that hunk. I could click\non it all I want, but the $@!*@(!@* computer didn't do what I really\nwanted it to. So stage hunk was born and added to the context menu.\n\nThat experience is actually true of much of the git-gui UI. Things\nhappen there only because I've actually tried to do something,\nonly to shock myself when I find out it doesn't work! I promptly\nwrite the patch and contribute it. :)\n \n> I don't know what sort of user-interface conventions say \"play with\n> me!\", though. Random ideas:\n> \n> \t- maybe the cursor should change shape over the diff hunks (or\n> \t just the headers?)\n\nThat's actually a pretty cool idea. I might play with it just to\nsee how I feel about the cursor changing and if it gives me any\nideas about what might happen under it. Though as I write this\nemail I'm thinking that if the cursor changed shape when it was\nover the diff hunk header I'd try to left-click the hunk header to\nget a reaction from the computer.\n\n> \t- maybe buttons, hunk headers, file names, etc., should all be\n> \t in the same color?\n> \t- maybe the hunk headers could benefit from a little more\n> \t decoration? I don't know how to do that without just making\n> \t the display look more cluttered, though.\n> \t- maybe left-clicking on diff hunks should do something too?\n\nI just had a thought of putting an actual button icon in the first\ncolumn of the hunk header lines. If it looks enough like a button\nicon thingy, users might just click on it. And when they do we\ncan present that diff pane context menu, and look, they can stage\ntheir hunks! ;-)\n\nJust a thought. Utterly random too. Musta been that alpha particle\nslamming into a neuron.\n\nThanks for the ideas. Its certainly given me some things to\nexperiment with in the next week or so when I can find the time.\n\n-- \nShawn.\n"},{"id":"49684","messageId":"85odhniw11.fsf@lola.goethe.zz","threadId":"9311","inReplyTo":"20070804062010.GQ20052@spearce.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T07:44:26Z","receivedAt":"2007-08-04T07:44:26Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"\"Shawn O. Pearce\" writes:\n\n> I haven't explored any in-Tk rendering options yet, been too busy\n> with other projects. Ideally I'd like to just render the asciidoc\n> markup directly, but I don't think anyone has done an asciidoc\n> viewer for Tk. I can't imagine it would be that difficult to get\n> some sort of parser working though...\n\nWith regard to my Texinfo proposal in a different thread, it must be\nmentioned that \"tkinfo\" can be used as an embedded info viewer in\nexisting applications.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49731","messageId":"20070804143559.GC10294@fieldses.org","threadId":"9311","inReplyTo":"20070804062010.GQ20052@spearce.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-04T14:35:59Z","receivedAt":"2007-08-04T14:35:59Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Aug 04, 2007 at 02:20:10AM -0400, Shawn O. Pearce wrote:\n> But at this point in git (and git-gui's) life I think it would\n> be very worthwhile to devote an entire (new) chapter to git-gui,\n> maybe as part of git 1.5.4/git-gui 0.9.0. I think we're far too\n> late in the 1.5.3 cycle to do it now. I personally won't have the\n> time to even try to rough draft something anytime soon, let alone\n> let others copy-edit me before Juino releases 1.5.3. :)\n> \n> Being bundled with core git has brought git-gui a sizeable and\n> growing userbase, and more and more users are discovering it\n> each day. We're now seeing it be translated into many different\n> languages, and it is a somewhat core part of the MSYS port as many\n> Windows users prefer to click in GUIs over type in cmd.exe terminal\n> windows (can't say I blame them, cmd.exe is aweful!).\n> \n> In other words I think git-gui should get roughly as much attention\n> from the user manual as git-add/rm/mv/commit/checkout/branch get,\n> as it offers the same feature set. But it shouldn't distract from\n> the command line part of the manual.\n> \n> Maybe we should write parts of the manual in a \"choose your own\n> adventure style\" and use different chapters for different paths.\n> I think users can easily decide between the command line \"i like to\n> type\" vs. the gui \"i like to click\" paths and focus their attention\n> to the material they are most interested in. :-)\n\nSure.\n\nFor now, though, I think it'd be simplest to start with an entirely\nseparate appendix. And find a way to make links to that chapter are\nprominently featured in Windows ports, as that sounds like an immediate\nneed.\n\nAnd then later as git-gui progresses we can figure out how to integrate\nit better.\n\n--b.\n"},{"id":"49872","messageId":"99870CA9-D204-40C2-9BC5-2353EBE18816@zib.de","threadId":"9311","inReplyTo":"20070803125601.GA28323@fieldses.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-05T12:09:09Z","receivedAt":"2007-08-05T12:09:09Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 3, 2007, at 2:56 PM, J. Bruce Fields wrote:\n\n> On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:\n>> Steffen, you seem to be more in-tune with the Mac UI standards\n>> than I am. Any suggestions on what I can do in git-gui to make\n>> this feature more obvious to users?\n\n From time to time I have a look at the Apple Human Interface\nGuidelines [1]. They contain large Apple specific sections but also\nideas of general interest.\n\n\n>> I myself use a Mac OS X based PowerBook as my primary development\n>> system, but I have to admit, I'm not the best GUI developer that has\n>> ever walked on this planet. Far far far from it.\n>\n> You're way ahead of me!\n>\n>> So I'd really love to do better. But frankly I'm at a loss here\n>> and just don't know what sort of change to make.\n>\n>> Side note: Someone recently asked me how to move individual files\n>> to the left side of the UI (to stage them). Apparently this person\n>> had been using git-gui for months by just clicking \"Add Existing\"\n>> (recently renamed to \"Stage Changed\"). It never occurred to the\n>> user to try clicking the file's individual icons. Or to select\n>> the files they were interested in and look for a menu option that\n>> might work on that selection.\n>\n> The one thing that struck me when I fired up git-gui was that it \n> wasn't\n> obvious to me which things I should try clicking on.\n\nI had the same experience. I didn't recognize that the document\nicon left to a filename is actually a button with an action\nattached to it. I thought it would be there just to distinguish\na file from a directory.\n\nI'd tend to use kind of a push button instead of an icon to\nindicate the action of adding a file to the index (staging).\nMaybe an arrow facing left? And an arrow facing right to\nunstage?\n\n\n> For example: the buttons, drop-down menus, and check-boxes all cry out\n> to be played with. But the filenames in the lists at the top are less\n> obvious, and it might never have occurred to me on my own to right- \n> click\n> on the diff hunks at the bottom. That just looks like passive \n> colorized\n> text to me.\n>\n> I don't know what sort of user-interface conventions say \"play with\n> me!\", though. Random ideas:\n>\n> \t- maybe the cursor should change shape over the diff hunks (or\n> \t just the headers?)\n> \t- maybe buttons, hunk headers, file names, etc., should all be\n> \t in the same color?\n> \t- maybe the hunk headers could benefit from a little more\n> \t decoration? I don't know how to do that without just making\n> \t the display look more cluttered, though.\n> \t- maybe left-clicking on diff hunks should do something too?\n\nIn general it's always a good idea to make every action\naccessible with only a single (left) mouse button. This\nmay seem ridiculous nowadays, but it really help to keep\nthings obvious. Right buttons and context menus have a\nvalue for the experienced user to access things more\nefficiently, but they should not be essential.\n\n\tSteffen\n\n[1] http://developer.apple.com/documentation/UserExperience/ \nConceptual/OSXHIGuidelines/index.html\n"},{"id":"49878","messageId":"D17F92F4-3FF9-46CD-9E55-449C07DE2820@zib.de","threadId":"9311","inReplyTo":"20070804062010.GQ20052@spearce.org","subject":"Re: [PATCH] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-05T12:26:11Z","receivedAt":"2007-08-05T12:26:11Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 4, 2007, at 8:20 AM, Shawn O. Pearce wrote:\n\n>>\n>> Though I'd like to keep the main body of the manual focused on the \n>> major\n>> command line tools, I'd have no objection to a separate chapter (or\n>> appendix?) devoted to git-gui; then you could point directly at that.\n>> Would that make sense?\n>\n> Yea, that makes a lot of sense. git-gui isn't a full replacement\n> for the command line anyway, so I would never suggest a wholesale\n> rewrite of the user manual to slant the entire thing towards git-gui.\n> Doing so would only point out the many shortcomings in git-gui. :)\n\nI partially disagree.\n\nWhen users start to learn git they are mostly interested in how to\nachieve a specific goal, e.g. how to create a commit. I think most\nusers either accept a command line or a gui, whatever is the easiest\nand fastest way to do something.\n\nI strongly believe that the sections in the manual should be organized\nalong the tasks that users want to solve and discuss available \napproaches.\nObviously each chapter should start with simple tasks and simple tools\n(the commandline) and only later add advanced usage scenarios. But I\ndon't think it makes sense to put git gui into a separate chapter.\n\nI personally use the command line for most of my work, but for adding\nsingle diff hunks to the index I use git gui. It's much simple than\n'git add -i'.\n\nIn the chapter on history browsing, the manual pretty early states\n\n\"The best way to see how this works is using the gitk(1) command;\nrunning gitk now on a git repository and looking for merge commits\nwill help understand how the git organizes history.\"\n\nwhich makes absolutely sense to me. If a gui is the best tool to\ndo the job 'understanding history', then there's no reason to first\nrestrict the manual to the command line tools, like 'git log'.\n\n\n\tSteffen\n"},{"id":"49883","messageId":"1186318785677-git-send-email-prohaska@zib.de","threadId":"9311","inReplyTo":"20070803125634.GB28323@fieldses.org","subject":"[PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-05T12:59:45Z","receivedAt":"2007-08-05T12:59:45Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"git gui is especially useful because it allows to select diff hunks.\nNow it is briefly mentioned in the user-manual.\n\nSigned-off-by: Steffen Prohaska \n---\n Documentation/user-manual.txt | 15 +++++++++++++++\n 1 files changed, 15 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 0071cd0..6865d21 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1079,6 +1079,17 @@ $ git diff HEAD\t # difference between HEAD and working tree; what\n $ git status\t # a brief per-file summary of the above.\n -------------------------------------------------\n \n+Another approach for creating commits is git gui:\n+\n+-------------------------------------------------\n+$ git gui citool\n+-------------------------------------------------\n+\n+starts the commit tool, which lets you add files (use menu\n+'Commit > Stage to Commit') or individually diff hunks (use\n+'Stage Hunk For Commit' in the context menu of the diff view)\n+to the index.\n+\n [[creating-good-commit-messages]]\n Creating good commit messages\n -----------------------------\n@@ -2482,6 +2493,10 @@ applying them (possibly in a different order) to mywork-new using\n cherry-pick, and possibly modifying them as you go using commit\n --amend.\n \n+git gui is especially useful to rework commits as it lets you\n+selectively add single diff hunks to the index (use\n+'Stage Hunk For Commit' in the context menu of the diff view).\n+\n Another technique is to use git-format-patch to create a series of\n patches, then reset the state to before the patches:\n \n-- \n1.5.3.rc3.151.g8d6306\n"},{"id":"49892","messageId":"Pine.LNX.4.64.0708051457110.14781@racer.site","threadId":"9311","inReplyTo":"1186318785677-git-send-email-prohaska@zib.de","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-05T13:58:11Z","receivedAt":"2007-08-05T13:58:11Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 5 Aug 2007, Steffen Prohaska wrote:\n\n> git gui is especially useful because it allows to select diff hunks.\n\nYou should give a _big_ _fat_ _red_ warning there.\n\nIf you selectively commit diff hunks, you _never_ tested what you \ncommitted.\n\nThat is the reason we're not advertising git add -i more actively.\n\nCiao,\nDscho\n"},{"id":"49896","messageId":"17AA7EBE-B755-4F26-9C7E-AF6D762811F2@zib.de","threadId":"9311","inReplyTo":"Pine.LNX.4.64.0708051457110.14781@racer.site","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-05T14:17:00Z","receivedAt":"2007-08-05T14:17:00Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:\n\n> Hi,\n>\n> On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n>\n>> git gui is especially useful because it allows to select diff hunks.\n>\n> You should give a _big_ _fat_ _red_ warning there.\n>\n> If you selectively commit diff hunks, you _never_ tested what you\n> committed.\n>\n> That is the reason we're not advertising git add -i more actively.\n\nHmm... If you do 'git cherry-pick' or 'git rebase' you also did\nnot test what you committed. Should we advertise them less\nactively as well?\n\nBut I see your point. Selecting diff hunks tends to be more fine\ngrained than cherry-picking. But this depends on the details of\nwhat you're doing. I don't think a general warning is appropriate.\n\n\tSteffen\n"},{"id":"49899","messageId":"Pine.LNX.4.64.0708051547410.14781@racer.site","threadId":"9311","inReplyTo":"17AA7EBE-B755-4F26-9C7E-AF6D762811F2@zib.de","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-05T14:48:06Z","receivedAt":"2007-08-05T14:48:06Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 5 Aug 2007, Steffen Prohaska wrote:\n\n> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:\n> \n> > Hi,\n> > \n> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n> > \n> > > git gui is especially useful because it allows to select diff hunks.\n> > \n> > You should give a _big_ _fat_ _red_ warning there.\n> > \n> > If you selectively commit diff hunks, you _never_ tested what you\n> > committed.\n> > \n> > That is the reason we're not advertising git add -i more actively.\n> \n> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did\n> not test what you committed. Should we advertise them less\n> actively as well?\n\nBut you have that state in your working tree! Big difference there!\n\nCiao,\nDscho\n"},{"id":"49902","messageId":"85wswa6n1o.fsf@lola.goethe.zz","threadId":"9311","inReplyTo":"17AA7EBE-B755-4F26-9C7E-AF6D762811F2@zib.de","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T15:03:47Z","receivedAt":"2007-08-05T15:03:47Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Steffen Prohaska writes:\n\n> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:\n>\n>> Hi,\n>>\n>> On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n>>\n>>> git gui is especially useful because it allows to select diff hunks.\n>>\n>> You should give a _big_ _fat_ _red_ warning there.\n>>\n>> If you selectively commit diff hunks, you _never_ tested what you\n>> committed.\n>>\n>> That is the reason we're not advertising git add -i more actively.\n>\n> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did\n> not test what you committed. Should we advertise them less\n> actively as well?\n\nSelectively committing diff hunks also means that a subsequent rebase\n-i or git-cherry will have to reconsider the same commit as it has\nonly been incompletely applied.\n\nSo it can mean more work later. Also one would in general have to\nedit the commit message (if it describes everything that has been\ndone).\n\nThere are simply consequences for the workflow if you do things\nright. Whether they are worth a \"big fat red warning\" is one\nquestion, but mentioning them is probably not amiss.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49935","messageId":"5AB64D44-2324-4A98-B010-8D6D6225F116@zib.de","threadId":"9311","inReplyTo":"85wswa6n1o.fsf@lola.goethe.zz","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-05T19:47:57Z","receivedAt":"2007-08-05T19:47:57Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 5, 2007, at 5:03 PM, David Kastrup wrote:\n\n> Steffen Prohaska writes:\n>\n>> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:\n>>\n>>> Hi,\n>>>\n>>> On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n>>>\n>>>> git gui is especially useful because it allows to select diff \n>>>> hunks.\n>>>\n>>> You should give a _big_ _fat_ _red_ warning there.\n>>>\n>>> If you selectively commit diff hunks, you _never_ tested what you\n>>> committed.\n>>>\n>>> That is the reason we're not advertising git add -i more actively.\n>>\n>> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did\n>> not test what you committed. Should we advertise them less\n>> actively as well?\n>\n> Selectively committing diff hunks also means that a subsequent rebase\n> -i or git-cherry will have to reconsider the same commit as it has\n> only been incompletely applied.\n>\n> So it can mean more work later. Also one would in general have to\n> edit the commit message (if it describes everything that has been\n> done).\n>\n> There are simply consequences for the workflow if you do things\n> right. Whether they are worth a \"big fat red warning\" is one\n> question, but mentioning them is probably not amiss.\n\nI found it quite useful to be able to commit diff chunks selectively.\nI started editing diffs as described in [1] but actually it turned\nout to be easier for me to use git gui. I'm speaking unified diff\nprobably less fluently than Linus does.\n\nMy note about using git gui to select diff hunks is added to the\nsection 'Reordering or selecting from a patch series', which is in\nmy opinion the right section.\n\nBut apparently there's some dispute about usefulness of my comment on\ncherry-picking. Maybe a separate section on rewriting changes would\nbe useful, which I do not have the time to start right now.\n\nJunio, maybe you want to take only the first part of my patch?\n\n\tSteffen\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/46733\n"},{"id":"49947","messageId":"20070805222213.GA12168@fieldses.org","threadId":"9311","inReplyTo":"Pine.LNX.4.64.0708051457110.14781@racer.site","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-05T22:22:13Z","receivedAt":"2007-08-05T22:22:13Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:\n> On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n> \n> > git gui is especially useful because it allows to select diff hunks.\n> \n> You should give a _big_ _fat_ _red_ warning there.\n> \n> If you selectively commit diff hunks, you _never_ tested what you \n> committed.\n\nA big warning would be out of place in what is for now just an isolated\nsentence in two different places. But I agree with you that this would\nbe worth mentioning in any eventual full-fledged git-gui tutorial.\n\n--b.\n"},{"id":"49949","messageId":"20070805222527.GB12168@fieldses.org","threadId":"9311","inReplyTo":"20070805222213.GA12168@fieldses.org","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-05T22:25:27Z","receivedAt":"2007-08-05T22:25:27Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Aug 05, 2007 at 06:22:13PM -0400, J. Bruce Fields wrote:\n> On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:\n> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n> > \n> > > git gui is especially useful because it allows to select diff hunks.\n> > \n> > You should give a _big_ _fat_ _red_ warning there.\n> > \n> > If you selectively commit diff hunks, you _never_ tested what you \n> > committed.\n> \n> A big warning would be out of place in what is for now just an isolated\n> sentence in two different places. But I agree with you that this would\n> be worth mentioning in any eventual full-fledged git-gui tutorial.\n\n(Oh, and my own attempt, along with a couple other minor manual updates,\nis in the master branch at\n\n\tgit://linux-nfs.org/~bfields/git.git master\n\nFeel free to take that whenever, if it looks OK, Junio.)\n\n--b.\n"},{"id":"49965","messageId":"Pine.LNX.4.64.0708060119320.14781@racer.site","threadId":"9311","inReplyTo":"5AB64D44-2324-4A98-B010-8D6D6225F116@zib.de","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-06T00:22:11Z","receivedAt":"2007-08-06T00:22:11Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Him\n\nOn Sun, 5 Aug 2007, Steffen Prohaska wrote:\n\n> I found it quite useful to be able to commit diff chunks selectively.\n\nBut how do you make sure that it works as expected? I.e. when you commit \na hunk using, say, variable \"rule_the_world\", and by mistake (happen to me \nall the time, maybe to you, too?) forgot to select the hunk which declares \nthat variable, maybe because it is hidden in a forest of other variables?\n\nI _try_ to test commits by my eyes, by compiling, and by running the \nversion I'll commit. (Okay, sometimes I run the test _after_ committing, \nbut then I test to see if I have to amend something.)\n\nCiao,\nDscho\n"},{"id":"49966","messageId":"Pine.LNX.4.64.0708060124120.14781@racer.site","threadId":"9311","inReplyTo":"20070805222213.GA12168@fieldses.org","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-06T00:26:21Z","receivedAt":"2007-08-06T00:26:21Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 5 Aug 2007, J. Bruce Fields wrote:\n\n> On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:\n> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n> > \n> > > git gui is especially useful because it allows to select diff hunks.\n> > \n> > You should give a _big_ _fat_ _red_ warning there.\n> > \n> > If you selectively commit diff hunks, you _never_ tested what you \n> > committed.\n> \n> A big warning would be out of place in what is for now just an isolated\n> sentence in two different places. But I agree with you that this would\n> be worth mentioning in any eventual full-fledged git-gui tutorial.\n\nUnfortunately, I am really wasted by this weekend's efforts to bring \nmsysgit.git along... could you be so kind as to cut&paste the relevant \nsection in a reply to me, so I do not have to search for myself?\n\nI would not normally ask for such a favour; it is relatively easy to go on \na search with Git, but I do have only 8 hours of sleep in the last 60 \nhours under my saddle...\n\nCiao,\nDscho\n"},{"id":"49976","messageId":"20070806035119.GB30269@fieldses.org","threadId":"9311","inReplyTo":"Pine.LNX.4.64.0708060124120.14781@racer.site","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-06T03:51:19Z","receivedAt":"2007-08-06T03:51:19Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Aug 06, 2007 at 01:26:21AM +0100, Johannes Schindelin wrote:\n> On Sun, 5 Aug 2007, J. Bruce Fields wrote:\n> > A big warning would be out of place in what is for now just an isolated\n> > sentence in two different places. But I agree with you that this would\n> > be worth mentioning in any eventual full-fledged git-gui tutorial.\n> \n> Unfortunately, I am really wasted by this weekend's efforts to bring \n> msysgit.git along... could you be so kind as to cut&paste the relevant \n> section in a reply to me, so I do not have to search for myself?\n\nSure; appended. This isn't that different from Steffen's proposal.\n\n> I would not normally ask for such a favour; it is relatively easy to go on \n> a search with Git, but I do have only 8 hours of sleep in the last 60 \n> hours under my saddle...\n\nHm. On the other hand, maybe we should just be refusing to feed your\naddiction till you get some sleep.\n\nI wanna keep this short for now, so if we really think we shouldn't\nmention of the hunk-selection thing without a warning, I'd rather just\nomit mention of it, and go for something like: \"You can also use\ngitlink:git-gui[1] to create commits and view changes in the index and\nworking tree\", and drop the second hunk. Whatever.\n\n--b.\n\n>From 407c0c87e15b3cf60347f4fc0bcdb4d239de4163 Mon Sep 17 00:00:00 2001\nFrom: J. Bruce Fields \nDate: Sun, 5 Aug 2007 18:12:37 -0400\nSubject: [PATCH] user-manual: mention git-gui\n\nThe git gui project seems to be still in early stages, but at a point\nwhere it's worth mentioning as an alternative way of creating commits.\n\nOne feature of interest is the ability to manipulate individual diff\nhunks. However, people have found that feature not to be easily\ndiscoverable from the user-interface. Pending some ui improvements, a\nparenthetical hint here may help.\n\n(Thanks to Steffen Prohask and Junio Hamano for suggesting the\nlanguage.)\n\nSigned-off-by: J. Bruce Fields \n---\n Documentation/user-manual.txt | 11 +++++++++--\n 1 files changed, 9 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 9efe85c..f89952a 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1079,6 +1079,11 @@ $ git diff HEAD\t # difference between HEAD and working tree; what\n $ git status\t # a brief per-file summary of the above.\n -------------------------------------------------\n \n+You can also use gitlink:git-gui[1] to create commits, view changes in\n+the index and the working tree files, and individually select diff hunks\n+for inclusion in the index (by right-clicking on the diff hunk and\n+choosing \"Stage Hunk For Commit\").\n+\n [[creating-good-commit-messages]]\n Creating good commit messages\n -----------------------------\n@@ -2506,8 +2511,10 @@ $ gitk origin..mywork &\n \n And browse through the list of patches in the mywork branch using gitk,\n applying them (possibly in a different order) to mywork-new using\n-cherry-pick, and possibly modifying them as you go using commit\n---amend.\n+cherry-pick, and possibly modifying them as you go using commit --amend.\n+The git-gui[1] command may also help as it allows you to individually\n+select diff hunks for inclusion in the index (by right-clicking on the\n+diff hunk and choosing \"Stage Hunk for Commit\").\n \n Another technique is to use git-format-patch to create a series of\n patches, then reset the state to before the patches:\n-- \n1.5.3.GIT\n"},{"id":"49985","messageId":"73E0048A-0F57-47AC-933C-55C041ACFD23@zib.de","threadId":"9311","inReplyTo":"Pine.LNX.4.64.0708060119320.14781@racer.site","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Steffen Prohaska","fromEmail":"prohaska@zib.de","sentAt":"2007-08-06T05:20:17Z","receivedAt":"2007-08-06T05:20:17Z","isPatch":true,"sender":{"key":"prohaska@zib.de","avatar":"https://avatars.githubusercontent.com/u/217580?v=4"},"body":"\nOn Aug 6, 2007, at 2:22 AM, Johannes Schindelin wrote:\n\n> On Sun, 5 Aug 2007, Steffen Prohaska wrote:\n>\n>> I found it quite useful to be able to commit diff chunks selectively.\n>\n> But how do you make sure that it works as expected? I.e. when you \n> commit\n> a hunk using, say, variable \"rule_the_world\", and by mistake \n> (happen to me\n> all the time, maybe to you, too?) forgot to select the hunk which \n> declares\n> that variable, maybe because it is hidden in a forest of other \n> variables?\n\nIn various ways, the details depend on what I'm doing. Here are three\nexamples.\n\n1) I push the commit to a faster machine to compile it there and \ncontinue\nworking on the next commit (a complete build of the software package \nthat\nI'm mostly working on takes approximately 30 min on our fastest \nmachines. I\ncan't wait for this before I continue working. Luckily a complete \ncompile is\nrarely needed).\n\n2) I don't care about a single commit. I only care about the result of a\nseries of commits. I need to check on multiple architectures anyway \nand can't\nthoroughly test what I'm doing right now. Regularly gcc and Microsoft\ncompilers disagree on warnings.\n\n3) I push a series of commits to my scratch space and wait one night \nfor the\nautomated builds to complete on all architectures.\n\n> I _try_ to test commits by my eyes, by compiling, and by running the\n> version I'll commit. (Okay, sometimes I run the test _after_ \n> committing,\n> but then I test to see if I have to amend something.)\n\nOption (1) is probably the only solution that fulfills your \nrequirement that\nevery single commit should compile and work. This is a perfect \napproach but\nsometimes take too much time for me.\n\n\tSteffen\n"},{"id":"50000","messageId":"46B6EBAB.4050805@midwinter.com","threadId":"9311","inReplyTo":"Pine.LNX.4.64.0708060119320.14781@racer.site","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2007-08-06T09:36:43Z","receivedAt":"2007-08-06T09:36:43Z","isPatch":true,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"Johannes Schindelin wrote:\n> But how do you make sure that it works as expected? I.e. when you commit \n> a hunk using, say, variable \"rule_the_world\", and by mistake (happen to me \n> all the time, maybe to you, too?) forgot to select the hunk which declares \n> that variable, maybe because it is hidden in a forest of other variables?\n> \n\nFor cases like that, sure, partial commits are dangerous. On the other \nhand, I've sometimes done partial commits for things like correcting \nerroneous comments in code I'm working on, where there is no functional \nchange whatsoever in the hunk I'm committing and where I want to isolate \nthe corrections from the functional changes I *am* working on.\n\nAlso, when I'm working on a topic branch in my local sandbox I like to \ndo lots of work-in-progress commits. I usually do those based on the \ngranularity of my mental model of what I'm working on, and I have no \nexpectation whatsoever that any particular percentage of them represent \nworking code or even code that compiles. Sometimes I do partial commits \nin that situation too: I make a change to some function in a file that \nI'm editing elsewhere, and commit just that hunk with a commit log \nmessage reminding me of why I made the change. Those commits are not \nintended for public consumption; they're just to help me keep track of \nmy own work. Once everything is in a working state, I do a squash merge \nor a bunch of cherry-pick -n invocations to build some revisions to \npublish to the outside world, and *then* I am in \"each commit must \nrepresent a non-broken state\" mode.\n\nThe great thing about git (well, *one* of the great things) is that it \nunifies those two workflows in one system. With, say, svn, the \"lots of \nlittle checkpoints of my work in progress\" part of that is awkward at \nbest, because it's very much oriented around an \"if the version control \nsystem knows about a change, it is by definition published to the \noutside world\" model.\n\nSo I guess my point, after all that, is just that assumptions that are \nvalid in the context of one workflow are not necessarily as valid in \nothers, and that even in a particular context, not all changes are \ncreated equal.\n\n-Steve\n"},{"id":"50012","messageId":"Pine.LNX.4.64.0708061250330.14781@racer.site","threadId":"9311","inReplyTo":"46B6EBAB.4050805@midwinter.com","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-06T11:51:59Z","receivedAt":"2007-08-06T11:51:59Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 6 Aug 2007, Steven Grimm wrote:\n>\n> [I pointed out how dangerous committing hunks selectively can be]\n>\n> So I guess my point, after all that, is just that assumptions that are \n> valid in the context of one workflow are not necessarily as valid in \n> others, and that even in a particular context, not all changes are \n> created equal.\n\nRight. But I think a warning _is_ needed. So that everybody considers if \nit is safe in _her_ workflow.\n\nCiao,\nDscho\n"},{"id":"50121","messageId":"200708062136.50462.robin.rosenberg.lists@dewire.com","threadId":"9311","inReplyTo":"20070806035119.GB30269@fieldses.org","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"Robin Rosenberg","fromEmail":"robin.rosenberg.lists@dewire.com","sentAt":"2007-08-06T19:36:49Z","receivedAt":"2007-08-06T19:36:49Z","isPatch":true,"sender":{"key":"robin.rosenberg@dewire.com","avatar":"https://avatars.githubusercontent.com/u/46357?v=4"},"body":"måndag 06 augusti 2007 skrev J. Bruce Fields:\n> On Mon, Aug 06, 2007 at 01:26:21AM +0100, Johannes Schindelin wrote:\n> > On Sun, 5 Aug 2007, J. Bruce Fields wrote:\n> > > A big warning would be out of place in what is for now just an isolated\n> > > sentence in two different places. But I agree with you that this would\n> > > be worth mentioning in any eventual full-fledged git-gui tutorial.\n> > \n> > Unfortunately, I am really wasted by this weekend's efforts to bring \n> > msysgit.git along... could you be so kind as to cut&paste the relevant \n> > section in a reply to me, so I do not have to search for myself?\n> \n> Sure; appended. This isn't that different from Steffen's proposal.\n> \n> > I would not normally ask for such a favour; it is relatively easy to go on \n> > a search with Git, but I do have only 8 hours of sleep in the last 60 \n> > hours under my saddle...\n> \n> Hm. On the other hand, maybe we should just be refusing to feed your\n> addiction till you get some sleep.\n> \n> I wanna keep this short for now, so if we really think we shouldn't\n> mention of the hunk-selection thing without a warning, I'd rather just\n> omit mention of it, and go for something like: \"You can also use\n> gitlink:git-gui[1] to create commits and view changes in the index and\n> working tree\", and drop the second hunk. Whatever.\n\nWho reads manuals for GUI's? Rougly nobody, unless the user needs the gui \nbadly AND the GUI sucks badly. Manuals for GUI's are mostly tick-in-the-box \ndocumentation (which is the probably reason most GUI documentation suck too).\n\nUncommon/dangerous features should generally be harder to find, but can you \ncan also use the common pattern of popping a dialog explaining the dangers \nand forcing the user to click away the box. Of course there should be a \ncheckbox in the dialog \"[X] Void warranty and don't bother me with this \nquestion anymore.\"\n\nNevertheless the dangers should be explained somewhere, maybe in the git user \nmanual. I believe most people will learn from experience.\n\n-- robin\n"},{"id":"50039","messageId":"20070806194327.GE24946@fieldses.org","threadId":"9311","inReplyTo":"200708062136.50462.robin.rosenberg.lists@dewire.com","subject":"Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-06T19:43:27Z","receivedAt":"2007-08-06T19:43:27Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Aug 06, 2007 at 09:36:49PM +0200, Robin Rosenberg wrote:\n> Who reads manuals for GUI's? Rougly nobody, unless the user needs the gui \n> badly AND the GUI sucks badly. Manuals for GUI's are mostly tick-in-the-box \n> documentation (which is the probably reason most GUI documentation suck too).\n\nI tend to agree. But the goal for now isn't to provide complete\ndocumentation, it's just to briefly point out the existence of this tool\nand what it does.\n\nI haven't used it myself other than just to experiment a bit, but my\nimpression from the people involved is that they still consider it a bit\nyoung, but that they think it's useful and that they'd benefit from more\npeople trying it out.\n\n--b.\n"}]}