{"thread":{"id":"43234","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","startedAt":"2006-12-08T11:20:32Z","lastAt":"2006-12-10T23:05:11Z","messageCount":25,"participants":["Junio C Hamano","Nicolas Pitre","Linus Torvalds","Jakub Narebski","Alan Chandler","Josef Weidendorfer","J. Bruce Fields","Salikh Zakirov"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"298028","messageId":"7vy7pik51b.fsf@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":null,"subject":"Documentation/git-commit.txt","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-08T11:20:32Z","receivedAt":"2006-12-08T11:20:32Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I attempted to rewrite the git-commit documentation.\n\nI think I went overboard and ended up not using the word\n\"index\", but eradicating the word was not my intention.  I think\nwe should hint how the index is used to implement the semantics\nsomewhere near the end where it is not distracting to ordinary\nusers but is accessbile by people who are interested in the\nplumbing-Porcelain interface. \n\n---\n\n  The following patch will _not_ apply as is, as I sprinkled a lot\n  of annotations in it, but you should be able to run\n\n          sed -e '/^|/d'\n\n  on it to make it apply if you want.\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 517a86b..50e8fd0 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -14,25 +14,111 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Updates the index file for given paths, or all modified files if\n-'-a' is specified, and makes a commit object.  The command specified\n-by either the VISUAL or EDITOR environment variables are used to edit\n-the commit log message.\n|\n| General idea; (1) we do not have to say \"index\" in Porcelain-ish\n| documentation.  (2) we should have a separate ENVIRONMENT section\n| at the end as all UNIX manpage does.\n|\n+Records a tree state as a new commit object.  The command is\n+used for both recording your own changes and recording the\n+result of manual resolution of a conflicted merge.\n+\n+When recoring your own work, the contents of modified files in\n+your working tree are staged with gitlink:git-add[1].  Removal\n+of a file are staged with gitlink:git-rm[1].  After building the\n+state to be committed incrementally with these commands, `git\n+commit` (without any pathname parameter) is used to record what\n+has been staged so far.  This is the most basic form of the\n+command.  An example:\n|\n| Give examples early and abundance of them.  Mention add and rm\n| as staging commands; technically mv is also a staging command but\n| this manpage is not about various ways to stage things, but\n| making a commit out of staged state, so omit it.\n|\n+\n+------------\n+$ edit hello.c\n+$ git rm goodbye.c\n+$ git add hello.c\n+$ git commit\n+------------\n+\n+////////////\n+We should fix 'git rm' to remove goodbye.c from both index and\n+working tree for the above example.\n+////////////\n+\n+Instead of staging files after each individual change, you can\n+tell `git commit` to notice the changes to the tracked files in\n+your working tree and do corresponding `git add` and `git rm`\n+for you.  That is, this example does the same as the earlier\n+example if there is no other change in your working tree:\n+\n+------------\n+$ edit hello.c\n+$ rm goodbye.c\n+$ git commit -a\n+------------\n+\n+The command `git commit -a` first looks at your working tree,\n+notices that you have modified hello.c and removed goodbye.c,\n+and performs necessary `git add` and `git rm` for you.\n+\n+After staging changes to many files, you can alter the order the\n+changes are recorded in, by giving pathnames to `git commit`.\n+When pathnames are given, the command makes a commit that\n+only records the changes made to the named paths:\n+\n+------------\n+$ edit hello.c hello.h\n+$ git add hello.c hello.h\n+$ edit Makefile\n+$ git commit Makefile\n+------------\n+\n+This makes a commit that records the modification to `Makefile`.\n+The changes staged for `hello.c` and `hello.h` are not included\n+in the resulting commit.  However, their changes are not lost --\n+they are still staged and merely held back.  After the above\n+sequence, if you do:\n+\n+------------\n+$ git commit\n+------------\n+\n+this second commit would record the changes to `hello.c` and\n+`hello.h` as expected.\n+\n+\n+After a merge (initiated by either gitlink:git-merge[1] or\n+gitlink:git-pull[1]) stops because of conflicts, cleanly merged\n+paths are already staged to be committed for you, and paths that\n+conflicted are left in unmerged state.  You would have to first\n+check which paths are conflicting with gitlink:git-ls-files[1]\n+and after fixing them manually in your working tree, you would\n+stage the result as usual with gitlink:git-add[1]:\n+\n+------------\n+$ git ls-files -u\n+100644 c87c61af00c6d2cd7212240e26089e24b90bbe05 1\thello.c\n+100644 646b6e73318e04cfff7b20abd5d06be424bce503 2\thello.c\n+100644 44b1ce4c6b56348e1661b60fc923cb80cb44d4ff 3\thello.c\n+$ edit hello.c\n+$ git add hello.c\n+------------\n|\n| Obviously 'ls-files -u' is a plumbing so we might want to give an\n| equivalent Porcelain.  We could say 'git status' and have the\n| reader look for \"unmerged:\", which might be better.  I dunno.\n|\n+\n+After resolving conflicts and staging the result, `git ls-files -u`\n+would stop mentioning the conflicted path.  When you are done,\n+run `git commit` to finally record the merge:\n+\n+------------\n+$ git commit\n+------------\n+\n+As with the case to record your own changes, you can use `-a`\n+option to save typing.  One difference is that during a merge\n+resolution, you cannot use `git commit` with pathnames to\n+alter the order the changes are committed, because the merge\n+should be recorded as a single commit.  In fact, the command\n+refuses to run when given pathnames (but see `-i` option).\n|\n| \"con paths\" form is really about 'alter the order of things\n| that are committed', in other words 'you may have started \n| staging but we let you split what is staged'.  Once the reader\n| understands it, it should be natural why we cannot use \"paths\"\n| during a merge resolution.\n|\n \n-Several environment variable are used during commits.  They are\n-documented in gitlink:git-commit-tree[1].\n-\n-\n-This command can run `commit-msg`, `pre-commit`, and\n-`post-commit` hooks.  See link:hooks.html[hooks] for more\n-information.\n|\n| In addition to ENVIRONMENT, many Porcelain-ish can invoke\n| hooks, and we should have HOOKS section at the same location\n| across manpages so people can expect where to find them.\n| I just chose them to be at the end.\n|\n\n \n OPTIONS\n -------\n -a|--all::\n-\tUpdate all paths in the index file.  This flag notices\n-\tfiles that have been modified and deleted, but new files\n-\tyou have not told git about are not affected.\n+\tTell the command to automatically stage files that have\n+\tbeen modified and deleted, but new files you have not\n+\ttold git about are not affected.\n|\n| No need to say \"index\", although I do not think we should\n| avoid the word.\n|\n \n -c or -C <commit>::\n \tTake existing commit object, and reuse the log message\n@@ -55,16 +141,13 @@ OPTIONS\n -s|--signoff::\n \tAdd Signed-off-by line at the end of the commit message.\n \n--v|--verify::\n-\tLook for suspicious lines the commit introduces, and\n-\tabort committing if there is one.  The definition of\n-\t'suspicious lines' is currently the lines that has\n-\ttrailing whitespaces, and the lines whose indentation\n-\thas a SP character immediately followed by a TAB\n-\tcharacter.  This is the default.\n-\n--n|--no-verify::\n-\tThe opposite of `--verify`.\n+--no-verify::\n+\tBy default, the command looks for suspicious lines the\n+\tcommit introduces, and aborts committing if there is one.\n+\tThe definition of 'suspicious lines' is currently the\n+\tlines that has trailing whitespaces, and the lines whose\n+\tindentation has a SP character immediately followed by a\n+\tTAB character.  This option turns off the check.\n|\n| The --verify option does not exist anymore.  This is an independent fix.\n| We do not yet describe --verbose (and real '-v') in the\n| current page, which is quite BAD.  It shows the diff between HEAD\n| and what is being committed.\n|\n \n -e|--edit::\n \tThe message taken from file with `-F`, command line with\n@@ -95,16 +177,16 @@ but can be used to amend a merge commit.\n --\n \n -i|--include::\n-\tInstead of committing only the files specified on the\n-\tcommand line, update them in the index file and then\n-\tcommit the whole index.  This is the traditional\n-\tbehavior.\n+\tBefore making a commit out of staged contents so far,\n+\tstage the contents of paths given on the command line\n+\tas well.  This is usually not what you want unless you\n+\tare concluding a conflicted merge.\n \n -o|--only::\n-\tCommit only the files specified on the command line.\n-\tThis format cannot be used during a merge, nor when the\n-\tindex and the latest commit does not match on the\n-\tspecified paths to avoid confusion.\n+\tCommit only the files specified on the command line;\n+\tthis is the default when pathnames are given on the\n+\tcommand line, so you usually do not have to give this\n+\toption.  This format cannot be used during a merge.\n \n \\--::\n \tDo not interpret any more arguments as options.\n@@ -118,46 +200,16 @@ If you make a commit and then found a mistake immediately after\n that, you can recover from it with gitlink:git-reset[1].\n \n \n-Discussion\n-----------\n-\n-`git commit` without _any_ parameter commits the tree structure\n-recorded by the current index file.  This is a whole-tree commit\n-even the command is invoked from a subdirectory.\n-\n-`git commit --include paths...` is equivalent to\n-\n-\tgit update-index --remove paths...\n-\tgit commit\n-\n-That is, update the specified paths to the index and then commit\n-the whole tree.\n-\n-`git commit paths...` largely bypasses the index file and\n-commits only the changes made to the specified paths.  It has\n-however several safety valves to prevent confusion.\n-\n-. It refuses to run during a merge (i.e. when\n-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users\n-  that the traditional semantics now needs -i flag.\n-\n-. It refuses to run if named `paths...` are different in HEAD\n-  and the index (ditto about reminding).  Added paths are OK.\n-  This is because an earlier `git diff` (not `git diff HEAD`)\n-  would have shown the differences since the last `git\n-  update-index paths...` to the user, and an inexperienced user\n-  may mistakenly think that the changes between the index and\n-  the HEAD (i.e. earlier changes made before the last `git\n-  update-index paths...` was done) are not being committed.\n-\n-. It reads HEAD commit into a temporary index file, updates the\n-  specified `paths...` and makes a commit.  At the same time,\n-  the real index file is also updated with the same `paths...`.\n-\n-`git commit --all` updates the index file with _all_ changes to\n-the working tree, and makes a whole-tree commit, regardless of\n-which subdirectory the command is invoked in.\n|\n| Lose this section that only talks about implementation detail\n| and expect the readers to understand the behaviour from it.\n| The audience when the page was originally written were well\n| versed in plumbing and the above technical description\n| conveyed what we wanted to say in very precise terms, but that\n| was only because git was very young.\n|\n\n+ENVIRONMENT VARIABLES\n+---------------------\n+The command specified by either the VISUAL or EDITOR environment\n+variables are used to edit the commit log message.\n \n+HOOKS\n+-----\n+This command can run `commit-msg`, `pre-commit`, and\n+`post-commit` hooks.  See link:hooks.html[hooks] for more\n+information.\n \n Author\n ------\n"},{"id":"298216","messageId":"4579529F.9030401@Intel.com","threadId":"43234","inReplyTo":"7vy7pik51b.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"Salikh Zakirov","fromEmail":"salikh.zakirov@intel.com","sentAt":"2006-12-08T11:55:11Z","receivedAt":"2006-12-08T11:55:11Z","isPatch":false,"sender":{"key":"salikh.zakirov@gmail.com","avatar":null},"body":"Junio Hamano wrote:\n> +Instead of staging files after each individual change, you can\n> +tell `git commit` to notice the changes to the tracked files in\n> +your working tree and do corresponding `git add` and `git rm`\n> +for you.  \n\nThis part is confusing as hell to anyone having any experience\nwith either CVS, SVN, Hg or Monotone, as doing \"corresponding `git add`\nand `git rm`\" commands automatically will be interpreted as adding\nuntracked files automatically, which is not the case here.\n"},{"id":"298238","messageId":"7vfybqi3r1.fsf@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":"4579529F.9030401@Intel.com","subject":"Re: Documentation/git-commit.txt","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-08T19:31:14Z","receivedAt":"2006-12-08T19:31:14Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Salikh Zakirov <Salikh.Zakirov@Intel.com> writes:\n\n> Junio Hamano wrote:\n>> +Instead of staging files after each individual change, you can\n>> +tell `git commit` to notice the changes to the tracked files in\n>> +your working tree and do corresponding `git add` and `git rm`\n>> +for you.  \n>\n> This part is confusing as hell to anyone having any experience\n> with either CVS, SVN, Hg or Monotone, as doing \"corresponding `git add`\n> and `git rm`\" commands automatically will be interpreted as adding\n> untracked files automatically, which is not the case here.\n\nWell, that's why the description says 'the changes to the\ntracked files' above to make it clear.  An obvious alternative\nis not to talk about staging in terms of `git add` and `git rm`\nbut instead mention `git update-index` in that part of the\ndocumentation, but I think that is going backwards.  I think the\nconclusion of recent discussions is not to paper over the\ndifferences from new people (nor making git closer to other\nsystems by castrating git), but make things easier to learn for\nthem.  My attempt to update git-commit documentation is a part\nof this effort.\n\nBetter rewording is very much appreciated.\n\nBut you are right.  Prior experiences with other systems would\nmake it harder to learn git here, because 'git add', especially\nwith Nico's enhancement in 'next', is different from 'cvs add'.\n\nThe problem is that these systems do not have the concept of\ntracking 'contents' (they instead track paths), and 'add' to\nthem mean 'add the named paths to the set of tracked paths'.\n\nOn the other hand, git fundamentally tracks contents.  We do\nhave the concept of 'the set of tracked paths', but that is a\nside effect of tracking contents.  In other words, you do not\n'add' a path without 'add'ing its contents.\n\nBy the way, I have been wondering if the --only variant of the\ncommand should also add untracked files to the index.  That is:\n\n\t$ git commit foo.c '*.h'\n\ncurrently barfs if foo.c is not tracked, and/or there is no\ntracked header files.  We could instead run git-update-index\n--add on them.\n\nIncidentally, this would make this sequence possible:\n\n\t$ tar xf /var/tmp/foo.tar ;# extract tarball here.\n        $ git init-db\n        $ git commit -m 'initial import' .\n"},{"id":"296824","messageId":"Pine.LNX.4.64.0612081443250.2630@xanadu.home","threadId":"43234","inReplyTo":"7vfybqi3r1.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-08T19:45:41Z","receivedAt":"2006-12-08T19:45:41Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 8 Dec 2006, Junio C Hamano wrote:\n\n> By the way, I have been wondering if the --only variant of the\n> command should also add untracked files to the index.  That is:\n> \n> \t$ git commit foo.c '*.h'\n> \n> currently barfs if foo.c is not tracked, and/or there is no\n> tracked header files.  We could instead run git-update-index\n> --add on them.\n\nThat would be a good thing indeed.\n\n> Incidentally, this would make this sequence possible:\n> \n> \t$ tar xf /var/tmp/foo.tar ;# extract tarball here.\n>         $ git init-db\n>         $ git commit -m 'initial import' .\n\n... making the UI even more consistent.\n\n\n"},{"id":"295946","messageId":"200612082256.45456.alan@chandlerfamily.org.uk","threadId":"43234","inReplyTo":"4579529F.9030401@Intel.com","subject":"Re: Documentation/git-commit.txt","fromName":"Alan Chandler","fromEmail":"alan@chandlerfamily.org.uk","sentAt":"2006-12-08T22:56:45Z","receivedAt":"2006-12-08T22:56:45Z","isPatch":false,"sender":{"key":"alan@chandlerfamily.org.uk","avatar":"https://gravatar.com/avatar/1862247e5ea8eac114c842f9dc3a5db6253754e24ef7171757cf97eedce48b8c?d=mp&s=160"},"body":"On Friday 08 December 2006 11:55, Salikh Zakirov wrote:\n> Junio Hamano wrote:\n> > +Instead of staging files after each individual change, you can\n> > +tell `git commit` to notice the changes to the tracked files in\n> > +your working tree and do corresponding `git add` and `git rm`\n> > +for you.\n>\n> This part is confusing as hell to anyone having any experience\n> with either CVS, SVN, Hg or Monotone, as doing \"corresponding `git\n> add` and `git rm`\" commands automatically will be interpreted as\n> adding untracked files automatically, which is not the case here.\n\nI thought the wording here was a little weird too.  I think this stems \nfrom the mistake of saying \"tracked files\" instead of \"tracked content\" \nwhich then leads to you falling back to the git add and git rm \ncommands..\n\nHow about the following wording here\n\nInstead of staging the content of each file immediately after changing \nit, you can wait until you have completed all the changes you want to \nmake and then use the `-a` option to tell `git commit` to look for all \nchanges to the content it is tracking and commit it automatically. That \nis, this example ...\n\n\n  \n\n-- \nAlan Chandler\n"},{"id":"294372","messageId":"Pine.LNX.4.64.0612082141260.2630@xanadu.home","threadId":"43234","inReplyTo":"7vy7pik51b.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-09T02:58:14Z","receivedAt":"2006-12-09T02:58:14Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 8 Dec 2006, Junio C Hamano wrote:\n\n> I attempted to rewrite the git-commit documentation.\n> \n> I think I went overboard and ended up not using the word\n> \"index\", but eradicating the word was not my intention.  I think\n> we should hint how the index is used to implement the semantics\n> somewhere near the end where it is not distracting to ordinary\n> users but is accessbile by people who are interested in the\n> plumbing-Porcelain interface. \n[...]\n\nFrankly I feel unconfortable with this.\n\n1) too many examples.\n\nYes, examples are good, but somehow there is something in the current \ntext that make me feel they are not providing the clarification they \nshould.  Dunno... I think I'd still push them after option list.\n\n2) explanation of how to resolve and commit a conflicting merge should \n   really be found in git-merge.txt not in git-commit.txt.\n\nIt feels a bit awkward to suddenly start talking about git ls-files and \nmerge here.  It would be much clearer to simply say \"when done just \ncommit your changes as usual\" in the merge doc than bringing in merge \nconcepts in the commit doc.\n\n[...]\n\nI started to insert my comments inline, but at some point it became too \nmessy.  So I decided to give it a try of my own instead.  Here what I \nthink would be a better direction for improving the commit man page \n(would need a few examples inserted towards the end like usual, and the \nenv vars too):\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 517a86b..6a9cec9 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -14,25 +14,43 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Updates the index file for given paths, or all modified files if\n-'-a' is specified, and makes a commit object.  The command specified\n-by either the VISUAL or EDITOR environment variables are used to edit\n-the commit log message.\n+Use 'git commit' when you want to record your changes into the repository\n+along with a log message describing what the commit is about. All changes\n+to be committed must be explicitly identified using one of the following\n+methods:\n \n-Several environment variable are used during commits.  They are\n-documented in gitlink:git-commit-tree[1].\n+1) by using gitlink:git-add[1] to incrementally \"add\" changes to the\n+   next commit before using the 'commit' command (Note: even modified\n+   files must be \"added\");\n \n+2) by using gitlink:git-rm[1] to identify content removal for the next\n+   commit, again before using the 'commit' command;\n+\n+3) by directly listing files containing changes to be committed as arguments\n+   to the 'commit' command, in which cases only those files alone will be\n+   considered for the commit;\n+\n+4) by using the -a switch with the 'commit' command to automatically \"add\"\n+   changes from all known files i.e. files that have already been committed\n+   before, and perform the actual commit.\n+\n+The 'git status' command can be used to obtain a summary of what is included\n+by (1) and (2) for the next commit.\n+\n+If you make a commit and then found a mistake immediately after\n+that, you can recover from it with gitlink:git-reset[1].\n \n This command can run `commit-msg`, `pre-commit`, and\n `post-commit` hooks.  See link:hooks.html[hooks] for more\n information.\n \n+\n OPTIONS\n -------\n -a|--all::\n-\tUpdate all paths in the index file.  This flag notices\n-\tfiles that have been modified and deleted, but new files\n-\tyou have not told git about are not affected.\n+\tTell the command to automatically stage files that have\n+\tbeen modified and deleted, but new files you have not\n+\ttold git about are not affected.\n \n -c or -C <commit>::\n \tTake existing commit object, and reuse the log message\n@@ -95,68 +113,18 @@ but can be used to amend a merge commit.\n --\n \n -i|--include::\n-\tInstead of committing only the files specified on the\n-\tcommand line, update them in the index file and then\n-\tcommit the whole index.  This is the traditional\n-\tbehavior.\n-\n--o|--only::\n-\tCommit only the files specified on the command line.\n-\tThis format cannot be used during a merge, nor when the\n-\tindex and the latest commit does not match on the\n-\tspecified paths to avoid confusion.\n+\tBefore making a commit out of staged contents so far,\n+\tstage the contents of paths given on the command line\n+\tas well.  This is usually not what you want unless you\n+\tare concluding a conflicted merge.\n \n \\--::\n \tDo not interpret any more arguments as options.\n \n <file>...::\n-\tFiles to be committed.  The meaning of these is\n-\tdifferent between `--include` and `--only`.  Without\n-\teither, it defaults `--only` semantics.\n-\n-If you make a commit and then found a mistake immediately after\n-that, you can recover from it with gitlink:git-reset[1].\n-\n-\n-Discussion\n-----------\n-\n-`git commit` without _any_ parameter commits the tree structure\n-recorded by the current index file.  This is a whole-tree commit\n-even the command is invoked from a subdirectory.\n-\n-`git commit --include paths...` is equivalent to\n-\n-\tgit update-index --remove paths...\n-\tgit commit\n-\n-That is, update the specified paths to the index and then commit\n-the whole tree.\n-\n-`git commit paths...` largely bypasses the index file and\n-commits only the changes made to the specified paths.  It has\n-however several safety valves to prevent confusion.\n-\n-. It refuses to run during a merge (i.e. when\n-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users\n-  that the traditional semantics now needs -i flag.\n-\n-. It refuses to run if named `paths...` are different in HEAD\n-  and the index (ditto about reminding).  Added paths are OK.\n-  This is because an earlier `git diff` (not `git diff HEAD`)\n-  would have shown the differences since the last `git\n-  update-index paths...` to the user, and an inexperienced user\n-  may mistakenly think that the changes between the index and\n-  the HEAD (i.e. earlier changes made before the last `git\n-  update-index paths...` was done) are not being committed.\n-\n-. It reads HEAD commit into a temporary index file, updates the\n-  specified `paths...` and makes a commit.  At the same time,\n-  the real index file is also updated with the same `paths...`.\n-\n-`git commit --all` updates the index file with _all_ changes to\n-the working tree, and makes a whole-tree commit, regardless of\n-which subdirectory the command is invoked in.\n+\tFiles to be committed.  If provided, only those files are\n+\tconsidered FOR COMMIT.  If `-i` or `--include` is also provided\n+\tthen the staged content is included as well.\n \n \n"},{"id":"296130","messageId":"7vpsatelvv.fsf@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612082141260.2630@xanadu.home","subject":"Re: Documentation/git-commit.txt","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-09T04:25:24Z","receivedAt":"2006-12-09T04:25:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre <nico@cam.org> writes:\n\n> Frankly I feel unconfortable with this.\n>\n> 1) too many examples.\n>\n> Yes, examples are good, but somehow there is something in the current \n> text that make me feel they are not providing the clarification they \n> should.  Dunno... I think I'd still push them after option list.\n\nHmmm.  I was merely trying to respond with recent requests on\nthe list (might have been #git log) to make common usage\nexamples more prominent.  While I feel that following the UNIXy\nmanpage tradition to push examples down is the right thing to\ndo, you and I are not the primary audience of Porcelain\nmanpages, so...\n\n> 2) explanation of how to resolve and commit a conflicting merge should \n>    really be found in git-merge.txt not in git-commit.txt.\n>\n> It feels a bit awkward to suddenly start talking about git ls-files and \n> merge here.\n\nI agree that it looks a bit out of place; the primary reason I\ntalked about the merge was to make it clear that a conflicted\nmerge will still stage the changes for cleanly auto-resolved\npaths.  In other words, it makes me feel uneasy that there is no\nmention of it in the list in your version that follows this\nsentence:\n\n> +... All changes\n> +to be committed must be explicitly identified using one of the following\n> +methods:\n\nIt would make me happier if you had, at the end of enumeration,\nsomething like:\n\n\tNote that the contents of the paths that resolved\n        cleanly by a conflicted merge are automatically staged\n        for the next commit; you still need to explicitly\n        identify what you want in the resulting commit using one\n        of the above methods before concluding the merge.\n\nAnother reason I described the merge workflow is it would become\nmuch less clear why --only is useless in merge situation if the\nreader does not know that a conflicted merge stages the\nauto-resolved changes.\n"},{"id":"297074","messageId":"20061209043123.GB18204@fieldses.org","threadId":"43234","inReplyTo":"7vy7pik51b.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-12-09T04:31:23Z","receivedAt":"2006-12-09T04:31:23Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Dec 08, 2006 at 03:20:32AM -0800, Junio C Hamano wrote:\n> I think I went overboard and ended up not using the word\n> \"index\", but eradicating the word was not my intention.\n\nYeah, \"index\" is a perfectly OK word, and it's already used all over the\ndocumentation.\n\nI think what you want to avoid is a huge digression into blobs, trees,\nSHA1's, and the structure of the index file when you could just slip it\nin there without a lot of fanfare, maybe like:\n\n> +When recoring your own work, the contents of modified files in\n> +your working tree are staged with gitlink:git-add[1].\n\t\t       ^^^\n...are temporarily stored to a staging area called the \"index\" with...\n\n(though maybe that's a little cumbersome).\n\nAlso, I don't think there's anything wrong with the verb \"stage\", but I\nthink it may be a little less commonly used (in this meaning) than the\nterm \"staging area\", so people might catch on faster if we started with\n\"staging area\".\n\n"},{"id":"297745","messageId":"20061209044213.GC18204@fieldses.org","threadId":"43234","inReplyTo":"7vpsatelvv.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-12-09T04:42:13Z","receivedAt":"2006-12-09T04:42:13Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Dec 08, 2006 at 08:25:24PM -0800, Junio C Hamano wrote:\n> Hmmm.  I was merely trying to respond with recent requests on\n> the list (might have been #git log) to make common usage\n> examples more prominent.  While I feel that following the UNIXy\n> manpage tradition to push examples down is the right thing to\n> do, you and I are not the primary audience of Porcelain\n> manpages, so...\n\nI think manpages are primarily reference documents, so it's more\nimportant to be able to get to the list of options without paging down\ntoo far....\n\nWe could always say \"see EXAMPLES below for more detail\", or \"see the\nchapter 3 of the tutorial/user manual/whatever\".\n\n"},{"id":"296422","messageId":"7vd56tei20.fsf_-_@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612082141260.2630@xanadu.home","subject":"[PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-09T05:48:07Z","receivedAt":"2006-12-09T05:48:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\nSigned-off-by: Junio C Hamano <junkio@cox.net>\n---\n\n * So how about this?\n\n Documentation/git-commit.txt |  227 ++++++++++++++++++++++++++++--------------\n 1 files changed, 154 insertions(+), 73 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 517a86b..8fe42cb 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -14,25 +14,47 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Updates the index file for given paths, or all modified files if\n-'-a' is specified, and makes a commit object.  The command specified\n-by either the VISUAL or EDITOR environment variables are used to edit\n-the commit log message.\n+Use 'git commit' when you want to record your changes into the repository\n+along with a log message describing what the commit is about. All changes\n+to be committed must be explicitly identified using one of the following\n+methods:\n \n-Several environment variable are used during commits.  They are\n-documented in gitlink:git-commit-tree[1].\n+1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n+   next commit before using the 'commit' command (Note: even modified\n+   files must be \"added\");\n \n+2. by using gitlink:git-rm[1] to identify content removal for the next\n+   commit, again before using the 'commit' command;\n+\n+3. by directly listing files containing changes to be committed as arguments\n+   to the 'commit' command, in which cases only those files alone will be\n+   considered for the commit;\n+\n+4. by using the -a switch with the 'commit' command to automatically \"add\"\n+   changes from all known files i.e. files that have already been committed\n+   before, and perform the actual commit.\n+\n+Note that the contents of the paths that resolved cleanly by a\n+conflicted merge are automatically staged for the next commit;\n+you still need to explicitly identify what you want in the\n+resulting commit using one of the above methods before\n+recording the merge commit.\n+\n+The gitlink:git-status[1] command can be used to obtain a\n+summary of what is included by any of the above for the next\n+commit by giving the same set of parameters you would give to\n+this command.\n+\n+If you make a commit and then found a mistake immediately after\n+that, you can recover from it with gitlink:git-reset[1].\n \n-This command can run `commit-msg`, `pre-commit`, and\n-`post-commit` hooks.  See link:hooks.html[hooks] for more\n-information.\n \n OPTIONS\n -------\n -a|--all::\n-\tUpdate all paths in the index file.  This flag notices\n-\tfiles that have been modified and deleted, but new files\n-\tyou have not told git about are not affected.\n+\tTell the command to automatically stage files that have\n+\tbeen modified and deleted, but new files you have not\n+\ttold git about are not affected.\n \n -c or -C <commit>::\n \tTake existing commit object, and reuse the log message\n@@ -55,16 +77,13 @@ OPTIONS\n -s|--signoff::\n \tAdd Signed-off-by line at the end of the commit message.\n \n--v|--verify::\n-\tLook for suspicious lines the commit introduces, and\n-\tabort committing if there is one.  The definition of\n-\t'suspicious lines' is currently the lines that has\n-\ttrailing whitespaces, and the lines whose indentation\n-\thas a SP character immediately followed by a TAB\n-\tcharacter.  This is the default.\n-\n--n|--no-verify::\n-\tThe opposite of `--verify`.\n+--no-verify::\n+\tBy default, the command looks for suspicious lines the\n+\tcommit introduces, and aborts committing if there is one.\n+\tThe definition of 'suspicious lines' is currently the\n+\tlines that has trailing whitespaces, and the lines whose\n+\tindentation has a SP character immediately followed by a\n+\tTAB character.  This option turns off the check.\n \n -e|--edit::\n \tThe message taken from file with `-F`, command line with\n@@ -95,16 +114,16 @@ but can be used to amend a merge commit.\n --\n \n -i|--include::\n-\tInstead of committing only the files specified on the\n-\tcommand line, update them in the index file and then\n-\tcommit the whole index.  This is the traditional\n-\tbehavior.\n+\tBefore making a commit out of staged contents so far,\n+\tstage the contents of paths given on the command line\n+\tas well.  This is usually not what you want unless you\n+\tare concluding a conflicted merge.\n \n -o|--only::\n-\tCommit only the files specified on the command line.\n-\tThis format cannot be used during a merge, nor when the\n-\tindex and the latest commit does not match on the\n-\tspecified paths to avoid confusion.\n+\tCommit only the files specified on the command line;\n+\tthis is the default when pathnames are given on the\n+\tcommand line, so you usually do not have to give this\n+\toption.  This format cannot be used during a merge.\n \n \\--::\n \tDo not interpret any more arguments as options.\n@@ -114,50 +133,112 @@ but can be used to amend a merge commit.\n \tdifferent between `--include` and `--only`.  Without\n \teither, it defaults `--only` semantics.\n \n-If you make a commit and then found a mistake immediately after\n-that, you can recover from it with gitlink:git-reset[1].\n-\n-\n-Discussion\n-----------\n-\n-`git commit` without _any_ parameter commits the tree structure\n-recorded by the current index file.  This is a whole-tree commit\n-even the command is invoked from a subdirectory.\n-\n-`git commit --include paths...` is equivalent to\n-\n-\tgit update-index --remove paths...\n-\tgit commit\n-\n-That is, update the specified paths to the index and then commit\n-the whole tree.\n-\n-`git commit paths...` largely bypasses the index file and\n-commits only the changes made to the specified paths.  It has\n-however several safety valves to prevent confusion.\n-\n-. It refuses to run during a merge (i.e. when\n-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users\n-  that the traditional semantics now needs -i flag.\n-\n-. It refuses to run if named `paths...` are different in HEAD\n-  and the index (ditto about reminding).  Added paths are OK.\n-  This is because an earlier `git diff` (not `git diff HEAD`)\n-  would have shown the differences since the last `git\n-  update-index paths...` to the user, and an inexperienced user\n-  may mistakenly think that the changes between the index and\n-  the HEAD (i.e. earlier changes made before the last `git\n-  update-index paths...` was done) are not being committed.\n-\n-. It reads HEAD commit into a temporary index file, updates the\n-  specified `paths...` and makes a commit.  At the same time,\n-  the real index file is also updated with the same `paths...`.\n-\n-`git commit --all` updates the index file with _all_ changes to\n-the working tree, and makes a whole-tree commit, regardless of\n-which subdirectory the command is invoked in.\n \n+EXAMPLES\n+--------\n+When recording your own work, the contents of modified files in\n+your working tree are temporarily stored to a staging area\n+called the \"index\" with gitlink:git-add[1].  Removal\n+of a file is staged with gitlink:git-rm[1].  After building the\n+state to be committed incrementally with these commands, `git\n+commit` (without any pathname parameter) is used to record what\n+has been staged so far.  This is the most basic form of the\n+command.  An example:\n+\n+------------\n+$ edit hello.c\n+$ git rm goodbye.c\n+$ git add hello.c\n+$ git commit\n+------------\n+\n+////////////\n+We should fix 'git rm' to remove goodbye.c from both index and\n+working tree for the above example.\n+////////////\n+\n+Instead of staging files after each individual change, you can\n+tell `git commit` to notice the changes to the tracked files in\n+your working tree and do corresponding `git add` and `git rm`\n+for you.  That is, this example does the same as the earlier\n+example if there is no other change in your working tree:\n+\n+------------\n+$ edit hello.c\n+$ rm goodbye.c\n+$ git commit -a\n+------------\n+\n+The command `git commit -a` first looks at your working tree,\n+notices that you have modified hello.c and removed goodbye.c,\n+and performs necessary `git add` and `git rm` for you.\n+\n+After staging changes to many files, you can alter the order the\n+changes are recorded in, by giving pathnames to `git commit`.\n+When pathnames are given, the command makes a commit that\n+only records the changes made to the named paths:\n+\n+------------\n+$ edit hello.c hello.h\n+$ git add hello.c hello.h\n+$ edit Makefile\n+$ git commit Makefile\n+------------\n+\n+This makes a commit that records the modification to `Makefile`.\n+The changes staged for `hello.c` and `hello.h` are not included\n+in the resulting commit.  However, their changes are not lost --\n+they are still staged and merely held back.  After the above\n+sequence, if you do:\n+\n+------------\n+$ git commit\n+------------\n+\n+this second commit would record the changes to `hello.c` and\n+`hello.h` as expected.\n+\n+After a merge (initiated by either gitlink:git-merge[1] or\n+gitlink:git-pull[1]) stops because of conflicts, cleanly merged\n+paths are already staged to be committed for you, and paths that\n+conflicted are left in unmerged state.  You would have to first\n+check which paths are conflicting with gitlink:git-status[1]\n+and after fixing them manually in your working tree, you would\n+stage the result as usual with gitlink:git-add[1]:\n+\n+------------\n+$ git status | grep unmerged\n+unmerged: hello.c\n+$ edit hello.c\n+$ git add hello.c\n+------------\n+\n+After resolving conflicts and staging the result, `git ls-files -u`\n+would stop mentioning the conflicted path.  When you are done,\n+run `git commit` to finally record the merge:\n+\n+------------\n+$ git commit\n+------------\n+\n+As with the case to record your own changes, you can use `-a`\n+option to save typing.  One difference is that during a merge\n+resolution, you cannot use `git commit` with pathnames to\n+alter the order the changes are committed, because the merge\n+should be recorded as a single commit.  In fact, the command\n+refuses to run when given pathnames (but see `-i` option).\n+\n+\n+ENVIRONMENT VARIABLES\n+---------------------\n+The command specified by either the VISUAL or EDITOR environment\n+variables is used to edit the commit log message.\n+\n+HOOKS\n+-----\n+This command can run `commit-msg`, `pre-commit`, and\n+`post-commit` hooks.  See link:hooks.html[hooks] for more\n+information.\n \n Author\n ------\n-- \n1.4.4.2.g7d2d-dirty\n\n"},{"id":"298756","messageId":"Pine.LNX.4.64.0612091442470.2630@xanadu.home","threadId":"43234","inReplyTo":"7vpsatelvv.fsf@assigned-by-dhcp.cox.net","subject":"Re: Documentation/git-commit.txt","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-09T19:58:11Z","receivedAt":"2006-12-09T19:58:11Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 8 Dec 2006, Junio C Hamano wrote:\n\n> Nicolas Pitre <nico@cam.org> writes:\n> \n> > Frankly I feel unconfortable with this.\n> >\n> > 1) too many examples.\n> >\n> > Yes, examples are good, but somehow there is something in the current \n> > text that make me feel they are not providing the clarification they \n> > should.  Dunno... I think I'd still push them after option list.\n> \n> Hmmm.  I was merely trying to respond with recent requests on\n> the list (might have been #git log) to make common usage\n> examples more prominent.  While I feel that following the UNIXy\n> manpage tradition to push examples down is the right thing to\n> do, you and I are not the primary audience of Porcelain\n> manpages, so...\n\nSure, but sometimes too much is just as bad as not enough.  And given \nthe amount of text in your version I feel the essence of the information \ngets dilluted too much.\n\n> > 2) explanation of how to resolve and commit a conflicting merge should \n> >    really be found in git-merge.txt not in git-commit.txt.\n> >\n> > It feels a bit awkward to suddenly start talking about git ls-files and \n> > merge here.\n> \n> I agree that it looks a bit out of place; the primary reason I\n> talked about the merge was to make it clear that a conflicted\n> merge will still stage the changes for cleanly auto-resolved\n> paths.  In other words, it makes me feel uneasy that there is no\n> mention of it in the list in your version that follows this\n> sentence:\n> \n> > +... All changes\n> > +to be committed must be explicitly identified using one of the following\n> > +methods:\n> \n> It would make me happier if you had, at the end of enumeration,\n> something like:\n> \n> \tNote that the contents of the paths that resolved\n>         cleanly by a conflicted merge are automatically staged\n>         for the next commit; you still need to explicitly\n>         identify what you want in the resulting commit using one\n>         of the above methods before concluding the merge.\n\nBut why couldn't this be in the git-merge man page instead?  That is \nprecisely the sort of addition that makes me feel like we're trying to \nsay too much at the same time.  When in the context of learning how \n\"commit\" works, it is certainly not necessary to talk about how \"merge\" \nworks.  That should really be mentioned in the \"merging\" documentation \n(with a link to git-commit for more options on commit).\n\n> Another reason I described the merge workflow is it would become\n> much less clear why --only is useless in merge situation if the\n> reader does not know that a conflicted merge stages the\n> auto-resolved changes.\n\nSure, but the whole merge concept might still not make any sense at the \nmoment the user is learning about commit.  In other words, the \"commit\" \ndocumentation must not depend on the \"merge\" concept.  It should rather \nbe the other way around, i.e. the \"merge\" documentation can easily \ndepend on the \"commit\" documentation.\n\nJust like I carefully avoided talking about \"commit -a\" in the git-add \nman page to avoid circular conceptual dependencies.  But obviously the \ngit-commit man page must talk about the \"add\" concept.\n\nThis way you get a progressive knowledge base with git-add which pretty \nmuch stands on its own, then you move to git-commit that depends on \ngit-add, then you move to merging and resolving conflicts that depend on \ngit-commit.  And so without being distracted by concepts you don't need \nto know just yet along the way.\n\n\n"},{"id":"297728","messageId":"elf7bt$hiq$1@sea.gmane.org","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612091442470.2630@xanadu.home","subject":"Re: Documentation/git-commit.txt","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-12-09T20:49:13Z","receivedAt":"2006-12-09T20:49:13Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Nicolas Pitre wrote:\n\n> On Fri, 8 Dec 2006, Junio C Hamano wrote:\n[...]\n>> Another reason I described the merge workflow is it would become\n>> much less clear why --only is useless in merge situation if the\n>> reader does not know that a conflicted merge stages the\n>> auto-resolved changes.\n> \n> Sure, but the whole merge concept might still not make any sense at the \n> moment the user is learning about commit.  In other words, the \"commit\" \n> documentation must not depend on the \"merge\" concept.  It should rather \n> be the other way around, i.e. the \"merge\" documentation can easily \n> depend on the \"commit\" documentation.\n> \n> Just like I carefully avoided talking about \"commit -a\" in the git-add \n> man page to avoid circular conceptual dependencies.  But obviously the \n> git-commit man page must talk about the \"add\" concept.\n> \n> This way you get a progressive knowledge base with git-add which pretty \n> much stands on its own, then you move to git-commit that depends on \n> git-add, then you move to merging and resolving conflicts that depend on \n> git-commit.  And so without being distracted by concepts you don't need \n> to know just yet along the way.\n\nIMVHO for reference documentation (and manpages for commands are such\ndocumentation) it is more important to be complete, than to be\nself-contained and without circular conceptual dependencies. The latter\n(and defining things before using it) is more important for things like\ntutorial or quickstart.\n\nIf one is not doing merge then one can skip the talk about merges. If one\ngit-commit complains about using --only (because of merge), one would\nrather search for information in git-commit(1), not git-merge(1) or\ngit-pull(1); well, the merge might be result of git-checkout -m.\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"},{"id":"298101","messageId":"Pine.LNX.4.64.0612091517010.2630@xanadu.home","threadId":"43234","inReplyTo":"7vd56tei20.fsf_-_@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-09T21:15:42Z","receivedAt":"2006-12-09T21:15:42Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 8 Dec 2006, Junio C Hamano wrote:\n\n> \n> Signed-off-by: Junio C Hamano <junkio@cox.net>\n> ---\n> \n>  * So how about this?\n\nMuch better.  Comments below.\n\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 517a86b..8fe42cb 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -14,25 +14,47 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> -Updates the index file for given paths, or all modified files if\n> -'-a' is specified, and makes a commit object.  The command specified\n> -by either the VISUAL or EDITOR environment variables are used to edit\n> -the commit log message.\n> +Use 'git commit' when you want to record your changes into the repository\n> +along with a log message describing what the commit is about. All changes\n> +to be committed must be explicitly identified using one of the following\n> +methods:\n>  \n> -Several environment variable are used during commits.  They are\n> -documented in gitlink:git-commit-tree[1].\n> +1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n> +   next commit before using the 'commit' command (Note: even modified\n> +   files must be \"added\");\n>  \n> +2. by using gitlink:git-rm[1] to identify content removal for the next\n> +   commit, again before using the 'commit' command;\n> +\n> +3. by directly listing files containing changes to be committed as arguments\n> +   to the 'commit' command, in which cases only those files alone will be\n> +   considered for the commit;\n> +\n> +4. by using the -a switch with the 'commit' command to automatically \"add\"\n> +   changes from all known files i.e. files that have already been committed\n> +   before, and perform the actual commit.\n> +\n> +Note that the contents of the paths that resolved cleanly by a\n> +conflicted merge are automatically staged for the next commit;\n> +you still need to explicitly identify what you want in the\n> +resulting commit using one of the above methods before\n> +recording the merge commit.\n\nLike I said in another mail, I really think this formal paragraph \nbelongs elsewhere. But if you insist for keeping it here, at least it \nshould be moved after mention of git-reset below.  But IMHO the merge \nexample included further down should be sufficient information wrt \ncommitting a merge.\n\n> +\n> +The gitlink:git-status[1] command can be used to obtain a\n> +summary of what is included by any of the above for the next\n> +commit by giving the same set of parameters you would give to\n> +this command.\n> +\n> +If you make a commit and then found a mistake immediately after\n> +that, you can recover from it with gitlink:git-reset[1].\n>  \n> -This command can run `commit-msg`, `pre-commit`, and\n> -`post-commit` hooks.  See link:hooks.html[hooks] for more\n> -information.\n>  \n>  OPTIONS\n>  -------\n>  -a|--all::\n> -\tUpdate all paths in the index file.  This flag notices\n> -\tfiles that have been modified and deleted, but new files\n> -\tyou have not told git about are not affected.\n> +\tTell the command to automatically stage files that have\n> +\tbeen modified and deleted, but new files you have not\n> +\ttold git about are not affected.\n>  \n>  -c or -C <commit>::\n>  \tTake existing commit object, and reuse the log message\n> @@ -55,16 +77,13 @@ OPTIONS\n>  -s|--signoff::\n>  \tAdd Signed-off-by line at the end of the commit message.\n>  \n> --v|--verify::\n> -\tLook for suspicious lines the commit introduces, and\n> -\tabort committing if there is one.  The definition of\n> -\t'suspicious lines' is currently the lines that has\n> -\ttrailing whitespaces, and the lines whose indentation\n> -\thas a SP character immediately followed by a TAB\n> -\tcharacter.  This is the default.\n> -\n> --n|--no-verify::\n> -\tThe opposite of `--verify`.\n> +--no-verify::\n> +\tBy default, the command looks for suspicious lines the\n> +\tcommit introduces, and aborts committing if there is one.\n> +\tThe definition of 'suspicious lines' is currently the\n> +\tlines that has trailing whitespaces, and the lines whose\n> +\tindentation has a SP character immediately followed by a\n> +\tTAB character.  This option turns off the check.\n>  \n>  -e|--edit::\n>  \tThe message taken from file with `-F`, command line with\n> @@ -95,16 +114,16 @@ but can be used to amend a merge commit.\n>  --\n>  \n>  -i|--include::\n> -\tInstead of committing only the files specified on the\n> -\tcommand line, update them in the index file and then\n> -\tcommit the whole index.  This is the traditional\n> -\tbehavior.\n> +\tBefore making a commit out of staged contents so far,\n> +\tstage the contents of paths given on the command line\n> +\tas well.  This is usually not what you want unless you\n> +\tare concluding a conflicted merge.\n>  \n>  -o|--only::\n> -\tCommit only the files specified on the command line.\n> -\tThis format cannot be used during a merge, nor when the\n> -\tindex and the latest commit does not match on the\n> -\tspecified paths to avoid confusion.\n> +\tCommit only the files specified on the command line;\n> +\tthis is the default when pathnames are given on the\n> +\tcommand line, so you usually do not have to give this\n> +\toption.  This format cannot be used during a merge.\n\nIs there some value in keeping this option documented?  What about \nremoving it (the documentation not the option)?\n\n>  \\--::\n>  \tDo not interpret any more arguments as options.\n> @@ -114,50 +133,112 @@ but can be used to amend a merge commit.\n>  \tdifferent between `--include` and `--only`.  Without\n>  \teither, it defaults `--only` semantics.\n>  \n> -If you make a commit and then found a mistake immediately after\n> -that, you can recover from it with gitlink:git-reset[1].\n> -\n> -\n> -Discussion\n> -----------\n> -\n> -`git commit` without _any_ parameter commits the tree structure\n> -recorded by the current index file.  This is a whole-tree commit\n> -even the command is invoked from a subdirectory.\n> -\n> -`git commit --include paths...` is equivalent to\n> -\n> -\tgit update-index --remove paths...\n> -\tgit commit\n> -\n> -That is, update the specified paths to the index and then commit\n> -the whole tree.\n> -\n> -`git commit paths...` largely bypasses the index file and\n> -commits only the changes made to the specified paths.  It has\n> -however several safety valves to prevent confusion.\n> -\n> -. It refuses to run during a merge (i.e. when\n> -  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users\n> -  that the traditional semantics now needs -i flag.\n> -\n> -. It refuses to run if named `paths...` are different in HEAD\n> -  and the index (ditto about reminding).  Added paths are OK.\n> -  This is because an earlier `git diff` (not `git diff HEAD`)\n> -  would have shown the differences since the last `git\n> -  update-index paths...` to the user, and an inexperienced user\n> -  may mistakenly think that the changes between the index and\n> -  the HEAD (i.e. earlier changes made before the last `git\n> -  update-index paths...` was done) are not being committed.\n> -\n> -. It reads HEAD commit into a temporary index file, updates the\n> -  specified `paths...` and makes a commit.  At the same time,\n> -  the real index file is also updated with the same `paths...`.\n> -\n> -`git commit --all` updates the index file with _all_ changes to\n> -the working tree, and makes a whole-tree commit, regardless of\n> -which subdirectory the command is invoked in.\n>  \n> +EXAMPLES\n> +--------\n> +When recording your own work, the contents of modified files in\n> +your working tree are temporarily stored to a staging area\n> +called the \"index\" with gitlink:git-add[1].  Removal\n\nI like the way the index is introduced at this point.\n\n> +of a file is staged with gitlink:git-rm[1].  After building the\n> +state to be committed incrementally with these commands, `git\n> +commit` (without any pathname parameter) is used to record what\n> +has been staged so far.  This is the most basic form of the\n> +command.  An example:\n> +\n> +------------\n> +$ edit hello.c\n> +$ git rm goodbye.c\n> +$ git add hello.c\n> +$ git commit\n> +------------\n> +\n> +////////////\n> +We should fix 'git rm' to remove goodbye.c from both index and\n> +working tree for the above example.\n> +////////////\n> +\n> +Instead of staging files after each individual change, you can\n> +tell `git commit` to notice the changes to the tracked files in\n> +your working tree and do corresponding `git add` and `git rm`\n> +for you.  That is, this example does the same as the earlier\n> +example if there is no other change in your working tree:\n> +\n> +------------\n> +$ edit hello.c\n> +$ rm goodbye.c\n> +$ git commit -a\n> +------------\n> +\n> +The command `git commit -a` first looks at your working tree,\n> +notices that you have modified hello.c and removed goodbye.c,\n> +and performs necessary `git add` and `git rm` for you.\n> +\n> +After staging changes to many files, you can alter the order the\n> +changes are recorded in, by giving pathnames to `git commit`.\n> +When pathnames are given, the command makes a commit that\n> +only records the changes made to the named paths:\n> +\n> +------------\n> +$ edit hello.c hello.h\n> +$ git add hello.c hello.h\n> +$ edit Makefile\n> +$ git commit Makefile\n> +------------\n> +\n> +This makes a commit that records the modification to `Makefile`.\n> +The changes staged for `hello.c` and `hello.h` are not included\n> +in the resulting commit.  However, their changes are not lost --\n> +they are still staged and merely held back.  After the above\n> +sequence, if you do:\n> +\n> +------------\n> +$ git commit\n> +------------\n> +\n> +this second commit would record the changes to `hello.c` and\n> +`hello.h` as expected.\n> +\n> +After a merge (initiated by either gitlink:git-merge[1] or\n> +gitlink:git-pull[1]) stops because of conflicts, cleanly merged\n> +paths are already staged to be committed for you, and paths that\n> +conflicted are left in unmerged state.  You would have to first\n> +check which paths are conflicting with gitlink:git-status[1]\n> +and after fixing them manually in your working tree, you would\n> +stage the result as usual with gitlink:git-add[1]:\n> +\n> +------------\n> +$ git status | grep unmerged\n> +unmerged: hello.c\n> +$ edit hello.c\n> +$ git add hello.c\n> +------------\n> +\n> +After resolving conflicts and staging the result, `git ls-files -u`\n> +would stop mentioning the conflicted path.  When you are done,\n> +run `git commit` to finally record the merge:\n> +\n> +------------\n> +$ git commit\n> +------------\n> +\n> +As with the case to record your own changes, you can use `-a`\n> +option to save typing.  One difference is that during a merge\n> +resolution, you cannot use `git commit` with pathnames to\n> +alter the order the changes are committed, because the merge\n> +should be recorded as a single commit.  In fact, the command\n> +refuses to run when given pathnames (but see `-i` option).\n> +\n> +\n> +ENVIRONMENT VARIABLES\n> +---------------------\n> +The command specified by either the VISUAL or EDITOR environment\n> +variables is used to edit the commit log message.\n> +\n> +HOOKS\n> +-----\n> +This command can run `commit-msg`, `pre-commit`, and\n> +`post-commit` hooks.  See link:hooks.html[hooks] for more\n> +information.\n\nI'd add (with links):\n\nSEE ALSO\n--------\ngit-add, git-rm, git-mv, git-merge, git-commit-tree\n\nOtherwise very good.\n\n\n"},{"id":"294094","messageId":"7vpsas91e5.fsf@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612091517010.2630@xanadu.home","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-09T21:59:14Z","receivedAt":"2006-12-09T21:59:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre <nico@cam.org> writes:\n\n>> +Note that the contents of the paths that resolved cleanly by a\n>> +conflicted merge are automatically staged for the next commit;\n>> +you still need to explicitly identify what you want in the\n>> +resulting commit using one of the above methods before\n>> +recording the merge commit.\n>\n> Like I said in another mail,...IMHO the merge \n> example included further down should be sufficient information wrt \n> committing a merge.\n\nYou are right --- removed.\n\n>>  -o|--only::\n>> -\tCommit only the files specified on the command line.\n>> -\tThis format cannot be used during a merge, nor when the\n>> -\tindex and the latest commit does not match on the\n>> -\tspecified paths to avoid confusion.\n>> +\tCommit only the files specified on the command line;\n>> +\tthis is the default when pathnames are given on the\n>> +\tcommand line, so you usually do not have to give this\n>> +\toption.  This format cannot be used during a merge.\n>\n> Is there some value in keeping this option documented?  What about \n> removing it (the documentation not the option)?\n\nTrue, although the description of <files>... need to be\nclarified if we do this.\n\n>> +When recording your own work, the contents of modified files in\n>> +your working tree are temporarily stored to a staging area\n>> +called the \"index\" with gitlink:git-add[1].  Removal\n>\n> I like the way the index is introduced at this point.\n\nCredit owed to JBF.\n\n> I'd add (with links):\n>\n> SEE ALSO\n> --------\n> git-add, git-rm, git-mv, git-merge, git-commit-tree\n\nDone.\n\nAttached is an incremental patch on top of what you commented\non.\n\n-- >8 --\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 8fe42cb..20a2cb3 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -34,12 +34,6 @@ methods:\n    changes from all known files i.e. files that have already been committed\n    before, and perform the actual commit.\n \n-Note that the contents of the paths that resolved cleanly by a\n-conflicted merge are automatically staged for the next commit;\n-you still need to explicitly identify what you want in the\n-resulting commit using one of the above methods before\n-recording the merge commit.\n-\n The gitlink:git-status[1] command can be used to obtain a\n summary of what is included by any of the above for the next\n commit by giving the same set of parameters you would give to\n@@ -119,19 +113,15 @@ but can be used to amend a merge commit.\n \tas well.  This is usually not what you want unless you\n \tare concluding a conflicted merge.\n \n--o|--only::\n-\tCommit only the files specified on the command line;\n-\tthis is the default when pathnames are given on the\n-\tcommand line, so you usually do not have to give this\n-\toption.  This format cannot be used during a merge.\n-\n \\--::\n \tDo not interpret any more arguments as options.\n \n <file>...::\n-\tFiles to be committed.  The meaning of these is\n-\tdifferent between `--include` and `--only`.  Without\n-\teither, it defaults `--only` semantics.\n+\tWhen files are given on the command line, the command\n+\tcommits the contents of the named files, without\n+\trecording the changes already staged.  The contents of\n+\tthese files are also staged for the next commit on top\n+\tof what have been staged before.\n \n \n EXAMPLES\n@@ -240,6 +230,15 @@ This command can run `commit-msg`, `pre-commit`, and\n `post-commit` hooks.  See link:hooks.html[hooks] for more\n information.\n \n+\n+SEE ALSO\n+--------\n+gitlink:git-add[1],\n+gitlink:git-rm[1],\n+gitlink:git-mv[1],\n+gitlink:git-merge[1],\n+gitlink:git-commit-tree[1]\n+\n Author\n ------\n Written by Linus Torvalds <torvalds@osdl.org> and\n"},{"id":"294924","messageId":"elfbq4$tka$1@sea.gmane.org","threadId":"43234","inReplyTo":"7vpsas91e5.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-12-09T22:05:04Z","receivedAt":"2006-12-09T22:05:04Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano wrote:\n\n> Nicolas Pitre <nico@cam.org> writes:\n\n>>>  -o|--only::\n>>> -   Commit only the files specified on the command line.\n>>> -   This format cannot be used during a merge, nor when the\n>>> -   index and the latest commit does not match on the\n>>> -   specified paths to avoid confusion.\n>>> +   Commit only the files specified on the command line;\n>>> +   this is the default when pathnames are given on the\n>>> +   command line, so you usually do not have to give this\n>>> +   option.  This format cannot be used during a merge.\n>>\n>> Is there some value in keeping this option documented?  What about \n>> removing it (the documentation not the option)?\n> \n> True, although the description of <files>... need to be\n> clarified if we do this.\n\nI'm a bit uncomfortable about removing documentation to existing\n(if no-op) option. I'd rather it stay.\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"},{"id":"294864","messageId":"Pine.LNX.4.64.0612091418410.12895@woody.osdl.org","threadId":"43234","inReplyTo":"elfbq4$tka$1@sea.gmane.org","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2006-12-09T22:19:21Z","receivedAt":"2006-12-09T22:19:21Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 9 Dec 2006, Jakub Narebski wrote:\n> \n> I'm a bit uncomfortable about removing documentation to existing\n> (if no-op) option. I'd rather it stay.\n\nHow about mentioning it at the very end, under a \"HYSTERICAL RAISINS\" \nheader. That way it's documented, and people still know to ignore it.\n\n"},{"id":"295869","messageId":"200612092324.11057.jnareb@gmail.com","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612091418410.12895@woody.osdl.org","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-12-09T22:24:10Z","receivedAt":"2006-12-09T22:24:10Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Linus Torvalds wrote:\n> \n> On Sat, 9 Dec 2006, Jakub Narebski wrote:\n>> \n>> I'm a bit uncomfortable about removing documentation to existing\n>> (if no-op) option. I'd rather it stay.\n> \n> How about mentioning it at the very end, under a \"HYSTERICAL RAISINS\" \n> header. That way it's documented, and people still know to ignore it.\n\n\"HISTORICAL NOTES\". Yes, that is good idea.\n\nAlthough for git-commit the option --only helps to explain what \n\"git commit <path>...\" does. So perhaps it should stay where it was.\n-- \nJakub Narebski\n"},{"id":"294684","messageId":"Pine.LNX.4.64.0612091718190.2630@xanadu.home","threadId":"43234","inReplyTo":"7vpsas91e5.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-09T22:26:51Z","receivedAt":"2006-12-09T22:26:51Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sat, 9 Dec 2006, Junio C Hamano wrote:\n\n> Attached is an incremental patch on top of what you commented\n> on.\n> \n[...]\n>  <file>...::\n> -\tFiles to be committed.  The meaning of these is\n> -\tdifferent between `--include` and `--only`.  Without\n> -\teither, it defaults `--only` semantics.\n> +\tWhen files are given on the command line, the command\n> +\tcommits the contents of the named files, without\n> +\trecording the changes already staged.  The contents of\n> +\tthese files are also staged for the next commit on top\n> +\tof what have been staged before.\n\nMight something like \"When -i is provided however...\" be missing in the \nabove?  Otherwise it is rather confusing.\n\nBesides that I'm really happy with the result.\n\n\n"},{"id":"296262","messageId":"200612100130.48812.Josef.Weidendorfer@gmx.de","threadId":"43234","inReplyTo":"7vd56tei20.fsf_-_@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Josef Weidendorfer","fromEmail":"josef.weidendorfer@gmx.de","sentAt":"2006-12-10T00:30:47Z","receivedAt":"2006-12-10T00:30:47Z","isPatch":true,"sender":{"key":"josef.weidendorfer@gmx.de","avatar":null},"body":"Very nice.\n\nOn Saturday 09 December 2006 06:48, Junio C Hamano wrote:\n>  DESCRIPTION\n>  -----------\n> -Updates the index file for given paths, or all modified files if\n> -'-a' is specified, and makes a commit object.  The command specified\n> -by either the VISUAL or EDITOR environment variables are used to edit\n> -the commit log message.\n> +Use 'git commit' when you want to record your changes into the repository\n> +along with a log message describing what the commit is about. All changes\n> +to be committed must be explicitly identified using one of the following\n\nWhat about: \"... must be explicitly identified (that is,\nmust be \"staged\") ...\"\n\nThis way, it will be clear for the reader that \"to explicitly identify\" is the\nsame thing as \"to stage\", which is used quite often later.\n\n> +methods:\n>  \n> -Several environment variable are used during commits.  They are\n> -documented in gitlink:git-commit-tree[1].\n> +1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n> +   next commit before using the 'commit' command (Note: even modified\n> +   files must be \"added\");\n\nRegarding this note: Of course unmodified files do not have to be added ;-)\n\nWhat about: \"(Note: changes in files already known to git, and even new\nchanges done after a previous `git add` for a given file, still must\nbe staged again)\" \n\n"},{"id":"294881","messageId":"Pine.LNX.4.64.0612091941230.2630@xanadu.home","threadId":"43234","inReplyTo":"200612100130.48812.Josef.Weidendorfer@gmx.de","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-10T00:51:09Z","receivedAt":"2006-12-10T00:51:09Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sun, 10 Dec 2006, Josef Weidendorfer wrote:\n\n> Very nice.\n> \n> On Saturday 09 December 2006 06:48, Junio C Hamano wrote:\n> >  DESCRIPTION\n> >  -----------\n> > -Updates the index file for given paths, or all modified files if\n> > -'-a' is specified, and makes a commit object.  The command specified\n> > -by either the VISUAL or EDITOR environment variables are used to edit\n> > -the commit log message.\n> > +Use 'git commit' when you want to record your changes into the repository\n> > +along with a log message describing what the commit is about. All changes\n> > +to be committed must be explicitly identified using one of the following\n> \n> What about: \"... must be explicitly identified (that is,\n> must be \"staged\") ...\"\n> \n> This way, it will be clear for the reader that \"to explicitly identify\" is the\n> same thing as \"to stage\", which is used quite often later.\n\nHmmm, maybe, maybe not.  Although I don't have particular problem with \n\"staging area\", I'm still unconvinced about the verb \"stage\".\n\n> > +methods:\n> >  \n> > -Several environment variable are used during commits.  They are\n> > -documented in gitlink:git-commit-tree[1].\n> > +1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n> > +   next commit before using the 'commit' command (Note: even modified\n> > +   files must be \"added\");\n> \n> Regarding this note: Of course unmodified files do not have to be added ;-)\n> \n> What about: \"(Note: changes in files already known to git, and even new\n> changes done after a previous `git add` for a given file, still must\n> be staged again)\" \n\nThis is getting too long for what it is worth in this case IMHO.\n\n\n"},{"id":"296715","messageId":"200612100917.29967.alan@chandlerfamily.org.uk","threadId":"43234","inReplyTo":"7vd56tei20.fsf_-_@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Alan Chandler","fromEmail":"alan@chandlerfamily.org.uk","sentAt":"2006-12-10T09:17:29Z","receivedAt":"2006-12-10T09:17:29Z","isPatch":true,"sender":{"key":"alan@chandlerfamily.org.uk","avatar":"https://gravatar.com/avatar/1862247e5ea8eac114c842f9dc3a5db6253754e24ef7171757cf97eedce48b8c?d=mp&s=160"},"body":"On Saturday 09 December 2006 05:48, Junio C Hamano wrote:\n\n>  OPTIONS\n>  -------\n>  -a|--all::\n> -\tUpdate all paths in the index file.  This flag notices\n> -\tfiles that have been modified and deleted, but new files\n> -\tyou have not told git about are not affected.\n> +\tTell the command to automatically stage files that have\n> +\tbeen modified and deleted, but new files you have not\n> +\ttold git about are not affected.\n\nThe \"but\" in this sentence doesn't seem right to me, I would either \nuse \"although\", or slightly better (IMHO) make it two sentences\n\nTell the command to automatically stage files that have been modified \nand deleted.  Note that files that you have not told git about are not \nincluded with this option.\n\n-- \nAlan Chandler\n"},{"id":"297414","messageId":"20061210210057.GB23387@fieldses.org","threadId":"43234","inReplyTo":"200612100130.48812.Josef.Weidendorfer@gmx.de","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-12-10T21:00:57Z","receivedAt":"2006-12-10T21:00:57Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Dec 10, 2006 at 01:30:47AM +0100, Josef Weidendorfer wrote:\n> On Saturday 09 December 2006 06:48, Junio C Hamano wrote:\n> > +1. by using gitlink:git-add[1] to incrementally \"add\" changes to the\n> > +   next commit before using the 'commit' command (Note: even modified\n> > +   files must be \"added\");\n> \n> Regarding this note: Of course unmodified files do not have to be added ;-)\n> \n> What about: \"(Note: changes in files already known to git, and even new\n> changes done after a previous `git add` for a given file, still must\n> be staged again)\" \n\nOr maybe: \"by using gitlink:git-add[1] to add new content (of either new\nor newly modified files) to the next commit.\"\n\nMan pages are reference documentation, so I figure it's OK to sacrifice\na little newbie-friendliness for accuracy and concision.\n\nI dunno, I think basically the right content is there and Junio should\njust commit it (after the git-rm change?), and then allow the rest of us\nnitpickers to submit patches against the result to our heart's\ncontent....\n\n"},{"id":"295540","messageId":"Pine.LNX.4.64.0612101704390.2630@xanadu.home","threadId":"43234","inReplyTo":"20061210210057.GB23387@fieldses.org","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-10T22:07:40Z","receivedAt":"2006-12-10T22:07:40Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sun, 10 Dec 2006, J. Bruce Fields wrote:\n\n> Or maybe: \"by using gitlink:git-add[1] to add new content (of either new\n> or newly modified files) to the next commit.\"\n> \n> Man pages are reference documentation, so I figure it's OK to sacrifice\n> a little newbie-friendliness for accuracy and concision.\n\nI disagree.  Clarity should be the first goal.  And the fact that even \nmodified files have to be specified is something worth enphasizing, \nespecially since this is not something other systems do.\n\n\n"},{"id":"297161","messageId":"20061210224145.GA3748@fieldses.org","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612101704390.2630@xanadu.home","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-12-10T22:41:45Z","receivedAt":"2006-12-10T22:41:45Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Dec 10, 2006 at 05:07:40PM -0500, Nicolas Pitre wrote:\n> On Sun, 10 Dec 2006, J. Bruce Fields wrote:\n> \n> > Or maybe: \"by using gitlink:git-add[1] to add new content (of either new\n> > or newly modified files) to the next commit.\"\n> > \n> > Man pages are reference documentation, so I figure it's OK to sacrifice\n> > a little newbie-friendliness for accuracy and concision.\n> \n> I disagree.  Clarity should be the first goal.  And the fact that even \n> modified files have to be specified is something worth enphasizing, \n> especially since this is not something other systems do.\n\nOK, OK.  Shortest I can manage then is:\n\n\tby using gitlink:git-add[1] to add new or modified files to the\n\tnext commit.  This adds a file's current contents only; run\n\tgitlink:git-add[1] again to include any subsequent changes.\n\nwhich may not be any improvement.\n\n"},{"id":"296895","messageId":"7vfybn2vyw.fsf@assigned-by-dhcp.cox.net","threadId":"43234","inReplyTo":"Pine.LNX.4.64.0612101704390.2630@xanadu.home","subject":"Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-10T23:05:11Z","receivedAt":"2006-12-10T23:05:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre <nico@cam.org> writes:\n\n>> Man pages are reference documentation, so I figure it's OK to sacrifice\n>> a little newbie-friendliness for accuracy and concision.\n>\n> I disagree.  Clarity should be the first goal.  And the fact that even \n> modified files have to be specified is something worth enphasizing, \n> especially since this is not something other systems do.\n\nLet's keep plumbing documentation technical reference material,\nbut allow more newbie friendliness in Porcelain-ish\ndocumentation.\n"}]}