[PATCH] git-add.txt: Order options alphabetically

[PATCH] git-add.txt: Order options alphabetically

[jari.aalto]

From: Jari Aalto <jari.aalto@cante.net>


Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-add.txt |  106 ++++++++++++++++++++++----------------------
 1 files changed, 53 insertions(+), 53 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 54aaaeb..83751c6 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -46,24 +46,26 @@ be used to add ignored files with the `-f` (force) option.
 Please see linkgit:git-commit[1] for alternative ways to add content to a
 commit.
 
-
 OPTIONS
 -------
-<filepattern>...::
-	Files to add content from.  Fileglobs (e.g. `*.c`) can
-	be given to add all matching files.  Also a
-	leading directory name (e.g. `dir` to add `dir/file1`
-	and `dir/file2`) can be given to add all files in the
-	directory, recursively.
 
--n::
---dry-run::
-	Don't actually add the file(s), just show if they exist and/or will
-	be ignored.
+-A::
+--all::
+	Like `-u`, but match <filepattern> against files in the
+	working tree in addition to the index. That means that it
+	will find new files as well as staging modified content and
+	removing files that are no longer in the working tree.
 
--v::
---verbose::
-        Be verbose.
+-e, \--edit::
+	Open the diff vs. the index in an editor and let the user
+	edit it.  After the editor was closed, adjust the hunk headers
+	and apply the patch to the index.
++
+The intent of this option is to pick and choose lines of the patch to
+apply, or even to modify the contents of lines to be staged. This can be
+quicker and more flexible than using the interactive hunk selector.
+However, it is easy to confuse oneself and create a patch that does not
+apply to the index. See EDITING PATCHES below.
 
 -f::
 --force::
@@ -76,6 +78,30 @@ OPTIONS
 	operation to a subset of the working tree. See ``Interactive
 	mode'' for details.
 
+--ignore-errors::
+	If some files could not be added because of errors indexing
+	them, do not abort the operation, but continue adding the
+	others. The command shall still exit with non-zero status.
+
+--ignore-missing::
+	This option can only be used together with --dry-run. By using
+	this option the user can check if any of the given files would
+	be ignored, no matter if they are already present in the work
+	tree or not.
+
+-n::
+--dry-run::
+	Don't actually add the file(s), just show if they exist and/or will
+	be ignored.
+
+-N::
+--intent-to-add::
+	Record only the fact that the path will be added later. An entry
+	for the path is placed in the index with no content. This is
+	useful for, among other things, showing the unstaged content of
+	such files with `git diff` and committing them with `git commit
+	-a`.
+
 -p::
 --patch::
 	Interactively choose hunks of patch between the index and the
@@ -87,16 +113,9 @@ This effectively runs `add --interactive`, but bypasses the
 initial command menu and directly jumps to the `patch` subcommand.
 See ``Interactive mode'' for details.
 
--e, \--edit::
-	Open the diff vs. the index in an editor and let the user
-	edit it.  After the editor was closed, adjust the hunk headers
-	and apply the patch to the index.
-+
-The intent of this option is to pick and choose lines of the patch to
-apply, or even to modify the contents of lines to be staged. This can be
-quicker and more flexible than using the interactive hunk selector.
-However, it is easy to confuse oneself and create a patch that does not
-apply to the index. See EDITING PATCHES below.
+--refresh::
+	Don't add the file(s), but only refresh their stat()
+	information in the index.
 
 -u::
 --update::
@@ -111,41 +130,22 @@ If no <filepattern> is given, default to "."; in other words,
 update all tracked files in the current directory and its
 subdirectories.
 
--A::
---all::
-	Like `-u`, but match <filepattern> against files in the
-	working tree in addition to the index. That means that it
-	will find new files as well as staging modified content and
-	removing files that are no longer in the working tree.
-
--N::
---intent-to-add::
-	Record only the fact that the path will be added later. An entry
-	for the path is placed in the index with no content. This is
-	useful for, among other things, showing the unstaged content of
-	such files with `git diff` and committing them with `git commit
-	-a`.
-
---refresh::
-	Don't add the file(s), but only refresh their stat()
-	information in the index.
-
---ignore-errors::
-	If some files could not be added because of errors indexing
-	them, do not abort the operation, but continue adding the
-	others. The command shall still exit with non-zero status.
-
---ignore-missing::
-	This option can only be used together with --dry-run. By using
-	this option the user can check if any of the given files would
-	be ignored, no matter if they are already present in the work
-	tree or not.
+-v::
+--verbose::
+        Be verbose.
 
 \--::
 	This option can be used to separate command-line options from
 	the list of files, (useful when filenames might be mistaken
 	for command-line options).
 
