doc/source/en/TortoiseGit/git_doc/git-remote.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-remote(1)">\r
   5 <articleinfo>\r
   6     <title>git-remote(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-remote(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-remote - manage set of tracked repositories</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git remote</emphasis> [-v | --verbose]\r
  19 <emphasis>git remote add</emphasis> [-t &lt;branch&gt;] [-m &lt;master&gt;] [-f] [--tags|--no-tags] [--mirror=&lt;fetch|push&gt;] &lt;name&gt; &lt;url&gt;\r
  20 <emphasis>git remote rename</emphasis> &lt;old&gt; &lt;new&gt;\r
  21 <emphasis>git remote rm</emphasis> &lt;name&gt;\r
  22 <emphasis>git remote set-head</emphasis> &lt;name&gt; (-a | -d | &lt;branch&gt;)\r
  23 <emphasis>git remote set-branches</emphasis> [--add] &lt;name&gt; &lt;branch&gt;&#8230;\r
  24 <emphasis>git remote set-url</emphasis> [--push] &lt;name&gt; &lt;newurl&gt; [&lt;oldurl&gt;]\r
  25 <emphasis>git remote set-url --add</emphasis> [--push] &lt;name&gt; &lt;newurl&gt;\r
  26 <emphasis>git remote set-url --delete</emphasis> [--push] &lt;name&gt; &lt;url&gt;\r
  27 <emphasis>git remote</emphasis> [-v | --verbose] <emphasis>show</emphasis> [-n] &lt;name&gt;\r
  28 <emphasis>git remote prune</emphasis> [-n | --dry-run] &lt;name&gt;\r
  29 <emphasis>git remote</emphasis> [-v | --verbose] <emphasis>update</emphasis> [-p | --prune] [(&lt;group&gt; | &lt;remote&gt;)&#8230;]</literallayout>\r
  30 </blockquote>\r
  31 </simplesect>\r
  32 <simplesect id="_description">\r
  33 <title>DESCRIPTION</title>\r
  34 <simpara>Manage the set of repositories ("remotes") whose branches you track.</simpara>\r
  35 </simplesect>\r
  36 <simplesect id="_options">\r
  37 <title>OPTIONS</title>\r
  38 <variablelist>\r
  39 <varlistentry>\r
  40 <term>\r
  41 -v\r
  42 </term>\r
  43 <term>\r
  44 --verbose\r
  45 </term>\r
  46 <listitem>\r
  47 <simpara>\r
  48         Be a little more verbose and show remote url after name.\r
  49         NOTE: This must be placed between <emphasis>remote</emphasis> and <emphasis>subcommand</emphasis>.\r
  50 </simpara>\r
  51 </listitem>\r
  52 </varlistentry>\r
  53 </variablelist>\r
  54 </simplesect>\r
  55 <simplesect id="_commands">\r
  56 <title>COMMANDS</title>\r
  57 <simpara>With no arguments, shows a list of existing remotes.  Several\r
  58 subcommands are available to perform operations on the remotes.</simpara>\r
  59 <variablelist>\r
  60 <varlistentry>\r
  61 <term>\r
  62 <emphasis>add</emphasis>\r
  63 </term>\r
  64 <listitem>\r
  65 <simpara>\r
  66 Adds a remote named &lt;name&gt; for the repository at\r
  67 &lt;url&gt;.  The command <emphasis>git fetch &lt;name&gt;</emphasis> can then be used to create and\r
  68 update remote-tracking branches &lt;name&gt;/&lt;branch&gt;.\r
  69 </simpara>\r
  70 <simpara>With <emphasis>-f</emphasis> option, <emphasis>git fetch &lt;name&gt;</emphasis> is run immediately after\r
  71 the remote information is set up.</simpara>\r
  72 <simpara>With <emphasis>--tags</emphasis> option, <emphasis>git fetch &lt;name&gt;</emphasis> imports every tag from the\r
  73 remote repository.</simpara>\r
  74 <simpara>With <emphasis>--no-tags</emphasis> option, <emphasis>git fetch &lt;name&gt;</emphasis> does not import tags from\r
  75 the remote repository.</simpara>\r
  76 <simpara>With <emphasis>-t &lt;branch&gt;</emphasis> option, instead of the default glob\r
  77 refspec for the remote to track all branches under\r
  78 the <emphasis>refs/remotes/&lt;name&gt;/</emphasis> namespace, a refspec to track only <emphasis>&lt;branch&gt;</emphasis>\r
  79 is created.  You can give more than one <emphasis>-t &lt;branch&gt;</emphasis> to track\r
  80 multiple branches without grabbing all branches.</simpara>\r
  81 <simpara>With <emphasis>-m &lt;master&gt;</emphasis> option, a symbolic-ref <emphasis>refs/remotes/&lt;name&gt;/HEAD</emphasis> is set\r
  82 up to point at remote's <emphasis>&lt;master&gt;</emphasis> branch. See also the set-head command.</simpara>\r
  83 <simpara>When a fetch mirror is created with <emphasis>--mirror=fetch</emphasis>, the refs will not\r
  84 be stored in the <emphasis>refs/remotes/</emphasis> namespace, but rather everything in\r
  85 <emphasis>refs/</emphasis> on the remote will be directly mirrored into <emphasis>refs/</emphasis> in the\r
  86 local repository. This option only makes sense in bare repositories,\r
  87 because a fetch would overwrite any local commits.</simpara>\r
  88 <simpara>When a push mirror is created with <emphasis>--mirror=push</emphasis>, then <emphasis>git push</emphasis>\r
  89 will always behave as if <emphasis>--mirror</emphasis> was passed.</simpara>\r
  90 </listitem>\r
  91 </varlistentry>\r
  92 <varlistentry>\r
  93 <term>\r
  94 <emphasis>rename</emphasis>\r
  95 </term>\r
  96 <listitem>\r
  97 <simpara>\r
  98 Rename the remote named &lt;old&gt; to &lt;new&gt;. All remote-tracking branches and\r
  99 configuration settings for the remote are updated.\r
 100 </simpara>\r
 101 <simpara>In case &lt;old&gt; and &lt;new&gt; are the same, and &lt;old&gt; is a file under\r
 102 <emphasis>$GIT_DIR/remotes</emphasis> or <emphasis>$GIT_DIR/branches</emphasis>, the remote is converted to\r
 103 the configuration file format.</simpara>\r
 104 </listitem>\r
 105 </varlistentry>\r
 106 <varlistentry>\r
 107 <term>\r
 108 <emphasis>rm</emphasis>\r
 109 </term>\r
 110 <listitem>\r
 111 <simpara>\r
 112 Remove the remote named &lt;name&gt;. All remote-tracking branches and\r
 113 configuration settings for the remote are removed.\r
 114 </simpara>\r
 115 </listitem>\r
 116 </varlistentry>\r
 117 <varlistentry>\r
 118 <term>\r
 119 <emphasis>set-head</emphasis>\r
 120 </term>\r
 121 <listitem>\r
 122 <simpara>\r
 123 Sets or deletes the default branch (i.e. the target of the\r
 124 symbolic-ref <emphasis>refs/remotes/&lt;name&gt;/HEAD</emphasis>) for\r
 125 the named remote. Having a default branch for a remote is not required,\r
 126 but allows the name of the remote to be specified in lieu of a specific\r
 127 branch. For example, if the default branch for <emphasis>origin</emphasis> is set to\r
 128 <emphasis>master</emphasis>, then <emphasis>origin</emphasis> may be specified wherever you would normally\r
 129 specify <emphasis>origin/master</emphasis>.\r
 130 </simpara>\r
 131 <simpara>With <emphasis>-d</emphasis>, the symbolic ref <emphasis>refs/remotes/&lt;name&gt;/HEAD</emphasis> is deleted.</simpara>\r
 132 <simpara>With <emphasis>-a</emphasis>, the remote is queried to determine its <emphasis>HEAD</emphasis>, then the\r
 133 symbolic-ref <emphasis>refs/remotes/&lt;name&gt;/HEAD</emphasis> is set to the same branch. e.g., if the remote\r
 134 <emphasis>HEAD</emphasis> is pointed at <emphasis>next</emphasis>, "<emphasis>git remote set-head origin -a</emphasis>" will set\r
 135 the symbolic-ref <emphasis>refs/remotes/origin/HEAD</emphasis> to <emphasis>refs/remotes/origin/next</emphasis>. This will\r
 136 only work if <emphasis>refs/remotes/origin/next</emphasis> already exists; if not it must be\r
 137 fetched first.</simpara>\r
 138 <simpara>Use <emphasis>&lt;branch&gt;</emphasis> to set the symbolic-ref <emphasis>refs/remotes/&lt;name&gt;/HEAD</emphasis> explicitly. e.g., "git\r
 139 remote set-head origin master" will set the symbolic-ref <emphasis>refs/remotes/origin/HEAD</emphasis> to\r
 140 <emphasis>refs/remotes/origin/master</emphasis>. This will only work if\r
 141 <emphasis>refs/remotes/origin/master</emphasis> already exists; if not it must be fetched first.</simpara>\r
 142 </listitem>\r
 143 </varlistentry>\r
 144 <varlistentry>\r
 145 <term>\r
 146 <emphasis>set-branches</emphasis>\r
 147 </term>\r
 148 <listitem>\r
 149 <simpara>\r
 150 Changes the list of branches tracked by the named remote.\r
 151 This can be used to track a subset of the available remote branches\r
 152 after the initial setup for a remote.\r
 153 </simpara>\r
 154 <simpara>The named branches will be interpreted as if specified with the\r
 155 <emphasis>-t</emphasis> option on the <emphasis>git remote add</emphasis> command line.</simpara>\r
 156 <simpara>With <emphasis>--add</emphasis>, instead of replacing the list of currently tracked\r
 157 branches, adds to that list.</simpara>\r
 158 </listitem>\r
 159 </varlistentry>\r
 160 <varlistentry>\r
 161 <term>\r
 162 <emphasis>set-url</emphasis>\r
 163 </term>\r
 164 <listitem>\r
 165 <simpara>\r
 166 Changes URL remote points to. Sets first URL remote points to matching\r
 167 regex &lt;oldurl&gt; (first URL if no &lt;oldurl&gt; is given) to &lt;newurl&gt;. If\r
 168 &lt;oldurl&gt; doesn't match any URL, error occurs and nothing is changed.\r
 169 </simpara>\r
 170 <simpara>With <emphasis>--push</emphasis>, push URLs are manipulated instead of fetch URLs.</simpara>\r
 171 <simpara>With <emphasis>--add</emphasis>, instead of changing some URL, new URL is added.</simpara>\r
 172 <simpara>With <emphasis>--delete</emphasis>, instead of changing some URL, all URLs matching\r
 173 regex &lt;url&gt; are deleted. Trying to delete all non-push URLs is an\r
 174 error.</simpara>\r
 175 </listitem>\r
 176 </varlistentry>\r
 177 <varlistentry>\r
 178 <term>\r
 179 <emphasis>show</emphasis>\r
 180 </term>\r
 181 <listitem>\r
 182 <simpara>\r
 183 Gives some information about the remote &lt;name&gt;.\r
 184 </simpara>\r
 185 <simpara>With <emphasis>-n</emphasis> option, the remote heads are not queried first with\r
 186 <emphasis>git ls-remote &lt;name&gt;</emphasis>; cached information is used instead.</simpara>\r
 187 </listitem>\r
 188 </varlistentry>\r
 189 <varlistentry>\r
 190 <term>\r
 191 <emphasis>prune</emphasis>\r
 192 </term>\r
 193 <listitem>\r
 194 <simpara>\r
 195 Deletes all stale remote-tracking branches under &lt;name&gt;.\r
 196 These stale branches have already been removed from the remote repository\r
 197 referenced by &lt;name&gt;, but are still locally available in\r
 198 "remotes/&lt;name&gt;".\r
 199 </simpara>\r
 200 <simpara>With <emphasis>--dry-run</emphasis> option, report what branches will be pruned, but do not\r
 201 actually prune them.</simpara>\r
 202 </listitem>\r
 203 </varlistentry>\r
 204 <varlistentry>\r
 205 <term>\r
 206 <emphasis>update</emphasis>\r
 207 </term>\r
 208 <listitem>\r
 209 <simpara>\r
 210 Fetch updates for a named set of remotes in the repository as defined by\r
 211 remotes.&lt;group&gt;.  If a named group is not specified on the command line,\r
 212 the configuration parameter remotes.default will be used; if\r
 213 remotes.default is not defined, all remotes which do not have the\r
 214 configuration parameter remote.&lt;name&gt;.skipDefaultUpdate set to true will\r
 215 be updated.  (See <xref linkend="git-config(1)" />).\r
 216 </simpara>\r
 217 <simpara>With <emphasis>--prune</emphasis> option, prune all the remotes that are updated.</simpara>\r
 218 </listitem>\r
 219 </varlistentry>\r
 220 </variablelist>\r
 221 </simplesect>\r
 222 <simplesect id="_discussion">\r
 223 <title>DISCUSSION</title>\r
 224 <simpara>The remote configuration is achieved using the <emphasis>remote.origin.url</emphasis> and\r
 225 <emphasis>remote.origin.fetch</emphasis> configuration variables.  (See\r
 226 <xref linkend="git-config(1)" />).</simpara>\r
 227 </simplesect>\r
 228 <simplesect id="_examples">\r
 229 <title>Examples</title>\r
 230 <itemizedlist>\r
 231 <listitem>\r
 232 <simpara>\r
 233 Add a new remote, fetch, and check out a branch from it\r
 234 </simpara>\r
 235 <screen>$ git remote\r
 236 origin\r
 237 $ git branch -r\r
 238 origin/master\r
 239 $ git remote add linux-nfs git://linux-nfs.org/pub/linux/nfs-2.6.git\r
 240 $ git remote\r
 241 linux-nfs\r
 242 origin\r
 243 $ git fetch\r
 244 * refs/remotes/linux-nfs/master: storing branch 'master' ...\r
 245   commit: bf81b46\r
 246 $ git branch -r\r
 247 origin/master\r
 248 linux-nfs/master\r
 249 $ git checkout -b nfs linux-nfs/master\r
 250 ...</screen>\r
 251 </listitem>\r
 252 <listitem>\r
 253 <simpara>\r
 254 Imitate <emphasis>git clone</emphasis> but track only selected branches\r
 255 </simpara>\r
 256 <screen>$ mkdir project.git\r
 257 $ cd project.git\r
 258 $ git init\r
 259 $ git remote add -f -t master -m master origin git://example.com/git.git/\r
 260 $ git merge origin</screen>\r
 261 </listitem>\r
 262 </itemizedlist>\r
 263 </simplesect>\r
 264 <simplesect id="_see_also">\r
 265 <title>SEE ALSO</title>\r
 266 <simpara><xref linkend="git-fetch(1)" />\r
 267 <xref linkend="git-branch(1)" />\r
 268 <xref linkend="git-config(1)" /></simpara>\r
 269 </simplesect>\r
 270 <simplesect id="_git">\r
 271 <title>GIT</title>\r
 272 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 273 </simplesect>\r
 274 </article>\r