threads / patch / 22750

patchRe: [PATCH] improve documentation on mirroring

Subject: Re: [PATCH] improve documentation on mirroring

## tl;dr

2 messages between Feb 22, 2010 and Feb 22, 2010. Diffs are folded; open one to read it.

replies: 1people: 2as markdown or json

Tay Ray Chuan· Feb 22, 2010, 06:22 UTC · lore

[PATCH] improve documentation on mirroring

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

Show changes to 3 files +9 −6

Documentation/config.txt, Documentation/git-clone.txt, Documentation/git-remote.txt

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

Junio C Hamano· Feb 22, 2010, 06:54 UTC · re: Tay Ray Chuan · lore

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.