[PATCH] improve documentation on mirroring

[PATCH] improve documentation on mirroring

[Tay Ray Chuan]

Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>
---

  Details on mirroring are distributed across various manpages, and I
  found myself grepping for it - definitely a bad sign.

 Documentation/config.txt     |    2 ++
 Documentation/git-clone.txt  |    2 ++
 Documentation/git-remote.txt |   10 +++++-----
 3 files changed, 9 insertions(+), 5 deletions(-)

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

 remote.<name>.skipDefaultUpdate::
 	If true, this remote will be skipped by default when updating
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 88ea624..3bd57d2 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -128,6 +128,8 @@ objects from the source repository into a pack in the cloned repository.

 --mirror::
 	Set up a mirror of the remote repository.  This implies `--bare`.
+	(See the `\--mirror` option to the `add` command to
+	linkgit:git-remote[1] for more details on mirroring.)

 --origin <name>::
 -o <name>::
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.
 +
-In mirror mode, enabled with `\--mirror`, the refs will not be stored
-in the 'refs/remotes/' namespace, but in 'refs/heads/'.  This option
-only makes sense in bare repositories.  If a remote uses mirror
-mode, furthermore, `git push` will always behave as if `\--mirror`
-was passed.
+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.

 'rename'::

--
1.7.0.20.gcb44ed

Re: [PATCH] improve documentation on mirroring

[Junio C Hamano]

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.