Documentation/git-clone.txt

   1 git-clone(1)
   2 ============
   3
   4 NAME
   5 ----
   6 git-clone - Clone a repository into a new directory
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 `git clone` [++--template=++__<template-directory>__]
  13           [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
  14           [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
  15           [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
  16           [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
  17           [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
  18           [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
  19           [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
  20           [_<directory>_]
  21
  22 DESCRIPTION
  23 -----------
  24
  25 Clones a repository into a newly created directory, creates
  26 remote-tracking branches for each branch in the cloned repository
  27 (visible using `git branch --remotes`), and creates and checks out an
  28 initial branch that is forked from the cloned repository's
  29 currently active branch.
  30
  31 After the clone, a plain `git fetch` without arguments will update
  32 all the remote-tracking branches, and a `git pull` without
  33 arguments will in addition merge the remote master branch into the
  34 current master branch, if any (this is untrue when `--single-branch`
  35 is given; see below).
  36
  37 This default configuration is achieved by creating references to
  38 the remote branch heads under `refs/remotes/origin` and
  39 by initializing `remote.origin.url` and `remote.origin.fetch`
  40 configuration variables.
  41
  42
  43 OPTIONS
  44 -------
  45 `-l`::
  46 `--local`::
  47         When the repository to clone from is on a local machine,
  48         this flag bypasses the normal "Git aware" transport
  49         mechanism and clones the repository by making a copy of
  50         `HEAD` and everything under objects and refs directories.
  51         The files under `.git/objects/` directory are hardlinked
  52         to save space when possible.
  53 +
  54 If the repository is specified as a local path (e.g., `/path/to/repo`),
  55 this is the default, and --local is essentially a no-op.  If the
  56 repository is specified as a URL, then this flag is ignored (and we
  57 never use the local optimizations).  Specifying `--no-local` will
  58 override the default when `/path/to/repo` is given, using the regular
  59 Git transport instead.
  60 +
  61 If the repository's `$GIT_DIR/objects` has symbolic links or is a
  62 symbolic link, the clone will fail. This is a security measure to
  63 prevent the unintentional copying of files by dereferencing the symbolic
  64 links.
  65 +
  66 *NOTE*: this operation can race with concurrent modification to the
  67 source repository, similar to running `cp -r src dst` while modifying
  68 `src`.
  69
  70 `--no-hardlinks`::
  71         Force the cloning process from a repository on a local
  72         filesystem to copy the files under the `.git/objects`
  73         directory instead of using hardlinks. This may be desirable
  74         if you are trying to make a back-up of your repository.
  75
  76 `-s`::
  77 `--shared`::
  78         When the repository to clone is on the local machine,
  79         instead of using hard links, automatically setup
  80         `.git/objects/info/alternates` to share the objects
  81         with the source repository.  The resulting repository
  82         starts out without any object of its own.
  83 +
  84 *NOTE*: this is a possibly dangerous operation; do *not* use
  85 it unless you understand what it does. If you clone your
  86 repository using this option and then delete branches (or use any
  87 other Git command that makes any existing commit unreferenced) in the
  88 source repository, some objects may become unreferenced (or dangling).
  89 These objects may be removed by normal Git operations (such as `git commit`)
  90 which automatically call `git maintenance run --auto`. (See
  91 linkgit:git-maintenance[1].) If these objects are removed and were referenced
  92 by the cloned repository, then the cloned repository will become corrupt.
  93 +
  94 Note that running `git repack` without the `--local` option in a repository
  95 cloned with `--shared` will copy objects from the source repository into a pack
  96 in the cloned repository, removing the disk space savings of `clone --shared`.
  97 It is safe, however, to run `git gc`, which uses the `--local` option by
  98 default.
  99 +
 100 If you want to break the dependency of a repository cloned with `--shared` on
 101 its source repository, you can simply run `git repack -a` to copy all
 102 objects from the source repository into a pack in the cloned repository.
 103
 104 `--reference`[`-if-able`] _<repository>_::
 105         If the reference _<repository>_ is on the local machine,
 106         automatically setup `.git/objects/info/alternates` to
 107         obtain objects from the reference _<repository>_.  Using
 108         an already existing repository as an alternate will
 109         require fewer objects to be copied from the repository
 110         being cloned, reducing network and local storage costs.
 111         When using the `--reference-if-able`, a non existing
 112         directory is skipped with a warning instead of aborting
 113         the clone.
 114 +
 115 *NOTE*: see the NOTE for the `--shared` option, and also the
 116 `--dissociate` option.
 117
 118 `--dissociate`::
 119         Borrow the objects from reference repositories specified
 120         with the `--reference` options only to reduce network
 121         transfer, and stop borrowing from them after a clone is made
 122         by making necessary local copies of borrowed objects.  This
 123         option can also be used when cloning locally from a
 124         repository that already borrows objects from another
 125         repository--the new repository will borrow objects from the
 126         same repository, and this option can be used to stop the
 127         borrowing.
 128
 129 `-q`::
 130 `--quiet`::
 131         Operate quietly.  Progress is not reported to the standard
 132         error stream.
 133
 134 `-v`::
 135 `--verbose`::
 136         Run verbosely. Does not affect the reporting of progress status
 137         to the standard error stream.
 138
 139 `--progress`::
 140         Progress status is reported on the standard error stream
 141         by default when it is attached to a terminal, unless `--quiet`
 142         is specified. This flag forces progress status even if the
 143         standard error stream is not directed to a terminal.
 144
 145 ++--server-option=++__<option>__::
 146         Transmit the given string to the server when communicating using
 147         protocol version 2.  The given string must not contain a NUL or LF
 148         character.  The server's handling of server options, including
 149         unknown ones, is server-specific.
 150         When multiple ++--server-option=++__<option>__ are given, they are all
 151         sent to the other side in the order listed on the command line.
 152
 153 `-n`::
 154 `--no-checkout`::
 155         No checkout of HEAD is performed after the clone is complete.
 156
 157 `--`[`no-`]`reject-shallow`::
 158         Fail if the source repository is a shallow repository.
 159         The `clone.rejectShallow` configuration variable can be used to
 160         specify the default.
 161
 162 `--bare`::
 163         Make a 'bare' Git repository.  That is, instead of
 164         creating _<directory>_ and placing the administrative
 165         files in _<directory>_`/.git`, make the _<directory>_
 166         itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
 167         because there is nowhere to check out the working tree.
 168         Also the branch heads at the remote are copied directly
 169         to corresponding local branch heads, without mapping
 170         them to `refs/remotes/origin/`.  When this option is
 171         used, neither remote-tracking branches nor the related
 172         configuration variables are created.
 173
 174 `--sparse`::
 175         Employ a sparse-checkout, with only files in the toplevel
 176         directory initially being present.  The
 177         linkgit:git-sparse-checkout[1] command can be used to grow the
 178         working directory as needed.
 179
 180 ++--filter=++__<filter-spec>__::
 181         Use the partial clone feature and request that the server sends
 182         a subset of reachable objects according to a given object filter.
 183         When using `--filter`, the supplied _<filter-spec>_ is used for
 184         the partial clone filter. For example, `--filter=blob:none` will
 185         filter out all blobs (file contents) until needed by Git. Also,
 186         ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
 187         at least _<size>_. For more details on filter specifications, see
 188         the `--filter` option in linkgit:git-rev-list[1].
 189
 190 `--also-filter-submodules`::
 191         Also apply the partial clone filter to any submodules in the repository.
 192         Requires `--filter` and `--recurse-submodules`. This can be turned on by
 193         default by setting the `clone.filterSubmodules` config option.
 194
 195 `--mirror`::
 196         Set up a mirror of the source repository.  This implies `--bare`.
 197         Compared to `--bare`, `--mirror` not only maps local branches of the
 198         source to local branches of the target, it maps all refs (including
 199         remote-tracking branches, notes etc.) and sets up a refspec configuration such
 200         that all these refs are overwritten by a `git remote update` in the
 201         target repository.
 202
 203 `-o` _<name>_::
 204 `--origin` _<name>_::
 205         Instead of using the remote name `origin` to keep track of the upstream
 206         repository, use _<name>_.  Overrides `clone.defaultRemoteName` from the
 207         config.
 208
 209 `-b` _<name>_::
 210 `--branch` _<name>_::
 211         Instead of pointing the newly created HEAD to the branch pointed
 212         to by the cloned repository's HEAD, point to _<name>_ branch
 213         instead. In a non-bare repository, this is the branch that will
 214         be checked out.
 215         `--branch` can also take tags and detaches the HEAD at that commit
 216         in the resulting repository.
 217
 218 `-u` _<upload-pack>_::
 219 `--upload-pack` _<upload-pack>_::
 220         When given, and the repository to clone from is accessed
 221         via ssh, this specifies a non-default path for the command
 222         run on the other end.
 223
 224 ++--template=++__<template-directory>__::
 225         Specify the directory from which templates will be used;
 226         (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 227
 228 `-c` __<key>__++=++__<value>__::
 229 `--config` __<key>__++=++__<value>__::
 230         Set a configuration variable in the newly-created repository;
 231         this takes effect immediately after the repository is
 232         initialized, but before the remote history is fetched or any
 233         files checked out.  The _<key>_ is in the same format as expected by
 234         linkgit:git-config[1] (e.g., `core.eol=true`). If multiple
 235         values are given for the same key, each value will be written to
 236         the config file. This makes it safe, for example, to add
 237         additional fetch refspecs to the origin remote.
 238 +
 239 Due to limitations of the current implementation, some configuration
 240 variables do not take effect until after the initial fetch and checkout.
 241 Configuration variables known to not take effect are:
 242 ++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
 243 corresponding `--mirror` and `--no-tags` options instead.
 244
 245 `--depth` _<depth>_::
 246         Create a 'shallow' clone with a history truncated to the
 247         specified number of commits. Implies `--single-branch` unless
 248         `--no-single-branch` is given to fetch the histories near the
 249         tips of all branches. If you want to clone submodules shallowly,
 250         also pass `--shallow-submodules`.
 251
 252 ++--shallow-since=++__<date>__::
 253         Create a shallow clone with a history after the specified time.
 254
 255 ++--shallow-exclude=++__<revision>__::
 256         Create a shallow clone with a history, excluding commits
 257         reachable from a specified remote branch or tag.  This option
 258         can be specified multiple times.
 259
 260 `--`[`no-`]`single-branch`::
 261         Clone only the history leading to the tip of a single branch,
 262         either specified by the `--branch` option or the primary
 263         branch remote's `HEAD` points at.
 264         Further fetches into the resulting repository will only update the
 265         remote-tracking branch for the branch this option was used for the
 266         initial cloning.  If the `HEAD` at the remote did not point at any
 267         branch when `--single-branch` clone was made, no remote-tracking
 268         branch is created.
 269
 270 `--no-tags`::
 271         Don't clone any tags, and set
 272         `remote.<remote>.tagOpt=--no-tags` in the config, ensuring
 273         that future `git pull` and `git fetch` operations won't follow
 274         any tags. Subsequent explicit tag fetches will still work,
 275         (see linkgit:git-fetch[1]).
 276 +
 277 Can be used in conjunction with `--single-branch` to clone and
 278 maintain a branch with no references other than a single cloned
 279 branch. This is useful e.g. to maintain minimal clones of the default
 280 branch of some repository for search indexing.
 281
 282 `--recurse-submodules`[`=`{empty}__<pathspec>__]::
 283         After the clone is created, initialize and clone submodules
 284         within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
 285         provided, all submodules are initialized and cloned.
 286         This option can be given multiple times for pathspecs consisting
 287         of multiple entries.  The resulting clone has `submodule.active` set to
 288         the provided pathspec, or "." (meaning all submodules) if no
 289         pathspec is provided.
 290 +
 291 Submodules are initialized and cloned using their default settings. This is
 292 equivalent to running
 293 `git submodule update --init --recursive <pathspec>` immediately after
 294 the clone is finished. This option is ignored if the cloned repository does
 295 not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
 296 or `--mirror` is given)
 297
 298 `--`[`no-`]`shallow-submodules`::
 299         All submodules which are cloned will be shallow with a depth of 1.
 300
 301 `--`[`no-`]`remote-submodules`::
 302         All submodules which are cloned will use the status of the submodule's
 303         remote-tracking branch to update the submodule, rather than the
 304         superproject's recorded SHA-1. Equivalent to passing `--remote` to
 305         `git submodule update`.
 306
 307 `--separate-git-dir=`{empty}__<git-dir>__::
 308         Instead of placing the cloned repository where it is supposed
 309         to be, place the cloned repository at the specified directory,
 310         then make a filesystem-agnostic Git symbolic link to there.
 311         The result is Git repository can be separated from working
 312         tree.
 313
 314 `--ref-format=`{empty}__<ref-format>__::
 315
 316 Specify the given ref storage format for the repository. The valid values are:
 317 +
 318 include::ref-storage-format.txt[]
 319
 320 `-j` _<n>_::
 321 `--jobs` _<n>_::
 322         The number of submodules fetched at the same time.
 323         Defaults to the `submodule.fetchJobs` option.
 324
 325 _<repository>_::
 326         The (possibly remote) _<repository>_ to clone from.  See the
 327         <<URLS,GIT URLS>> section below for more information on specifying
 328         repositories.
 329
 330 _<directory>_::
 331         The name of a new directory to clone into.  The "humanish"
 332         part of the source repository is used if no _<directory>_ is
 333         explicitly given (`repo` for `/path/to/repo.git` and `foo`
 334         for `host.xz:foo/.git`).  Cloning into an existing directory
 335         is only allowed if the directory is empty.
 336
 337 `--bundle-uri=`{empty}__<uri>__::
 338         Before fetching from the remote, fetch a bundle from the given
 339         _<uri>_ and unbundle the data into the local repository. The refs
 340         in the bundle will be stored under the hidden `refs/bundle/*`
 341         namespace. This option is incompatible with `--depth`,
 342         `--shallow-since`, and `--shallow-exclude`.
 343
 344 :git-clone: 1
 345 include::urls.txt[]
 346
 347 EXAMPLES
 348 --------
 349
 350 * Clone from upstream:
 351 +
 352 ------------
 353 $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
 354 $ cd my-linux
 355 $ make
 356 ------------
 357
 358
 359 * Make a local clone that borrows from the current directory, without checking things out:
 360 +
 361 ------------
 362 $ git clone -l -s -n . ../copy
 363 $ cd ../copy
 364 $ git show-branch
 365 ------------
 366
 367
 368 * Clone from upstream while borrowing from an existing local directory:
 369 +
 370 ------------
 371 $ git clone --reference /git/linux.git \
 372         git://git.kernel.org/pub/scm/.../linux.git \
 373         my-linux
 374 $ cd my-linux
 375 ------------
 376
 377
 378 * Create a bare repository to publish your changes to the public:
 379 +
 380 ------------
 381 $ git clone --bare -l /home/proj/.git /pub/scm/proj.git
 382 ------------
 383
 384 CONFIGURATION
 385 -------------
 386
 387 include::includes/cmd-config-section-all.txt[]
 388
 389 include::config/init.txt[]
 390
 391 include::config/clone.txt[]
 392
 393
 394 GIT
 395 ---
 396 Part of the linkgit:git[1] suite