| 1 | git-remote(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-remote - Manage set of tracked repositories |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git remote [-v | --verbose] |
| 13 | git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL> |
| 14 | git remote rename [--[no-]progress] <old> <new> |
| 15 | git remote remove <name> |
| 16 | git remote set-head <name> (-a | --auto | -d | --delete | <branch>) |
| 17 | git remote set-branches [--add] <name> <branch>... |
| 18 | git remote get-url [--push] [--all] <name> |
| 19 | git remote set-url [--push] <name> <newurl> [<oldurl>] |
| 20 | git remote set-url --add [--push] <name> <newurl> |
| 21 | git remote set-url --delete [--push] <name> <URL> |
| 22 | git remote [-v | --verbose] show [-n] <name>... |
| 23 | git remote prune [-n | --dry-run] <name>... |
| 24 | git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...] |
| 25 | |
| 26 | DESCRIPTION |
| 27 | ----------- |
| 28 | |
| 29 | Manage the set of repositories ("remotes") whose branches you track. |
| 30 | |
| 31 | |
| 32 | OPTIONS |
| 33 | ------- |
| 34 | |
| 35 | `-v`:: |
| 36 | `--verbose`:: |
| 37 | Be a little more verbose and show remote url after name. |
| 38 | For promisor remotes, also show which filters (`blob:none` etc.) |
| 39 | are configured. |
| 40 | NOTE: This must be placed between `remote` and subcommand. |
| 41 | |
| 42 | |
| 43 | COMMANDS |
| 44 | -------- |
| 45 | |
| 46 | With no arguments, show a list of existing remotes. Several |
| 47 | subcommands are available to perform operations on the remotes. |
| 48 | |
| 49 | `add`:: |
| 50 | |
| 51 | Add a remote named _<name>_ for the repository at |
| 52 | _<URL>_. The command `git fetch <name>` can then be used to create and |
| 53 | update remote-tracking branches `<name>/<branch>`. |
| 54 | + |
| 55 | With `-f` option, `git fetch <name>` is run immediately after |
| 56 | the remote information is set up. |
| 57 | + |
| 58 | With `--tags` option, `git fetch <name>` imports every tag from the |
| 59 | remote repository. |
| 60 | + |
| 61 | With `--no-tags` option, `git fetch <name>` does not import tags from |
| 62 | the remote repository. |
| 63 | + |
| 64 | By default, only tags on fetched branches are imported |
| 65 | (see linkgit:git-fetch[1]). |
| 66 | + |
| 67 | With `-t <branch>` option, instead of the default glob |
| 68 | refspec for the remote to track all branches under |
| 69 | the `refs/remotes/<name>/` namespace, a refspec to track only _<branch>_ |
| 70 | is created. You can give more than one `-t <branch>` to track |
| 71 | multiple branches without grabbing all branches. |
| 72 | + |
| 73 | With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set |
| 74 | up to point at remote's _<master>_ branch. See also the set-head command. |
| 75 | + |
| 76 | When a fetch mirror is created with `--mirror=fetch`, the refs will not |
| 77 | be stored in the `refs/remotes/` namespace, but rather everything in |
| 78 | `refs/` on the remote will be directly mirrored into `refs/` in the |
| 79 | local repository. This option only makes sense in bare repositories, |
| 80 | because a fetch would overwrite any local commits. |
| 81 | + |
| 82 | When a push mirror is created with `--mirror=push`, then `git push` |
| 83 | will always behave as if `--mirror` was passed. |
| 84 | |
| 85 | `rename`:: |
| 86 | |
| 87 | Rename the remote named _<old>_ to _<new>_. All remote-tracking branches and |
| 88 | configuration settings for the remote are updated. |
| 89 | + |
| 90 | In case _<old>_ and _<new>_ are the same, and _<old>_ is a file under |
| 91 | `$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to |
| 92 | the configuration file format. |
| 93 | |
| 94 | `remove`:: |
| 95 | `rm`:: |
| 96 | |
| 97 | Remove the remote named _<name>_. All remote-tracking branches and |
| 98 | configuration settings for the remote are removed. |
| 99 | |
| 100 | `set-head`:: |
| 101 | |
| 102 | Set or delete the default branch (i.e. the target of the |
| 103 | symbolic-ref `refs/remotes/<name>/HEAD`) for |
| 104 | the named remote. Having a default branch for a remote is not required, |
| 105 | but allows the name of the remote to be specified in lieu of a specific |
| 106 | branch. For example, if the default branch for `origin` is set to |
| 107 | `master`, then `origin` may be specified wherever you would normally |
| 108 | specify `origin/master`. |
| 109 | + |
| 110 | With `-d` or `--delete`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted. |
| 111 | + |
| 112 | With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the |
| 113 | symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote |
| 114 | `HEAD` is pointed at `next`, `git remote set-head origin -a` will set |
| 115 | the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will |
| 116 | only work if `refs/remotes/origin/next` already exists; if not it must be |
| 117 | fetched first. |
| 118 | + |
| 119 | Use _<branch>_ to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., `git |
| 120 | remote set-head origin master` will set the symbolic-ref `refs/remotes/origin/HEAD` to |
| 121 | `refs/remotes/origin/master`. This will only work if |
| 122 | `refs/remotes/origin/master` already exists; if not it must be fetched first. |
| 123 | + |
| 124 | |
| 125 | `set-branches`:: |
| 126 | |
| 127 | Change the list of branches tracked by the named remote. |
| 128 | This can be used to track a subset of the available remote branches |
| 129 | after the initial setup for a remote. |
| 130 | + |
| 131 | The named branches will be interpreted as if specified with the |
| 132 | `-t` option on the `git remote add` command line. |
| 133 | + |
| 134 | With `--add`, instead of replacing the list of currently tracked |
| 135 | branches, adds to that list. |
| 136 | |
| 137 | `get-url`:: |
| 138 | |
| 139 | Retrieves the URLs for a remote. Configurations for `insteadOf` and |
| 140 | `pushInsteadOf` are expanded here. By default, only the first URL is listed. |
| 141 | + |
| 142 | With `--push`, push URLs are queried rather than fetch URLs. |
| 143 | + |
| 144 | With `--all`, all URLs for the remote will be listed. |
| 145 | |
| 146 | `set-url`:: |
| 147 | |
| 148 | Change URLs for the remote. Sets first URL for remote _<name>_ that matches |
| 149 | regex _<oldurl>_ (first URL if no _<oldurl>_ is given) to _<newurl>_. If |
| 150 | _<oldurl>_ doesn't match any URL, an error occurs and nothing is changed. |
| 151 | + |
| 152 | With `--push`, push URLs are manipulated instead of fetch URLs. |
| 153 | + |
| 154 | With `--add`, instead of changing existing URLs, new URL is added. |
| 155 | + |
| 156 | With `--delete`, instead of changing existing URLs, all URLs matching |
| 157 | regex _<URL>_ are deleted for remote _<name>_. Trying to delete all |
| 158 | non-push URLs is an error. |
| 159 | + |
| 160 | Note that the push URL and the fetch URL, even though they can |
| 161 | be set differently, must still refer to the same place. What you |
| 162 | pushed to the push URL should be what you would see if you |
| 163 | immediately fetched from the fetch URL. If you are trying to |
| 164 | fetch from one place (e.g. your upstream) and push to another (e.g. |
| 165 | your publishing repository), use two separate remotes. |
| 166 | |
| 167 | |
| 168 | `show`:: |
| 169 | |
| 170 | Give some information about the remote _<name>_. |
| 171 | + |
| 172 | With `-n` option, the remote heads are not queried first with |
| 173 | `git ls-remote <name>`; cached information is used instead. |
| 174 | |
| 175 | `prune`:: |
| 176 | |
| 177 | Delete stale references associated with _<name>_. By default, stale |
| 178 | remote-tracking branches under _<name>_ are deleted, but depending on |
| 179 | global configuration and the configuration of the remote we might even |
| 180 | prune local tags that haven't been pushed there. Equivalent to `git |
| 181 | fetch --prune <name>`, except that no new references will be fetched. |
| 182 | + |
| 183 | See the PRUNING section of linkgit:git-fetch[1] for what it'll prune |
| 184 | depending on various configuration. |
| 185 | + |
| 186 | With `--dry-run` option, report what branches would be pruned, but do not |
| 187 | actually prune them. |
| 188 | |
| 189 | `update`:: |
| 190 | |
| 191 | Fetch updates for remotes or remote groups in the repository as defined by |
| 192 | `remotes.<group>`. If neither group nor remote is specified on the command line, |
| 193 | the configuration parameter `remotes.default` will be used; if |
| 194 | `remotes.default` is not defined, all remotes which do not have the |
| 195 | configuration parameter `remote.<name>.skipDefaultUpdate` set to `true` will |
| 196 | be updated. (See linkgit:git-config[1]). |
| 197 | + |
| 198 | With `--prune` option, run pruning against all the remotes that are updated. |
| 199 | |
| 200 | |
| 201 | DISCUSSION |
| 202 | ---------- |
| 203 | |
| 204 | The remote configuration is achieved using the `remote.origin.url` and |
| 205 | `remote.origin.fetch` configuration variables. (See |
| 206 | linkgit:git-config[1]). |
| 207 | |
| 208 | EXIT STATUS |
| 209 | ----------- |
| 210 | |
| 211 | On success, the exit status is `0`. |
| 212 | |
| 213 | When subcommands such as `add`, `rename`, and `remove` can't find the |
| 214 | remote in question, the exit status is `2`. When the remote already |
| 215 | exists, the exit status is `3`. |
| 216 | |
| 217 | On any other error, the exit status may be any other non-zero value. |
| 218 | |
| 219 | EXAMPLES |
| 220 | -------- |
| 221 | |
| 222 | * Add a new remote, fetch, and check out a branch from it |
| 223 | + |
| 224 | ------------ |
| 225 | $ git remote |
| 226 | origin |
| 227 | $ git branch -r |
| 228 | origin/HEAD -> origin/master |
| 229 | origin/master |
| 230 | $ git remote add staging git://git.kernel.org/.../gregkh/staging.git |
| 231 | $ git remote |
| 232 | origin |
| 233 | staging |
| 234 | $ git fetch staging |
| 235 | ... |
| 236 | From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging |
| 237 | * [new branch] master -> staging/master |
| 238 | * [new branch] staging-linus -> staging/staging-linus |
| 239 | * [new branch] staging-next -> staging/staging-next |
| 240 | $ git branch -r |
| 241 | origin/HEAD -> origin/master |
| 242 | origin/master |
| 243 | staging/master |
| 244 | staging/staging-linus |
| 245 | staging/staging-next |
| 246 | $ git switch -c staging staging/master |
| 247 | ... |
| 248 | ------------ |
| 249 | |
| 250 | * Imitate `git clone` but track only selected branches |
| 251 | + |
| 252 | ------------ |
| 253 | $ mkdir project.git |
| 254 | $ cd project.git |
| 255 | $ git init |
| 256 | $ git remote add -f -t master -m master origin git://example.com/git.git/ |
| 257 | $ git merge origin |
| 258 | ------------ |
| 259 | |
| 260 | |
| 261 | SEE ALSO |
| 262 | -------- |
| 263 | linkgit:git-fetch[1] |
| 264 | linkgit:git-branch[1] |
| 265 | linkgit:git-config[1] |
| 266 | |
| 267 | GIT |
| 268 | --- |
| 269 | Part of the linkgit:git[1] suite |