+<filepattern>...::
+	Files to add content from.  Fileglobs (e.g. `*.c`) can
+	be given to add all matching files.  Also a
+	leading directory name (e.g. `dir` to add `dir/file1`
+	and `dir/file2`) can be given to add all files in the
+	directory, recursively.
+
 
 Configuration
 -------------
-- 
1.7.2.3

Re: [PATCH] git-add.txt: Order options alphabetically

[Drew Northup]

On Wed, 2010-12-01 at 17:42 +0200, jari.aalto@cante.net wrote:
> From: Jari Aalto <jari.aalto@cante.net>
> 
> 
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-add.txt |  106 ++++++++++++++++++++++----------------------
>  1 files changed, 53 insertions(+), 53 deletions(-)
> 
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index 54aaaeb..83751c6 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -46,24 +46,26 @@ be used to add ignored files with the `-f` (force) option.
>  Please see linkgit:git-commit[1] for alternative ways to add content to a
>  commit.
>  
> -
>  OPTIONS
>  -------
> -<filepattern>...::
> -	Files to add content from.  Fileglobs (e.g. `*.c`) can
> -	be given to add all matching files.  Also a
> -	leading directory name (e.g. `dir` to add `dir/file1`
> -	and `dir/file2`) can be given to add all files in the
> -	directory, recursively.
>  
> --n::
> ---dry-run::
> -	Don't actually add the file(s), just show if they exist and/or will
> -	be ignored.
> +-A::
> +--all::
> +	Like `-u`, but match <filepattern> against files in the
> +	working tree in addition to the index. That means that it
> +	will find new files as well as staging modified content and
> +	removing files that are no longer in the working tree.
>  
> --v::
> ---verbose::
> -        Be verbose.
> +-e, \--edit::
> +	Open the diff vs. the index in an editor and let the user
> +	edit it.  After the editor was closed, adjust the hunk headers
> +	and apply the patch to the index.
> ++
> +The intent of this option is to pick and choose lines of the patch to
> +apply, or even to modify the contents of lines to be staged. This can be
> +quicker and more flexible than using the interactive hunk selector.
> +However, it is easy to confuse oneself and create a patch that does not
> +apply to the index. See EDITING PATCHES below.
>  
>  -f::
>  --force::
> @@ -76,6 +78,30 @@ OPTIONS
>  	operation to a subset of the working tree. See ``Interactive
>  	mode'' for details.
>  
> +--ignore-errors::
> +	If some files could not be added because of errors indexing
> +	them, do not abort the operation, but continue adding the
> +	others. The command shall still exit with non-zero status.
> +
> +--ignore-missing::
> +	This option can only be used together with --dry-run. By using
> +	this option the user can check if any of the given files would
> +	be ignored, no matter if they are already present in the work
> +	tree or not.
> +
> +-n::
> +--dry-run::
> +	Don't actually add the file(s), just show if they exist and/or will
> +	be ignored.
> +
> +-N::
> +--intent-to-add::
> +	Record only the fact that the path will be added later. An entry
> +	for the path is placed in the index with no content. This is
> +	useful for, among other things, showing the unstaged content of
> +	such files with `git diff` and committing them with `git commit
> +	-a`.
> +
>  -p::
>  --patch::
>  	Interactively choose hunks of patch between the index and the
> @@ -87,16 +113,9 @@ This effectively runs `add --interactive`, but bypasses the
>  initial command menu and directly jumps to the `patch` subcommand.
>  See ``Interactive mode'' for details.
>  
> --e, \--edit::
> -	Open the diff vs. the index in an editor and let the user
> -	edit it.  After the editor was closed, adjust the hunk headers
> -	and apply the patch to the index.
> -+
> -The intent of this option is to pick and choose lines of the patch to
> -apply, or even to modify the contents of lines to be staged. This can be
> -quicker and more flexible than using the interactive hunk selector.
> -However, it is easy to confuse oneself and create a patch that does not
> -apply to the index. See EDITING PATCHES below.
> +--refresh::
> +	Don't add the file(s), but only refresh their stat()
> +	information in the index.
>  
>  -u::
>  --update::
> @@ -111,41 +130,22 @@ If no <filepattern> is given, default to "."; in other words,
>  update all tracked files in the current directory and its
>  subdirectories.
>  
> --A::
> ---all::
> -	Like `-u`, but match <filepattern> against files in the
> -	working tree in addition to the index. That means that it
> -	will find new files as well as staging modified content and
> -	removing files that are no longer in the working tree.
> -
> --N::
> ---intent-to-add::
> -	Record only the fact that the path will be added later. An entry
> -	for the path is placed in the index with no content. This is
> -	useful for, among other things, showing the unstaged content of
> -	such files with `git diff` and committing them with `git commit
> -	-a`.
> -
> ---refresh::
> -	Don't add the file(s), but only refresh their stat()
> -	information in the index.
> -
> ---ignore-errors::
> -	If some files could not be added because of errors indexing
> -	them, do not abort the operation, but continue adding the
> -	others. The command shall still exit with non-zero status.
> -
> ---ignore-missing::
> -	This option can only be used together with --dry-run. By using
> -	this option the user can check if any of the given files would
> -	be ignored, no matter if they are already present in the work
> -	tree or not.
> +-v::
> +--verbose::
> +        Be verbose.
>  
>  \--::
>  	This option can be used to separate command-line options from
>  	the list of files, (useful when filenames might be mistaken
>  	for command-line options).
>  
> +<filepattern>...::
> +	Files to add content from.  Fileglobs (e.g. `*.c`) can
> +	be given to add all matching files.  Also a
> +	leading directory name (e.g. `dir` to add `dir/file1`
> +	and `dir/file2`) can be given to add all files in the
> +	directory, recursively.
> +
>  
>  Configuration
>  -------------

