]>
Commit | Line | Data |
---|---|---|
0c04094b | 1 | <repository>:: |
bccf5956 JL |
2 | The "remote" repository that is the source of a fetch |
3 | or pull operation, or the destination of a push operation. | |
4 | One of the following notations can be used | |
5 | to name the remote repository: | |
df8baa42 JF |
6 | + |
7 | =============================================================== | |
7b5d895d AE |
8 | - rsync://host.xz/path/to/repo.git/ |
9 | - http://host.xz/path/to/repo.git/ | |
10 | - https://host.xz/path/to/repo.git/ | |
11 | - git://host.xz/path/to/repo.git/ | |
4dbd1352 | 12 | - git://host.xz/~user/path/to/repo.git/ |
7b5d895d AE |
13 | - ssh://host.xz/path/to/repo.git/ |
14 | - ssh://host.xz/~user/path/to/repo.git/ | |
15 | - ssh://host.xz/~/path/to/repo.git | |
16 | =============================================================== | |
17 | + | |
b020dcd5 JL |
18 | SSH Is the default transport protocol and also supports an |
19 | scp-like syntax. Both syntaxes support username expansion, | |
20 | as does the native git protocol. The following three are | |
21 | identical to the last three above, respectively: | |
7b5d895d AE |
22 | + |
23 | =============================================================== | |
24 | - host.xz:/path/to/repo.git/ | |
25 | - host.xz:~user/path/to/repo.git/ | |
26 | - host.xz:path/to/repo.git | |
27 | =============================================================== | |
28 | + | |
b020dcd5 JL |
29 | To sync with a local directory, use: |
30 | + | |
7b5d895d AE |
31 | =============================================================== |
32 | - /path/to/repo.git/ | |
df8baa42 JF |
33 | =============================================================== |
34 | + | |
35 | In addition to the above, as a short-hand, the name of a | |
bccf5956 | 36 | file in `$GIT_DIR/remotes` directory can be given; the |
df8baa42 JF |
37 | named file should be in the following format: |
38 | + | |
39 | URL: one of the above URL format | |
fdd08979 JH |
40 | Push: <refspec> |
41 | Pull: <refspec> | |
df8baa42 JF |
42 | + |
43 | When such a short-hand is specified in place of | |
44 | <repository> without <refspec> parameters on the command | |
fdd08979 | 45 | line, <refspec> specified on `Push:` lines or `Pull:` |
bccf5956 JL |
46 | lines are used for `git-push` and `git-fetch`/`git-pull`, |
47 | respectively. Multiple `Push:` and and `Pull:` lines may | |
48 | be specified for additional branch mappings. | |
df8baa42 | 49 | + |
bccf5956 | 50 | The name of a file in `$GIT_DIR/branches` directory can be |
df8baa42 JF |
51 | specified as an older notation short-hand; the named |
52 | file should contain a single line, a URL in one of the | |
bccf5956 | 53 | above formats, optionally followed by a hash `#` and the |
df8baa42 | 54 | name of remote head (URL fragment notation). |
bccf5956 | 55 | `$GIT_DIR/branches/<remote>` file that stores a <url> |
df8baa42 | 56 | without the fragment is equivalent to have this in the |
bccf5956 | 57 | corresponding file in the `$GIT_DIR/remotes/` directory. |
df8baa42 JF |
58 | + |
59 | URL: <url> | |
60 | Pull: refs/heads/master:<remote> | |
61 | + | |
bccf5956 | 62 | while having `<url>#<head>` is equivalent to |
df8baa42 JF |
63 | + |
64 | URL: <url> | |
65 | Pull: refs/heads/<head>:<remote> | |
ab9b3138 JH |
66 | |
67 | <refspec>:: | |
68 | The canonical format of a <refspec> parameter is | |
bccf5956 JL |
69 | `+?<src>:<dst>`; that is, an optional plus `+`, followed |
70 | by the source ref, followed by a colon `:`, followed by | |
ab9b3138 | 71 | the destination ref. |
df8baa42 | 72 | + |
bccf5956 | 73 | When used in `git-push`, the <src> side can be an |
df8baa42 | 74 | arbitrary "SHA1 expression" that can be used as an |
bccf5956 | 75 | argument to `git-cat-file -t`. E.g. `master~4` (push |
df8baa42 JF |
76 | four parents before the current master head). |
77 | + | |
bccf5956 | 78 | For `git-push`, the local ref that matches <src> is used |
df8baa42 | 79 | to fast forward the remote ref that matches <dst>. If |
bccf5956 | 80 | the optional plus `+` is used, the remote ref is updated |
df8baa42 JF |
81 | even if it does not result in a fast forward update. |
82 | + | |
bccf5956 | 83 | For `git-fetch` and `git-pull`, the remote ref that matches <src> |
df8baa42 JF |
84 | is fetched, and if <dst> is not empty string, the local |
85 | ref that matches it is fast forwarded using <src>. | |
bccf5956 | 86 | Again, if the optional plus `+` is used, the local ref |
df8baa42 JF |
87 | is updated even if it does not result in a fast forward |
88 | update. | |
89 | + | |
bccf5956 JL |
90 | [NOTE] |
91 | If the remote branch from which you want to pull is | |
92 | modified in non-linear ways such as being rewound and | |
93 | rebased frequently, then a pull will attempt a merge with | |
94 | an older version of itself, likely conflict, and fail. | |
95 | It is under these conditions that you would want to use | |
96 | the `+` sign to indicate non-fast-forward updates will | |
97 | be needed. There is currently no easy way to determine | |
98 | or declare that a branch will be made available in a | |
99 | repository with this behavior; the pulling user simply | |
100 | must know this is the expected usage pattern for a branch. | |
101 | + | |
102 | [NOTE] | |
103 | You never do your own development on branches that appear | |
104 | on the right hand side of a <refspec> colon on `Pull:` lines; | |
4607166d JH |
105 | they are to be updated by `git-fetch`. If you intend to do |
106 | development derived from a remote branch `B`, have a `Pull:` | |
107 | line to track it (i.e. `Pull: B:remote-B`), and have a separate | |
108 | branch `my-B` to do your development on top of it. The latter | |
109 | is created by `git branch my-B remote-B` (or its equivalent `git | |
110 | checkout -b my-B remote-B`). Run `git fetch` to keep track of | |
111 | the progress of the remote side, and when you see something new | |
112 | on the remote branch, merge it into your development branch with | |
113 | `git pull . remote-B`, while you are on `my-B` branch. | |
114 | The common `Pull: master:origin` mapping of a remote `master` | |
115 | branch to a local `origin` branch, which is then merged to a | |
b020dcd5 | 116 | local development branch, again typically named `master`, is made |
4607166d | 117 | when you run `git clone` for you to follow this pattern. |
bccf5956 | 118 | + |
fdd08979 JH |
119 | [NOTE] |
120 | There is a difference between listing multiple <refspec> | |
121 | directly on `git-pull` command line and having multiple | |
122 | `Pull:` <refspec> lines for a <repository> and running | |
123 | `git-pull` command without any explicit <refspec> parameters. | |
124 | <refspec> listed explicitly on the command line are always | |
125 | merged into the current branch after fetching. In other words, | |
126 | if you list more than one remote refs, you would be making | |
127 | an Octopus. While `git-pull` run without any explicit <refspec> | |
128 | parameter takes default <refspec>s from `Pull:` lines, it | |
129 | merges only the first <refspec> found into the current branch, | |
130 | after fetching all the remote refs. This is because making an | |
131 | Octopus from remote refs is rarely done, while keeping track | |
132 | of multiple remote heads in one-go by fetching more than one | |
133 | is often useful. | |
134 | + | |
df8baa42 JF |
135 | Some short-cut notations are also supported. |
136 | + | |
bccf5956 | 137 | * For backward compatibility, `tag` is almost ignored; |
df8baa42 | 138 | it just makes the following parameter <tag> to mean a |
bccf5956 | 139 | refspec `refs/tags/<tag>:refs/tags/<tag>`. |
df8baa42 | 140 | * A parameter <ref> without a colon is equivalent to |
bccf5956 | 141 | <ref>: when pulling/fetching, and <ref>`:`<ref> when |
df8baa42 JF |
142 | pushing. That is, do not store it locally if |
143 | fetching, and update the same name if pushing. | |
61420a2c | 144 |