X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fpull-fetch-param.txt;h=b5b979242ca809d121ef10826ab083159ea2195c;hb=b21c31c9a5edfd90d6f85481517f979352da4eed;hp=57e9ddf0d605e5536ce21901494c0058ef4ce857;hpb=87ce294c9129879f717f8749cae1c659e18a3823;p=git.git

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 57e9ddf0..b5b97924 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -5,11 +5,31 @@
 	to name the remote repository:
 +
 ===============================================================
-- Rsync URL:		rsync://remote.machine/path/to/repo.git/
-- HTTP(s) URL:		http://remote.machine/path/to/repo.git/
-- git URL:		git://remote.machine/path/to/repo.git/
-			or remote.machine:/path/to/repo.git/
-- Local directory:	/path/to/repo.git/
+- rsync://host.xz/path/to/repo.git/
+- http://host.xz/path/to/repo.git/
+- https://host.xz/path/to/repo.git/
+- git://host.xz/path/to/repo.git/
+- git://host.xz/~user/path/to/repo.git/
+- ssh://host.xz/path/to/repo.git/
+- ssh://host.xz/~user/path/to/repo.git/
+- ssh://host.xz/~/path/to/repo.git
+===============================================================
++
+SSH Is the default transport protocol and also supports an
+scp-like syntax.  Both syntaxes support username expansion,
+as does the native git protocol. The following three are
+identical to the last three above, respectively:
++
+===============================================================
+- host.xz:/path/to/repo.git/
+- host.xz:~user/path/to/repo.git/
+- host.xz:path/to/repo.git
+===============================================================
++
+To sync with a local directory, use:
++
+===============================================================
+- /path/to/repo.git/
 ===============================================================
 +
 In addition to the above, as a short-hand, the name of a
@@ -82,14 +102,19 @@ must know this is the expected usage pattern for a branch.
 [NOTE]
 You never do your own development on branches that appear
 on the right hand side of a <refspec> colon on `Pull:` lines;
-they are to be updated by `git-fetch`.  The corollary is that
-a local branch should be introduced and named on a <refspec>
-right-hand-side if you intend to do development derived from
-that branch.
-This leads to the common `Pull: master:origin` mapping of a
-remote `master` branch to a local `origin` branch, which
-is then merged to a local development branch, again typically
-named `master`.
+they are to be updated by `git-fetch`.  If you intend to do
+development derived from a remote branch `B`, have a `Pull:`
+line to track it (i.e. `Pull: B:remote-B`), and have a separate
+branch `my-B` to do your development on top of it.  The latter
+is created by `git branch my-B remote-B` (or its equivalent `git
+checkout -b my-B remote-B`).  Run `git fetch` to keep track of
+the progress of the remote side, and when you see something new
+on the remote branch, merge it into your development branch with
+`git pull . remote-B`, while you are on `my-B` branch.
+The common `Pull: master:origin` mapping of a remote `master`
+branch to a local `origin` branch, which is then merged to a
+local development branch, again typically named `master`, is made
+when you run `git clone` for you to follow this pattern.
 +
 [NOTE]
 There is a difference between listing multiple <refspec>