Jari,
First off, this patch (and set I've seen thus far) has little no commit
message. Second (lacking a commit message to tell me), WHY? Some
projects order options alphabetically and some in the order they are
expected to be most often used. Other documentation writers just specify
the options in the same order they were provided in the synopsis (which
can rarely be successfully alphabetized). Some have no order whatsoever.

So again I ask, why make this change? Did you plan on changing the the
short help displayed by git add -h as well?



-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] git-add.txt: Order options alphabetically

[Jari Aalto]

2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
> On Wed, 2010-12-01 at 17:42 +0200, jari.aalto@cante.net wrote:
> First off, this patch (and set I've seen thus far) has little no commit
> message.

There is no point of making it any longer as it is basically the same
for everything. I don't think we want to see long identical copies of
explanations over and over in "git log".

> Did you plan on changing the the short help displayed by git add -h as
> well?

Don't know. At this time, I happen to have some free time. But that's a
good candidate for followup work.

Jari

Re: [PATCH] git-add.txt: Order options alphabetically

[Jari Aalto]

2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
> (lacking a commit message to tell me), WHY? [alphabetical]

Quoting <http://permalink.gmane.org/gmane.comp.version-control.git/162552>

    - You read from top to bottom, therefore A-Z.
    - GNU project uses it in manual pages. It looks good, it looks
      professional, it looks clean. And it works when searching (= no
      oriantation problems regardless of tools; even when you print on
      paper when you don't have any computerized aids to help your search.).

Jari

Re: [PATCH] git-add.txt: Order options alphabetically

[Drew Northup]

On Wed, 2010-12-01 at 21:29 +0200, Jari Aalto wrote:
> 2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
> > (lacking a commit message to tell me), WHY? [alphabetical]
> 
> Quoting <http://permalink.gmane.org/gmane.comp.version-control.git/162552>
> 
>     - You read from top to bottom, therefore A-Z.
>     - GNU project uses it in manual pages. It looks good, it looks
>       professional, it looks clean. And it works when searching (= no
>       oriantation problems regardless of tools; even when you print on
>       paper when you don't have any computerized aids to help your search.).
> 
> Jari

THAT belongs in a commit message!!!

As an aside, you haven't looked at the sed and gawk manpages, have you?

Alphabetic order fairly often looks nice, but it is not always the right
answer.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] git-add.txt: Order options alphabetically

[Drew Northup]

On Wed, 2010-12-01 at 21:27 +0200, Jari Aalto wrote:
> 2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
> > On Wed, 2010-12-01 at 17:42 +0200, jari.aalto@cante.net wrote:
> > First off, this patch (and set I've seen thus far) has little no commit
> > message.
> 
> There is no point of making it any longer as it is basically the same
> for everything. I don't think we want to see long identical copies of
> explanations over and over in "git log".
> 
> > Did you plan on changing the the short help displayed by git add -h as
> > well?
> 
> Don't know. At this time, I happen to have some free time. But that's a
> good candidate for followup work.
> 
> Jari

First, before I reply to your post proper, I am going to echo others on
this list--unless you see a good specific reason to prune the CC/reply
list please leave it intact and use "reply all" and not "reply to list"
here once a conversation has been started. (Other lists may have
different conventions, and I am still absorbing some of the ones used
here myself...)

That said, like changes should be grouped together in closely related
patchsets. It makes life easier for everybody. Don't worry about using
virtually the same commit message over and over again if that's what is
actually appropriate. Junio may very well rebase/restructure patches
that need it (I haven't checked to see how often he bothers) and will
tell you if patch structure is completely out of line or unusable--but
that's not the same as others actually reviewing the changes themselves.

See 

Message-ID: <20101201165043.GF26120@burratino>

These changes should be a bundle, this bundle should have a "meta
message", and each element should have a commit message.


-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] git-add.txt: Order options alphabetically

[Kevin Ballard]

On Dec 1, 2010, at 11:29 AM, Jari Aalto wrote:

>    - You read from top to bottom, therefore A-Z.

What does that have to do with anything? Very rarely does it make sense to try
to read options in alphabetical format. If the reader is, in fact, reading from
top-to-bottom straight through, they will certainly appreciate having related
options grouped together.

>    - GNU project uses it in manual pages. It looks good, it looks
>      professional, it looks clean. And it works when searching (= no
>      oriantation problems regardless of tools; even when you print on
>      paper when you don't have any computerized aids to help your search.).

"Looks clean" is not a good reason to reduce clarity in the documentation.
Comprehension and ease-of-readability are far more important than visual
aesthetics.

-Kevin Ballard

Re: [PATCH] git-add.txt: Order options alphabetically

[Jari Aalto]

2010-12-01 21:45 Drew Northup <drew.northup@maine.edu>:
> On Wed, 2010-12-01 at 21:29 +0200, Jari Aalto wrote:
>
>> 2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
>> > (lacking a commit message to tell me), WHY? [alphabetical]
>> 
>> Quoting <http://permalink.gmane.org/gmane.comp.version-control.git/162552>
>> 
>>     - You read from top to bottom, therefore A-Z.
>>     - GNU project uses it in manual pages. It looks good, it looks
>>       professional, it looks clean. And it works when searching (= no
>>       oriantation problems regardless of tools; even when you print on
>>       paper when you don't have any computerized aids to help your search.).
>> 
>> Jari
>
> THAT belongs in a commit message!!!

It does not. No need to clutter 10's of message that long in there..

> As an aside, you haven't looked at the sed and gawk manpages, have you?

There are plenty of pages that are bad examples. Let's make ours better.

Jari

Re: [PATCH] git-add.txt: Order options alphabetically

[Jari Aalto]

2010-12-02 00:04 Kevin Ballard <kevin@sb.org>:
> On Dec 1, 2010, at 11:29 AM, Jari Aalto wrote:
> Comprehension and ease-of-readability are far more important than visual
> aesthetics.

You can't take that out of equation. The people that read Western
languages, read A-Z. It's built in how we comprehend from start of
school education.

Jari

Re: [PATCH] git-add.txt: Order options alphabetically

[Kevin Ballard]

On Dec 1, 2010, at 2:30 PM, Jari Aalto wrote:

> 2010-12-02 00:04 Kevin Ballard <kevin@sb.org>:
>> On Dec 1, 2010, at 11:29 AM, Jari Aalto wrote:
>> Comprehension and ease-of-readability are far more important than visual
>> aesthetics.
> 
> You can't take that out of equation. The people that read Western
> languages, read A-Z. It's built in how we comprehend from start of
> school education.

I don't understand what you mean. People search A-Z. They don't read A-Z.
When you have tools to do the searching for you, A-Z ordering no longer
becomes useful. In an index, sure, as those are intended for scanning by
human eyes, but as actual documentation it serves no purpose.

-Kevin Ballard

Re: [PATCH] git-add.txt: Order options alphabetically

[SZEDER Gábor]

Please don't cull Cc list.


Hi,

On Thu, Dec 02, 2010 at 12:28:06AM +0200, Jari Aalto wrote:
> 2010-12-01 21:45 Drew Northup <drew.northup@maine.edu>:
> > On Wed, 2010-12-01 at 21:29 +0200, Jari Aalto wrote:
> >
> >> 2010-12-01 20:53 Drew Northup <drew.northup@maine.edu>:
> >> > (lacking a commit message to tell me), WHY? [alphabetical]
> >> 
> >> Quoting <http://permalink.gmane.org/gmane.comp.version-control.git/162552>
> >> 
> >>     - You read from top to bottom, therefore A-Z.
> >>     - GNU project uses it in manual pages. It looks good, it looks
> >>       professional, it looks clean. And it works when searching (= no
> >>       oriantation problems regardless of tools; even when you print on
> >>       paper when you don't have any computerized aids to help your search.).
> >> 
> >> Jari
> >
> > THAT belongs in a commit message!!!
> 
> It does not. No need to clutter 10's of message that long in there..

It definitely does.

People doing 'git log -- Documentation/git-add.txt' in the future will
want to see it, just as well as people doing 'git log --
Documentation/git-commit.txt', or 'git log --
Documentation/git-reset.txt', or ....

HtH,
Gábor