threads / patch / 8006

patchDocument git add -u introduced earlier.

Subject: [PATCH] Document git add -u introduced earlier.

## tl;dr

10 messages between May 6, 2007 and May 7, 2007. Diffs are folded; open one to read it.

replies: 9people: 3as markdown or json

Matthieu Moy· May 6, 2007, 21:11 UTC · lore

[PATCH] Document the fact that commit -a is the way to go for simple operations

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-commit.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)
Show changes to Documentation/git-commit.txt +2 −1
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 2895225..d024c03 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -54,7 +54,8 @@ OPTIONS
 -a|--all::
 	Tell the command to automatically stage files that have
 	been modified and deleted, but new files you have not
-	told git about are not affected.
+	told git about are not affected.  You should use it for most
+        trivial operations.
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message

-- 
1.5.1.3
Matthieu Moy· May 6, 2007, 21:11 UTC · re: Matthieu Moy · lore

This command was implemented, but not documented in dfdac5d9b877641d3aad8ec49f64c2730a3487e3.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-add.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)
Show changes to Documentation/git-add.txt +5 −1
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 755d718..ea27018 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -7,7 +7,7 @@ git-add - Add file contents to the changeset to be committed next
 
 SYNOPSIS
 --------
-'git-add' [-n] [-v] [-f] [--interactive | -i] [--] <file>...
+'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
 
 DESCRIPTION
 -----------
@@ -56,6 +56,10 @@ OPTIONS
 	Add modified contents in the working tree interactively to
 	the index.
 
+-u::
+	Update all files that git already knows about. This is what
+	"git commit -a" does in preparation for making a commit.
+
 \--::
 	This option can be used to separate command-line options from
 	the list of files, (useful when filenames might be mistaken

-- 
1.5.1.3
Matthieu Moy· May 6, 2007, 21:11 UTC · re: Matthieu Moy · lore

[PATCH] Added a reference to git-add in the documentation for git-update-index

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-update-index.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)
Show changes to Documentation/git-update-index.txt +5 −1
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index cd5e014..6cfbd9a 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -27,6 +27,9 @@ Modifies the index or directory cache. Each file mentioned is updated
 into the index and any 'unmerged' or 'needs updating' state is
 cleared.
 
+See also gitlink:git-add[1] for a more user-friendly way to do some of
+the most common operations on the index.
+
 The way "git-update-index" handles files it is told about can be modified
 using the various options:
 
@@ -306,7 +309,8 @@ The command looks at `core.ignorestat` configuration variable.  See
 
 See Also
 --------
-gitlink:git-config[1]
+gitlink:git-config[1],
+gitlink:git-add[1]
 
 
 Author

-- 
1.5.1.3
Matthieu Moy· May 6, 2007, 21:11 UTC · re: Matthieu Moy · lore

[PATCH] Document "commit --only".

The documentation was there earlier, but removed by 4170a19587280eeb3663a47a6fd993910de78076.

That option being the default now, it could perhaps be actually removed, but since it is there, and mentionned in the SYNOPSIS, it should be actually documented.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-commit.txt |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)
Show changes to Documentation/git-commit.txt +5 −0
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index d024c03..0bdf794 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -116,6 +116,11 @@ but can be used to amend a merge commit.
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
+-o|--only::
+	Commit only the files specified on the command line.
+	This format cannot be used during a merge. This is the
+	default.
+
 -q|--quiet::
 	Suppress commit summary message.
 

-- 
1.5.1.3
Nicolas Pitre· May 6, 2007, 23:13 UTC · re: Matthieu Moy · lore

Re: [PATCH] Document "commit --only".

On Sun, 6 May 2007, Matthieu Moy wrote:
Show 6 quoted lines
> The documentation was there earlier, but removed by
> 4170a19587280eeb3663a47a6fd993910de78076.
> 
> That option being the default now, it could perhaps be actually
> removed, but since it is there, and mentionned in the SYNOPSIS, it
> should be actually documented.
I don't think this is a good idea either.
> +-o|--only::
> +	Commit only the files specified on the command line.
> +	This format cannot be used during a merge. This is the
> +	default.

This looks really confusing. This is the default _only_ if files are specified on the command line.

IMHO I'd rather remove the option from the synopsis and flag it as scheduled for removal in the source instead.

Nicolas
Matthieu Moy· May 7, 2007, 08:16 UTC · re: Nicolas Pitre · lore

Re: [PATCH] Document "commit --only".

Nicolas Pitre <nico@cam.org> writes:
Show 5 quoted lines
> This looks really confusing.  This is the default _only_ if files are 
> specified on the command line.
>
> IMHO I'd rather remove the option from the synopsis and flag it as 
> scheduled for removal in the source instead.

I'm fine with this proposal. Next email will be a patch to do that (I'm not sure about the standard way to deprecate things in git, so I just added a warning when -o is used, feel free to improve it).

-- 
Matthieu
Matthieu Moy· May 7, 2007, 10:37 UTC · re: Matthieu Moy · lore

Re: [PATCH] Document "commit --only".

Matthieu Moy <Matthieu.Moy@imag.fr> writes:
Show 11 quoted lines
> Nicolas Pitre <nico@cam.org> writes:
>
>> This looks really confusing.  This is the default _only_ if files are 
>> specified on the command line.
>>
>> IMHO I'd rather remove the option from the synopsis and flag it as 
>> scheduled for removal in the source instead.
>
> I'm fine with this proposal. Next email will be a patch to do that
> (I'm not sure about the standard way to deprecate things in git, so I
> just added a warning when -o is used, feel free to improve it).

