Merge branch 'ew/rebase'
[git/git.git] / Documentation / git-clone.txt
1 git-clone(1)
2 ============
3
4 NAME
5 ----
6 git-clone - Clones a repository
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare]
13 [-o <name>] [-u <upload-pack>] [--reference <repository>]
14 [--use-separate-remote] <repository> [<directory>]
15
16 DESCRIPTION
17 -----------
18 Clones a repository into a newly created directory. All remote
19 branch heads are copied under `$GIT_DIR/refs/heads/`, except
20 that the remote `master` is also copied to `origin` branch.
21
22 In addition, `$GIT_DIR/remotes/origin` file is set up to have
23 this line:
24
25 Pull: master:origin
26
27 This is to help the typical workflow of working off of the
28 remote `master` branch. Every time `git pull` without argument
29 is run, the progress on the remote `master` branch is tracked by
30 copying it into the local `origin` branch, and merged into the
31 branch you are currently working on. Remote branches other than
32 `master` are also added there to be tracked.
33
34
35 OPTIONS
36 -------
37 --local::
38 -l::
39 When the repository to clone from is on a local machine,
40 this flag bypasses normal "git aware" transport
41 mechanism and clones the repository by making a copy of
42 HEAD and everything under objects and refs directories.
43 The files under .git/objects/ directory are hardlinked
44 to save space when possible.
45
46 --shared::
47 -s::
48 When the repository to clone is on the local machine,
49 instead of using hard links, automatically setup
50 .git/objects/info/alternates to share the objects
51 with the source repository. The resulting repository
52 starts out without any object of its own.
53
54 --reference <repository>::
55 If the reference repository is on the local machine
56 automatically setup .git/objects/info/alternates to
57 obtain objects from the reference repository. Using
58 an already existing repository as an alternate will
59 require less objects to be copied from the repository
60 being cloned, reducing network and local storage costs.
61
62 --quiet::
63 -q::
64 Operate quietly. This flag is passed to "rsync" and
65 "git-fetch-pack" commands when given.
66
67 -n::
68 No checkout of HEAD is performed after the clone is complete.
69
70 --bare::
71 Make a 'bare' GIT repository. That is, instead of
72 creating `<directory>` and placing the administrative
73 files in `<directory>/.git`, make the `<directory>`
74 itself the `$GIT_DIR`. This implies `-n` option. When
75 this option is used, neither the `origin` branch nor the
76 default `remotes/origin` file is created.
77
78 -o <name>::
79 Instead of using the branch name 'origin' to keep track
80 of the upstream repository, use <name> instead. Note
81 that the shorthand name stored in `remotes/origin` is
82 not affected, but the local branch name to pull the
83 remote `master` branch into is.
84
85 --upload-pack <upload-pack>::
86 -u <upload-pack>::
87 When given, and the repository to clone from is handled
88 by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
89 the command to specify non-default path for the command
90 run on the other end.
91
92 --template=<template_directory>::
93 Specify the directory from which templates will be used;
94 if unset the templates are taken from the installation
95 defined default, typically `/usr/share/git-core/templates`.
96
97 --use-separate-remote::
98 Save remotes heads under `$GIT_DIR/remotes/origin/` instead
99 of `$GIT_DIR/refs/heads/`. Only the master branch is saved
100 in the latter.
101
102 <repository>::
103 The (possibly remote) repository to clone from. It can
104 be any URL git-fetch supports.
105
106 <directory>::
107 The name of a new directory to clone into. The "humanish"
108 part of the source repository is used if no directory is
109 explicitly given ("repo" for "/path/to/repo.git" and "foo"
110 for "host.xz:foo/.git"). Cloning into an existing directory
111 is not allowed.
112
113 Examples
114 --------
115
116 Clone from upstream::
117 +
118 ------------
119 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
120 $ cd my2.6
121 $ make
122 ------------
123
124
125 Make a local clone that borrows from the current directory, without checking things out::
126 +
127 ------------
128 $ git clone -l -s -n . ../copy
129 $ cd copy
130 $ git show-branch
131 ------------
132
133
134 Clone from upstream while borrowing from an existing local directory::
135 +
136 ------------
137 $ git clone --reference my2.6 \
138 git://git.kernel.org/pub/scm/.../linux-2.7 \
139 my2.7
140 $ cd my2.7
141 ------------
142
143
144 Create a bare repository to publish your changes to the public::
145 +
146 ------------
147 $ git clone --bare -l /home/proj/.git /pub/scm/proj.git
148 ------------
149
150
151 Create a repository on the kernel.org machine that borrows from Linus::
152 +
153 ------------
154 $ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \
155 /pub/scm/.../me/subsys-2.6.git
156 ------------
157
158
159 Author
160 ------
161 Written by Linus Torvalds <torvalds@osdl.org>
162
163
164 Documentation
165 --------------
166 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
167
168
169 GIT
170 ---
171 Part of the gitlink:git[7] suite
172