v1.5.0.txt updates (Carl Worth's suggestions, batch II)
Junio C Hamano committed
Jan 22, 2007 at 17:15 UTC
d1d9f47f0ebd40f64e4fa6ac4210a77b55c05f53
1 file changed
+38
-5
v1.5.0.txt
+38
-5
@@ -107,11 +107,44 @@ Updates in v1.5.0 since v1.4.4 series
107
already comfortable with your workflow with the layout.
108
109
- git-clone always uses what is known as "separate remote"
110
- layout for a newly created repository with a working tree;
111
- i.e. tracking branches in $GIT_DIR/refs/remotes/origin/ are
112
- used to track branches from the origin, instead of
113
- $GIT_DIR/refs/heads/, making the difference between remotely
114
- tracked and local branches more obvious.
110
+ layout for a newly created repository with a working tree.
111
+
112
+ A repository with the separate remote layout starts with only
113
+ one default branch, 'master', to be used for your own
114
+ development. Unlike the traditional layout that copied all
115
+ the upstream branches into your branch namespace (while
116
+ renaming their 'master' to your 'origin'), the new layout
117
+ puts upstream branches into local "remote-tracking branches"
118
+ with their own namespace. These can be referenced with names
119
+ such as "origin/$upstream_branch_name" and are stored in
120
+ .git/refs/remotes rather than .git/refs/heads where normal
121
+ branches are stored.
122
+
123
+ This layout keeps your own branch namespace less cluttered,
124
+ avoids name collision with your upstream, makes it possible
125
+ to automatically track new branches created at the remote
126
+ after you clone from it, and makes it easier to interact with
127
+ more than one remote repository (you can use "git remote" to
128
+ add other repositories to track). There might be some
129
+ surprises:
130
+
131
+ * 'git branch' does not show the remote tracking branches.
132
+ It only lists your own branches. Use '-r' option to view
133
+ the tracking branches.
134
+
135
+ * If you are forking off of a branch obtained from the
136
+ upstream, you would have done something like 'git branch
137
+ my-next next', because traditional layout dropped the
138
+ tracking branch 'next' into your own branch namespace.
139
+ With the separate remote layout, you say 'git branch next
140
+ origin/next', which allows you to use the matching name
141
+ 'next' for your own branch. It also allows you to track a
142
+ remote other than 'origin' (i.e. where you initially cloned
143
+ from) and fork off of a branch from there the same way
144
+ (e.g. "git branch mingw j6t/master").
145
+
146
+ Repositories initialized with the traditional layout continue
147
+ to work.
148
149
- New branches that appear on the origin side after a clone is
150
made are also tracked automatically. This is done with an