The twelfth batch
[alt-git.git] / Documentation / git-clone.txt
blobf90977a8519b4c9c057438afa042b4bd25855567
1 git-clone(1)
2 ============
4 NAME
5 ----
6 git-clone - Clone a repository into a new directory
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>]
22 DESCRIPTION
23 -----------
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.
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).
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.
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.
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.
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.
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`.
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.
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.
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.
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.
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.
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.
115 *NOTE*: see the NOTE for the `--shared` option, and also the
116 `--dissociate` option.
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.
129 -q::
130 --quiet::
131         Operate quietly.  Progress is not reported to the standard
132         error stream.
134 -v::
135 --verbose::
136         Run verbosely. Does not affect the reporting of progress status
137         to the standard error stream.
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.
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.
153 -n::
154 --no-checkout::
155         No checkout of HEAD is performed after the clone is complete.
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.
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.
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.
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].
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.
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.
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.
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.
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.
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].)
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.
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.
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`.
252 --shallow-since=<date>::
253         Create a shallow clone with a history after the specified time.
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.
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.
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]).
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.
282 --recurse-submodules[=<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.
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)
298 --[no-]shallow-submodules::
299         All submodules which are cloned will be shallow with a depth of 1.
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`.
307 --separate-git-dir=<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.
314 --ref-format=<ref-format>::
316 Specify the given ref storage format for the repository. The valid values are:
318 include::ref-storage-format.txt[]
320 -j <n>::
321 --jobs <n>::
322         The number of submodules fetched at the same time.
323         Defaults to the `submodule.fetchJobs` option.
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.
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.
337 --bundle-uri=<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`.
344 :git-clone: 1
345 include::urls.txt[]
347 EXAMPLES
348 --------
350 * Clone from upstream:
352 ------------
353 $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
354 $ cd my-linux
355 $ make
356 ------------
359 * Make a local clone that borrows from the current directory, without checking things out:
361 ------------
362 $ git clone -l -s -n . ../copy
363 $ cd ../copy
364 $ git show-branch
365 ------------
368 * Clone from upstream while borrowing from an existing local directory:
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 ------------
378 * Create a bare repository to publish your changes to the public:
380 ------------
381 $ git clone --bare -l /home/proj/.git /pub/scm/proj.git
382 ------------
384 CONFIGURATION
385 -------------
387 include::includes/cmd-config-section-all.txt[]
389 include::config/init.txt[]
391 include::config/clone.txt[]
396 Part of the linkgit:git[1] suite