{"thread":{"id":"8006","subject":"[PATCH] Document git add -u introduced earlier.","startedAt":"2007-05-06T21:11:54Z","lastAt":"2007-05-07T11:22:36Z","messageCount":10,"participants":["Matthieu Moy","Nicolas Pitre","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"41251","messageId":"11784859173386-git-send-email-Matthieu.Moy@imag.fr","threadId":"8006","inReplyTo":null,"subject":"[PATCH] Document the fact that commit -a is the way to go for simple operations","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-06T21:11:54Z","receivedAt":"2007-05-06T21:11:54Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-commit.txt | 3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 2895225..d024c03 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -54,7 +54,8 @@ OPTIONS\n -a|--all::\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+\ttold git about are not affected. You should use it for most\n+ trivial operations.\n \n -c or -C ::\n \tTake existing commit object, and reuse the log message\n-- \n1.5.1.3\n"},{"id":"41250","messageId":"11784859173725-git-send-email-Matthieu.Moy@imag.fr","threadId":"8006","inReplyTo":"11784859173386-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH] Document git add -u introduced earlier.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-06T21:11:55Z","receivedAt":"2007-05-06T21:11:55Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"This command was implemented, but not documented in\ndfdac5d9b877641d3aad8ec49f64c2730a3487e3.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-add.txt | 6 +++++-\n 1 files changed, 5 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 755d718..ea27018 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -7,7 +7,7 @@ git-add - Add file contents to the changeset to be committed next\n \n SYNOPSIS\n --------\n-'git-add' [-n] [-v] [-f] [--interactive | -i] [--] ...\n+'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] ...\n \n DESCRIPTION\n -----------\n@@ -56,6 +56,10 @@ OPTIONS\n \tAdd modified contents in the working tree interactively to\n \tthe index.\n \n+-u::\n+\tUpdate all files that git already knows about. This is what\n+\t\"git commit -a\" does in preparation for making a commit.\n+\n \\--::\n \tThis option can be used to separate command-line options from\n \tthe list of files, (useful when filenames might be mistaken\n-- \n1.5.1.3\n"},{"id":"41253","messageId":"11784859182473-git-send-email-Matthieu.Moy@imag.fr","threadId":"8006","inReplyTo":"11784859173725-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH] Added a reference to git-add in the documentation for git-update-index","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-06T21:11:56Z","receivedAt":"2007-05-06T21:11:56Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-update-index.txt | 6 +++++-\n 1 files changed, 5 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex cd5e014..6cfbd9a 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -27,6 +27,9 @@ Modifies the index or directory cache. Each file mentioned is updated\n into the index and any 'unmerged' or 'needs updating' state is\n cleared.\n \n+See also gitlink:git-add[1] for a more user-friendly way to do some of\n+the most common operations on the index.\n+\n The way \"git-update-index\" handles files it is told about can be modified\n using the various options:\n \n@@ -306,7 +309,8 @@ The command looks at `core.ignorestat` configuration variable. See\n \n See Also\n --------\n-gitlink:git-config[1]\n+gitlink:git-config[1],\n+gitlink:git-add[1]\n \n \n Author\n-- \n1.5.1.3\n"},{"id":"41252","messageId":"11784859184184-git-send-email-Matthieu.Moy@imag.fr","threadId":"8006","inReplyTo":"11784859182473-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH] Document \"commit --only\".","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-06T21:11:57Z","receivedAt":"2007-05-06T21:11:57Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The documentation was there earlier, but removed by\n4170a19587280eeb3663a47a6fd993910de78076.\n\nThat option being the default now, it could perhaps be actually\nremoved, but since it is there, and mentionned in the SYNOPSIS, it\nshould be actually documented.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-commit.txt | 5 +++++\n 1 files changed, 5 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex d024c03..0bdf794 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -116,6 +116,11 @@ 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 format cannot be used during a merge. This is the\n+\tdefault.\n+\n -q|--quiet::\n \tSuppress commit summary message.\n \n-- \n1.5.1.3\n"},{"id":"41268","messageId":"alpine.LFD.0.99.0705061904050.24220@xanadu.home","threadId":"8006","inReplyTo":"11784859173386-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Document the fact that commit -a is the way to go for simple operations","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-05-06T23:07:48Z","receivedAt":"2007-05-06T23:07:48Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sun, 6 May 2007, Matthieu Moy wrote:\n\n> \n> Signed-off-by: Matthieu Moy \n> ---\n> Documentation/git-commit.txt | 3 ++-\n> 1 files changed, 2 insertions(+), 1 deletions(-)\n> \n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 2895225..d024c03 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -54,7 +54,8 @@ OPTIONS\n> -a|--all::\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> +\ttold git about are not affected. You should use it for most\n> + trivial operations.\n\nI don't think this patch is worth it. If anything it might create more \nconfusion.\n\nThere are many ways to commit without -a which still could be considered \namongst \"most trivial operations\".\n\n\nNicolas\n"},{"id":"41271","messageId":"alpine.LFD.0.99.0705061908430.24220@xanadu.home","threadId":"8006","inReplyTo":"11784859184184-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Document \"commit --only\".","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-05-06T23:13:41Z","receivedAt":"2007-05-06T23:13:41Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sun, 6 May 2007, Matthieu Moy wrote:\n\n> The documentation was there earlier, but removed by\n> 4170a19587280eeb3663a47a6fd993910de78076.\n> \n> That option being the default now, it could perhaps be actually\n> removed, but since it is there, and mentionned in the SYNOPSIS, it\n> should be actually documented.\n\nI don't think this is a good idea either.\n\n> +-o|--only::\n> +\tCommit only the files specified on the command line.\n> +\tThis format cannot be used during a merge. This is the\n> +\tdefault.\n\nThis looks really confusing. This is the default _only_ if files are \nspecified on the command line.\n\nIMHO I'd rather remove the option from the synopsis and flag it as \nscheduled for removal in the source instead.\n\n\nNicolas\n"},{"id":"41305","messageId":"vpq8xc1ujzq.fsf@bauges.imag.fr","threadId":"8006","inReplyTo":"alpine.LFD.0.99.0705061908430.24220@xanadu.home","subject":"Re: [PATCH] Document \"commit --only\".","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-07T08:16:09Z","receivedAt":"2007-05-07T08:16:09Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Nicolas Pitre writes:\n\n> This looks really confusing. This is the default _only_ if files are \n> specified on the command line.\n>\n> IMHO I'd rather remove the option from the synopsis and flag it as \n> scheduled for removal in the source instead.\n\nI'm fine with this proposal. Next email will be a patch to do that\n(I'm not sure about the standard way to deprecate things in git, so I\njust added a warning when -o is used, feel free to improve it).\n\n-- \nMatthieu\n"},{"id":"41306","messageId":"vpqy7k1t56i.fsf@bauges.imag.fr","threadId":"8006","inReplyTo":"alpine.LFD.0.99.0705061904050.24220@xanadu.home","subject":"Re: [PATCH] Document the fact that commit -a is the way to go for simple operations","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-07T08:21:25Z","receivedAt":"2007-05-07T08:21:25Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Nicolas Pitre writes:\n\n>> --- a/Documentation/git-commit.txt\n>> +++ b/Documentation/git-commit.txt\n>> @@ -54,7 +54,8 @@ OPTIONS\n>> -a|--all::\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>> +\ttold git about are not affected. You should use it for most\n>> + trivial operations.\n>\n> I don't think this patch is worth it. If anything it might create more \n> confusion.\n>\n> There are many ways to commit without -a which still could be considered \n> amongst \"most trivial operations\".\n\nMy proposal is not perfect, and I'm sure we can do better.\n\nBut the problem with most of git's manpages for beginners is that the\ndocumentation is mostly technical and factual. That is, it tells you\nwhat git will do if you provide such or such option, but not _why_ and\n_when_ you should use it.\n\nProbably just a \"gitlink:\" to the place in the user manual which talks\nabout the index would be OK here.\n\n-- \nMatthieu\n"},{"id":"41315","messageId":"vpqirb4q5q9.fsf@bauges.imag.fr","threadId":"8006","inReplyTo":"vpq8xc1ujzq.fsf@bauges.imag.fr","subject":"Re: [PATCH] Document \"commit --only\".","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2007-05-07T10:37:50Z","receivedAt":"2007-05-07T10:37:50Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Matthieu Moy writes:\n\n> Nicolas Pitre writes:\n>\n>> This looks really confusing. This is the default _only_ if files are \n>> specified on the command line.\n>>\n>> IMHO I'd rather remove the option from the synopsis and flag it as \n>> scheduled for removal in the source instead.\n>\n> I'm fine with this proposal. Next email will be a patch to do that\n> (I'm not sure about the standard way to deprecate things in git, so I\n> just added a warning when -o is used, feel free to improve it).\n\nI messed up threading, sorry. Here's the patch again, but it's already\nin a separate thead.\n\n\n\n[PATCH] Remove mention of -o|--only in SYNOPSYS of git-commit.\n\nThis flag is actually useless since it is the default behavior, and\nwas mentionned in the SYNOPSYS, but not actually documented. Better\njust deprecate it.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-commit.txt | 4 ++--\n git-commit.sh | 4 +++-\n 2 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 53a7bb0..4324ca0 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git-commit' [-a | --interactive] [-s] [-v]\n \t [(-c | -C) | -F | -m | --amend]\n \t [--no-verify] [-e] [--author ]\n-\t [--] [[-i | -o ]...]\n+\t [--] [[-i] ...]\n \n DESCRIPTION\n -----------\n@@ -91,7 +91,7 @@ OPTIONS\n \n \tUsed to amend the tip of the current branch. Prepare the tree\n \tobject you would want to replace the latest commit as usual\n-\t(this includes the usual -i/-o and explicit paths), and the\n+\t(this includes the usual -i and explicit paths), and the\n \tcommit log editor is seeded with the commit message from the\n \ttip of the current branch. The commit you create replaces the\n \tcurrent tip -- if it was a merge, it will have the parents of\ndiff --git a/git-commit.sh b/git-commit.sh\nindex f28fc24..3913097 100755\n--- a/git-commit.sh\n+++ b/git-commit.sh\n@@ -3,7 +3,7 @@\n # Copyright (c) 2005 Linus Torvalds\n # Copyright (c) 2006 Junio C Hamano\n \n-USAGE='[-a | --interactive] [-s] [-v] [--no-verify] [-m | -F | (-C|-c) | --amend] [-u] [-e] [--author ] [[-i | -o] ...]'\n+USAGE='[-a | --interactive] [-s] [-v] [--no-verify] [-m | -F | (-C|-c) | --amend] [-u] [-e] [--author ] [[-i] ...]'\n SUBDIRECTORY_OK=Yes\n . git-sh-setup\n require_work_tree\n@@ -138,6 +138,8 @@ do\n \t\tshift\n \t\t;;\n \t-o|--o|--on|--onl|--only)\n+ echo >&2 \"Warning: --only option is now the default.\"\n+ echo >&2 \"It will be removed in a future version of git.\"\n \t\tonly=t\n \t\tshift\n \t\t;;\n-- \n1.5.1.1\n"},{"id":"41322","messageId":"Pine.LNX.4.64.0705071317580.4167@racer.site","threadId":"8006","inReplyTo":"vpqy7k1t56i.fsf@bauges.imag.fr","subject":"Re: [PATCH] Document the fact that commit -a is the way to go for simple operations","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-05-07T11:22:36Z","receivedAt":"2007-05-07T11:22:36Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\n[BTW Matthieu, it seems you suffer the same problem as Jakub, since you do \nnot Cc the original authors in your replies.]\n\nOn Mon, 7 May 2007, Matthieu Moy wrote:\n\n> My proposal is not perfect, and I'm sure we can do better.\n> \n> But the problem with most of git's manpages for beginners is that the\n> documentation is mostly technical and factual. That is, it tells you\n> what git will do if you provide such or such option, but not _why_ and\n> _when_ you should use it.\n> \n> Probably just a \"gitlink:\" to the place in the user manual which talks\n> about the index would be OK here.\n\nNAK. You should not even consider reading the man pages before reading the \nuser manual. If you expect the man pages to give you a proper introduction \ninto _anything_ that is your problem, not the doc's.\n\nWe have such a lovely user manual, full of examples, a nice read, and it \neven contains a section for the impatient. But the man pages are _meant_ \nto be technical. And I do not see a place in them for a back reference to \nthe user manual.\n\nCiao,\nDscho\n"}]}