Re: [PATCH] improve documentation on mirroring

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 22, 2010, 06:54 UTC
Message-ID: <7viq9prc99.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1266819758-5572-1-git-send-email-rctay89@gmail.com>

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

Show 10 quoted lines

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

Show 13 quoted lines

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