Documentation/git-remote.txt

   1 git-remote(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-remote - Manage set of tracked repositories
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  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 filter (`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, shows 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 Sets or deletes 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 Changes 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 Changes 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 Gives 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 Deletes 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