I messed up threading, sorry. Here's the patch again, but it's already in a separate thead.

[PATCH] Remove mention of -o|--only in SYNOPSYS of git-commit.

This flag is actually useless since it is the default behavior, and was mentionned in the SYNOPSYS, but not actually documented. Better just deprecate it.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-commit.txt |    4 ++--
 git-commit.sh                |    4 +++-
 2 files changed, 5 insertions(+), 3 deletions(-)
Show changes to 2 files +5 −3

Documentation/git-commit.txt, git-commit.sh

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 53a7bb0..4324ca0 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 'git-commit' [-a | --interactive] [-s] [-v]
 	   [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]
 	   [--no-verify] [-e] [--author <author>]
-	   [--] [[-i | -o ]<file>...]
+	   [--] [[-i] <files>...]
 
 DESCRIPTION
 -----------
@@ -91,7 +91,7 @@ OPTIONS
 
 	Used to amend the tip of the current branch. Prepare the tree
 	object you would want to replace the latest commit as usual
-	(this includes the usual -i/-o and explicit paths), and the
+	(this includes the usual -i and explicit paths), and the
 	commit log editor is seeded with the commit message from the
 	tip of the current branch. The commit you create replaces the
 	current tip -- if it was a merge, it will have the parents of
diff --git a/git-commit.sh b/git-commit.sh
index f28fc24..3913097 100755
--- a/git-commit.sh
+++ b/git-commit.sh
@@ -3,7 +3,7 @@
 # Copyright (c) 2005 Linus Torvalds
 # Copyright (c) 2006 Junio C Hamano
 
-USAGE='[-a | --interactive] [-s] [-v] [--no-verify] [-m <message> | -F <logfile> | (-C|-c) <commit> | --amend] [-u] [-e] [--author <author>] [[-i | -o] <path>...]'
+USAGE='[-a | --interactive] [-s] [-v] [--no-verify] [-m <message> | -F <logfile> | (-C|-c) <commit> | --amend] [-u] [-e] [--author <author>] [[-i] <path>...]'
 SUBDIRECTORY_OK=Yes
 . git-sh-setup
 require_work_tree
@@ -138,6 +138,8 @@ do
 		shift
 		;;
 	-o|--o|--on|--onl|--only)
+                echo >&2 "Warning: --only option is now the default."
+                echo >&2 "It will be removed in a future version of git."
 		only=t
 		shift
 		;;

-- 
1.5.1.1
Nicolas Pitre· May 6, 2007, 23:07 UTC · re: Matthieu Moy · lore

Re: [PATCH] Document the fact that commit -a is the way to go for simple operations

On Sun, 6 May 2007, Matthieu Moy wrote:
Show 17 quoted lines
> 
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/git-commit.txt |    3 ++-
>  1 files changed, 2 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 2895225..d024c03 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -54,7 +54,8 @@ OPTIONS
>  -a|--all::
>  	Tell the command to automatically stage files that have
>  	been modified and deleted, but new files you have not
> -	told git about are not affected.
> +	told git about are not affected.  You should use it for most
> +        trivial operations.

I don't think this patch is worth it. If anything it might create more confusion.

There are many ways to commit without -a which still could be considered amongst "most trivial operations".

Nicolas
Matthieu Moy· May 7, 2007, 08:21 UTC · re: Nicolas Pitre · lore

Re: [PATCH] Document the fact that commit -a is the way to go for simple operations

Nicolas Pitre <nico@cam.org> writes:
Show 15 quoted lines
>> --- a/Documentation/git-commit.txt
>> +++ b/Documentation/git-commit.txt
>> @@ -54,7 +54,8 @@ OPTIONS
>>  -a|--all::
>>  	Tell the command to automatically stage files that have
>>  	been modified and deleted, but new files you have not
>> -	told git about are not affected.
>> +	told git about are not affected.  You should use it for most
>> +        trivial operations.
>
> I don't think this patch is worth it.  If anything it might create more 
> confusion.
>
> There are many ways to commit without -a which still could be considered 
> amongst "most trivial operations".
My proposal is not perfect, and I'm sure we can do better.

But the problem with most of git's manpages for beginners is that the documentation is mostly technical and factual. That is, it tells you what git will do if you provide such or such option, but not _why_ and _when_ you should use it.

Probably just a "gitlink:" to the place in the user manual which talks about the index would be OK here.

-- 
Matthieu
Johannes Schindelin· May 7, 2007, 11:22 UTC · re: Matthieu Moy · lore

Re: [PATCH] Document the fact that commit -a is the way to go for simple operations

Hi,

[BTW Matthieu, it seems you suffer the same problem as Jakub, since you do not Cc the original authors in your replies.]

On Mon, 7 May 2007, Matthieu Moy wrote:
Show 9 quoted lines
> My proposal is not perfect, and I'm sure we can do better.
> 
> But the problem with most of git's manpages for beginners is that the
> documentation is mostly technical and factual. That is, it tells you
> what git will do if you provide such or such option, but not _why_ and
> _when_ you should use it.
> 
> Probably just a "gitlink:" to the place in the user manual which talks
> about the index would be OK here.

NAK. You should not even consider reading the man pages before reading the user manual. If you expect the man pages to give you a proper introduction into _anything_ that is your problem, not the doc's.

We have such a lovely user manual, full of examples, a nice read, and it even contains a section for the impatient. But the man pages are _meant_ to be technical. And I do not see a place in them for a back reference to the user manual.

Ciao, Dscho

← back to recent threads