Documentation: pull/clone ref mapping clarification.
Josef Weidendorfer points out that git-clone documentation does not mention the initial copying of remote branch heads into corresponding local branches. Also clarify the purpose of the ref mappings description in the "remotes" file and recommended workflow. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Nov 5, 2005 at 22:26 UTC
4607166d0735d13e0ee4ffe8df0c2fc899957852
2 files changed
+33
-14
Documentation/git-clone.txt
+20
-6
@@ -12,7 +12,21 @@ SYNOPSIS
12
13
DESCRIPTION
14
-----------
15
-Clones a repository into a newly created directory.
15
+Clones a repository into a newly created directory. All remote
16
+branch heads are copied under `$GIT_DIR/refs/heads/`, except
17
+that the remote `master` is also copied to `origin` branch.
18
+
19
+In addition, `$GIT_DIR/remotes/origin` file is set up to have
20
+this line:
21
+
22
+ Pull: master:origin
23
+
24
+This is to help the typical workflow of working off of the
25
+remote `master` branch. Every time `git pull` without argument
26
+is run, the progress on the remote `master` branch is tracked by
27
+copying it into the local `origin` branch, and merged into the
28
+branch you are currently working on.
29
+
30
31
OPTIONS
32
-------
@@ -28,9 +42,10 @@ OPTIONS
42
--shared::
43
-s::
44
When the repository to clone is on the local machine,
31
- instead of using hard links automatically setup
45
+ instead of using hard links, automatically setup
46
.git/objects/info/alternatives to share the objects
33
- with the source repository
47
+ with the source repository. The resulting repository
48
+ starts out without any object of its own.
49
50
--quiet::
51
-q::
@@ -49,14 +64,13 @@ OPTIONS
64
65
<repository>::
66
The (possibly remote) repository to clone from. It can
52
- be an "rsync://host/dir" URL, an "http://host/dir" URL,
53
- or [<host>:]/dir notation that is used by 'git-clone-pack'.
54
- Currently http transport is not supported.
67
+ be any URL git-fetch supports.
68
69
<directory>::
70
The name of a new directory to be cloned into. It is an
71
error to specify an existing directory.
72
73
+
74
Author
75
------
76
Written by Linus Torvalds <torvalds@osdl.org>
Documentation/pull-fetch-param.txt
+13
-8
@@ -82,14 +82,19 @@ must know this is the expected usage pattern for a branch.
82
[NOTE]
83
You never do your own development on branches that appear
84
on the right hand side of a <refspec> colon on `Pull:` lines;
85
-they are to be updated by `git-fetch`. The corollary is that
86
-a local branch should be introduced and named on a <refspec>
87
-right-hand-side if you intend to do development derived from
88
-that branch.
89
-This leads to the common `Pull: master:origin` mapping of a
90
-remote `master` branch to a local `origin` branch, which
91
-is then merged to a local development branch, again typically
92
-named `master`.
85
+they are to be updated by `git-fetch`. If you intend to do
86
+development derived from a remote branch `B`, have a `Pull:`
87
+line to track it (i.e. `Pull: B:remote-B`), and have a separate
88
+branch `my-B` to do your development on top of it. The latter
89
+is created by `git branch my-B remote-B` (or its equivalent `git
90
+checkout -b my-B remote-B`). Run `git fetch` to keep track of
91
+the progress of the remote side, and when you see something new
92
+on the remote branch, merge it into your development branch with
93
+`git pull . remote-B`, while you are on `my-B` branch.
94
+The common `Pull: master:origin` mapping of a remote `master`
95
+branch to a local `origin` branch, which is then merged to a
96
+ocal development branch, again typically named `master`, is made
97
+when you run `git clone` for you to follow this pattern.
98
+
99
[NOTE]
100
There is a difference between listing multiple <refspec>