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

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

[Matthieu Moy]

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.
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message
-- 
1.5.1.3

[PATCH] Document git add -u introduced earlier.

[Matthieu Moy]

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(-)

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

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

[Matthieu Moy]

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-update-index.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

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

[PATCH] Document "commit --only".

[Matthieu Moy]

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(-)

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

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

[Nicolas Pitre]

On Sun, 6 May 2007, Matthieu Moy wrote:

> 
> 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

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

[Nicolas Pitre]

On Sun, 6 May 2007, Matthieu Moy wrote:

> 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

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

[Matthieu Moy]

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).

-- 
Matthieu

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

[Matthieu Moy]

Nicolas Pitre <nico@cam.org> writes:

>> --- 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

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

[Matthieu Moy]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> 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(-)

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

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

[Johannes Schindelin]

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:

> 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