Re: [PATCH] improve documentation on mirroring

[Junio C Hamano <gitster@pobox.com>]

Tay Ray Chuan <rctay89@gmail.com> writes:

> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 664de6b..e87c06e 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1479,6 +1479,8 @@ remote.<name>.push::
>  remote.<name>.mirror::
>  	If true, pushing to this remote will automatically behave
>  	as if the `\--mirror` option was given on the command line.
> +	(See the `\--mirror` option to the `add` command to
> +	linkgit:git-remote[1] for more details on mirroring.)

Please call that "add" a subcommand.  My first quick glance made me go
"Huh?  git add --mirror?".  The same goes for your git-clone docco update.

> diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
> index 3fc599c..c2c25fd 100644
> --- a/Documentation/git-remote.txt
> +++ b/Documentation/git-remote.txt
> @@ -60,11 +60,11 @@ multiple branches without grabbing all branches.
>  With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set
>  up to point at remote's `<master>` branch. See also the set-head command.
>  +
> +With `\--mirror`, the fetch refspec for this remote is setup such that
> +fetched refs are not stored in the 'refs/remotes/' namespace (the default),
> +but in 'refs/heads/'.  The configuration variable `remote.<name>.mirror` is
> +also set to true, so that `git push` will always behave as if `\--mirror`
> +was passed.  This option only makes sense in bare repositories.

It is way suboptimal to say "refs/remotes/ namespace (the default)" here.
The reader either (1) knows by default tracking branches will fall under
refs/remotes and wants to find out what this funny --mirror mode does, or
(2) does not know where they go by default, and does not expect that the
description to the non-default --mirror mode is the place to learn about
it.

The culprit is the introductory description for the `add` option; it does
not start by explaining what happens by default when _no_ options are
given.  Once you fix _that_ problem, it would be clear to the reader that
the description of each option talks primarily about how the option makes
command behave differently from the default, and you can say something
like:

	With --mirror, all branches from the remote side are configured to
        be stored under the same name, i.e. refs/heads/<branch> at remote
        goes to refs/heads/<branch>.

without even mentioning what the default is again and again.  The
description of `-t` also talks about "instead of the default..."; it can
go if you follow this strategy.