Documentation: begin discussion of git-remote in user manual
Start discussion of git-remote. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Jan 9, 2007 at 00:18 UTC
d5cd5de495654ec2454e8c37829c5e1c9f49b66a
1 file changed
+54
-14
Documentation/user-manual.txt
+54
-14
@@ -4,12 +4,12 @@ _________________
4
This manual is designed to be readable by someone with basic unix
5
commandline skills, but no previous knowledge of git.
6
7
-Chapters 1 and 2 explain how to fetch and study a project using git--the
8
-tools you'd need to build and test a particular version of a software
9
-project, to search for regressions, and so on.
7
+Chapters 1 and 2 explain how to fetch and study a project using
8
+git--the tools you'd need to build and test a particular version of a
9
+software project, to search for regressions, and so on.
10
11
-Chapter 3 explains how to do development with git and share your progress
12
-with others.
11
+Chapter 3 explains how to do development with git, and chapter 4 how
12
+to share that development with others.
13
14
Further chapters cover more specialized topics.
15
@@ -50,7 +50,7 @@ directory, you will see that it contains a copy of the project files,
50
together with a special top-level directory named ".git", which
51
contains all the information about the history of the project.
52
53
-In the following, examples will be taken from one of the two
53
+In most of the following, examples will be taken from one of the two
54
repositories above.
55
56
How to check out a different version of a project
@@ -340,9 +340,52 @@ remote-tracking branches to the latest version found in her
340
repository. It will not touch any of your own branches--not even the
341
"master" branch that was created for you on clone.
342
343
+Fetching branches from other repositories
344
+-----------------------------------------
345
+
346
+You can also track branches from repositories other than the one you
347
+cloned from, using gitlink:git-remote[1]:
348
+
349
+-------------------------------------------------
350
+$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
351
+$ git fetch
352
+* refs/remotes/linux-nfs/master: storing branch 'master' ...
353
+ commit: bf81b46
354
+-------------------------------------------------
355
+
356
+New remote-tracking branches will be stored under the shorthand name
357
+that you gave "git remote add", in this case linux-nfs:
358
+
359
+-------------------------------------------------
360
+$ git branch -r
361
+linux-nfs/master
362
+origin/master
363
+-------------------------------------------------
364
+
365
+If you run "git fetch <remote>" later, the tracking branches for the
366
+named <remote> will be updated.
367
+
368
+If you examine the file .git/config, you will see that git has added
369
+a new stanza:
370
+
371
+-------------------------------------------------
372
+$ cat .git/config
373
+...
374
+[remote "linux-nfs"]
375
+ url = git://linux-nfs.org/~bfields/git.git
376
+ fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
377
+...
378
+-------------------------------------------------
379
+
380
+This is what causes git to track the remote's branches; you may
381
+modify or delete these configuration options by editing .git/config
382
+with a text editor.
383
+
384
Fetching individual branches
385
----------------------------
386
387
+TODO: find another home for this, later on:
388
+
389
You can also choose to update just one branch at a time:
390
391
-------------------------------------------------
@@ -1618,9 +1661,9 @@ The basic requirements:
1661
knowledge than necessary: for example, "importing patches into a
1662
project" rather than "the git-am command"
1663
1621
-Think about how to create a clear chapter dependency graph that will allow
1622
-people to get to important topics without necessarily reading everything
1623
-in between.
1664
+Think about how to create a clear chapter dependency graph that will
1665
+allow people to get to important topics without necessarily reading
1666
+everything in between.
1667
1668
Scan Documentation/ for other stuff left out; in particular:
1669
howto's
@@ -1634,11 +1677,8 @@ Scan email archives for other stuff left out
1677
Scan man pages to see if any assume more background than this manual
1678
provides.
1679
1637
-Update git fetch discussion to use "git remote", move most of branch
1638
-discussion till later.
1639
-
1640
-Can also simplify beginning by suggesting disconnected head instead
1641
-of temporary branch creation.
1680
+Simplify beginning by suggesting disconnected head instead of temporary
1681
+branch creation.
1682
1683
Explain how to refer to file stages in the "how to resolve a merge"
1684
section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The