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