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