From 48bb914ed641fc0880d86b16cbb17c84769c320a Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 11 Mar 2011 00:52:08 -0500 Subject: doc: drop author/documentation sections from most pages The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage. --- Documentation/git-remote.txt | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'Documentation/git-remote.txt') diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index c258ea48db..37bd3e5388 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -214,16 +214,6 @@ linkgit:git-fetch[1] linkgit:git-branch[1] linkgit:git-config[1] -Author ------- -Written by Junio Hamano - - -Documentation --------------- -Documentation by J. Bruce Fields and the git-list . - - GIT --- Part of the linkgit:git[1] suite -- cgit v1.2.3 From a9f5a3558dcf83440c60ae5a2e2b56c80d65bb0b Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 30 Mar 2011 15:53:19 -0400 Subject: remote: separate the concept of push and fetch mirrors git-remote currently has one option, "--mirror", which sets up mirror configuration which can be used for either fetching or pushing. It looks like this: [remote "mirror"] url = wherever fetch = +refs/*:refs/* mirror = true However, a remote like this can be dangerous and confusing. Specifically: 1. If you issue the wrong command, it can be devastating. You are not likely to "push" when you meant to "fetch", but "git remote update" will try to fetch it, even if you intended the remote only for pushing. In either case, the results can be quite destructive. An unintended push will overwrite or delete remote refs, and an unintended fetch can overwrite local branches. 2. The tracking setup code can produce confusing results. The fetch refspec above means that "git checkout -b new master" will consider refs/heads/master to come from the remote "mirror", even if you only ever intend to push to the mirror. It will set up the "new" branch to track mirror's refs/heads/master. 3. The push code tries to opportunistically update tracking branches. If you "git push mirror foo:bar", it will see that we are updating mirror's refs/heads/bar, which corresponds to our local refs/heads/bar, and will update our local branch. To solve this, we split the concept into "push mirrors" and "fetch mirrors". Push mirrors set only remote.*.mirror, solving (2) and (3), and making an accidental fetch write only into FETCH_HEAD. Fetch mirrors set only the fetch refspec, meaning an accidental push will not force-overwrite or delete refs on the remote end. The new syntax is "--mirror=". For compatibility, we keep "--mirror" as-is, setting up both types simultaneously. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-remote.txt | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'Documentation/git-remote.txt') diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index c258ea48db..79e38fedd7 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t ] [-m ] [-f] [--tags|--no-tags] [--mirror] +'git remote add' [-t ] [-m ] [-f] [--tags|--no-tags] [--mirror=] 'git remote rename' 'git remote rm' 'git remote set-head' (-a | -d | ) @@ -67,11 +67,18 @@ multiple branches without grabbing all branches. With `-m ` option, `$GIT_DIR/remotes//HEAD` is set up to point at remote's `` 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. +When a fetch mirror is created with `\--mirror=fetch`, the refs will not +be stored in the 'refs/remotes/' namespace, but rather everything in +'refs/' on the remote will be directly mirrored into 'refs/' in the +local repository. This option only makes sense in bare repositories, +because a fetch would overwrite any local commits. ++ +When a push mirror is created with `\--mirror=push`, then `git push` +will always behave as if `\--mirror` was passed. ++ +The option `\--mirror` (with no type) sets up both push and fetch +mirror configuration. It is kept for historical purposes, and is +probably not what you want. 'rename':: -- cgit v1.2.3 From 099024861021830f9d4c7db4c64c844bf9d5ebd9 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 30 Mar 2011 15:53:39 -0400 Subject: remote: deprecate --mirror The configuration created by plain --mirror is dangerous and useless, and we now have --mirror=fetch and --mirror=push to replace it. Let's warn the user. One alternative to this is to try to guess which type the user wants. In a non-bare repository, a fetch mirror doesn't make much sense, since it would overwrite local commits. But in a bare repository, you might use either type, or even both (e.g., if you are acting as an intermediate drop-point across two disconnected networks). So rather than try for complex heuristics, let's keep it simple. The user knows what they're trying to do, so let them tell us. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-remote.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'Documentation/git-remote.txt') diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 79e38fedd7..ddcbcc00ae 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -75,10 +75,6 @@ because a fetch would overwrite any local commits. + When a push mirror is created with `\--mirror=push`, then `git push` will always behave as if `\--mirror` was passed. -+ -The option `\--mirror` (with no type) sets up both push and fetch -mirror configuration. It is kept for historical purposes, and is -probably not what you want. 'rename':: -- cgit v1.2.3