{"thread":{"id":"22750","subject":"Re: [PATCH] improve documentation on mirroring","startedAt":"2010-02-22T06:22:38Z","lastAt":"2010-02-22T06:54:42Z","messageCount":2,"participants":["Junio C Hamano","Tay Ray Chuan"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"135267","messageId":"1266819758-5572-1-git-send-email-rctay89@gmail.com","threadId":"22750","inReplyTo":null,"subject":"[PATCH] improve documentation on mirroring","fromName":"Tay Ray Chuan","fromEmail":"rctay89@gmail.com","sentAt":"2010-02-22T06:22:38Z","receivedAt":"2010-02-22T06:22:38Z","isPatch":true,"sender":{"key":"rctay89@gmail.com","avatar":"https://avatars.githubusercontent.com/u/61553?v=4"},"body":"Signed-off-by: Tay Ray Chuan \n---\n\n Details on mirroring are distributed across various manpages, and I\n found myself grepping for it - definitely a bad sign.\n\n Documentation/config.txt | 2 ++\n Documentation/git-clone.txt | 2 ++\n Documentation/git-remote.txt | 10 +++++-----\n 3 files changed, 9 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 664de6b..e87c06e 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -1479,6 +1479,8 @@ remote..push::\n remote..mirror::\n \tIf true, pushing to this remote will automatically behave\n \tas if the `\\--mirror` option was given on the command line.\n+\t(See the `\\--mirror` option to the `add` command to\n+\tlinkgit:git-remote[1] for more details on mirroring.)\n\n remote..skipDefaultUpdate::\n \tIf true, this remote will be skipped by default when updating\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 88ea624..3bd57d2 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -128,6 +128,8 @@ objects from the source repository into a pack in the cloned repository.\n\n --mirror::\n \tSet up a mirror of the remote repository. This implies `--bare`.\n+\t(See the `\\--mirror` option to the `add` command to\n+\tlinkgit:git-remote[1] for more details on mirroring.)\n\n --origin ::\n -o ::\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 3fc599c..c2c25fd 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -60,11 +60,11 @@ multiple branches without grabbing all branches.\n With `-m ` option, `$GIT_DIR/remotes//HEAD` is set\n up to point at remote's `` branch. See also the set-head command.\n +\n-In mirror mode, enabled with `\\--mirror`, the refs will not be stored\n-in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option\n-only makes sense in bare repositories. If a remote uses mirror\n-mode, furthermore, `git push` will always behave as if `\\--mirror`\n-was passed.\n+With `\\--mirror`, the fetch refspec for this remote is setup such that\n+fetched refs are not stored in the 'refs/remotes/' namespace (the default),\n+but in 'refs/heads/'. The configuration variable `remote..mirror` is\n+also set to true, so that `git push` will always behave as if `\\--mirror`\n+was passed. This option only makes sense in bare repositories.\n\n 'rename'::\n\n--\n1.7.0.20.gcb44ed\n"},{"id":"135263","messageId":"7viq9prc99.fsf@alter.siamese.dyndns.org","threadId":"22750","inReplyTo":"1266819758-5572-1-git-send-email-rctay89@gmail.com","subject":"Re: [PATCH] improve documentation on mirroring","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-22T06:54:42Z","receivedAt":"2010-02-22T06:54:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tay Ray Chuan writes:\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 664de6b..e87c06e 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -1479,6 +1479,8 @@ remote..push::\n> remote..mirror::\n> \tIf true, pushing to this remote will automatically behave\n> \tas if the `\\--mirror` option was given on the command line.\n> +\t(See the `\\--mirror` option to the `add` command to\n> +\tlinkgit:git-remote[1] for more details on mirroring.)\n\nPlease call that \"add\" a subcommand. My first quick glance made me go\n\"Huh? git add --mirror?\". The same goes for your git-clone docco update.\n\n> diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\n> index 3fc599c..c2c25fd 100644\n> --- a/Documentation/git-remote.txt\n> +++ b/Documentation/git-remote.txt\n> @@ -60,11 +60,11 @@ multiple branches without grabbing all branches.\n> With `-m ` option, `$GIT_DIR/remotes//HEAD` is set\n> up to point at remote's `` branch. See also the set-head command.\n> +\n> +With `\\--mirror`, the fetch refspec for this remote is setup such that\n> +fetched refs are not stored in the 'refs/remotes/' namespace (the default),\n> +but in 'refs/heads/'. The configuration variable `remote..mirror` is\n> +also set to true, so that `git push` will always behave as if `\\--mirror`\n> +was passed. This option only makes sense in bare repositories.\n\nIt is way suboptimal to say \"refs/remotes/ namespace (the default)\" here.\nThe reader either (1) knows by default tracking branches will fall under\nrefs/remotes and wants to find out what this funny --mirror mode does, or\n(2) does not know where they go by default, and does not expect that the\ndescription to the non-default --mirror mode is the place to learn about\nit.\n\nThe culprit is the introductory description for the `add` option; it does\nnot start by explaining what happens by default when _no_ options are\ngiven. Once you fix _that_ problem, it would be clear to the reader that\nthe description of each option talks primarily about how the option makes\ncommand behave differently from the default, and you can say something\nlike:\n\n\tWith --mirror, all branches from the remote side are configured to\n be stored under the same name, i.e. refs/heads/ at remote\n goes to refs/heads/.\n\nwithout even mentioning what the default is again and again. The\ndescription of `-t` also talks about \"instead of the default...\"; it can\ngo if you follow this strategy.\n"}]}