[PATCH] fetch/pull: short-hand notation for remote repositories.
[git/git.git] / Documentation / git.txt
CommitLineData
7984eabe 1git(7)
2cf565c5 2======
6c84e2e0 3May 2005
2cf565c5
DG
4
5NAME
6----
7git - the stupid content tracker
8
9
10SYNOPSIS
11--------
12'git-<command>' <args>
13
14DESCRIPTION
15-----------
16
17This is reference information for the core git commands.
18
6c84e2e0
DG
19The Discussion section below contains much useful definition and
20clarification info - read that first. And of the commands, I suggest
21reading link:git-update-cache.html[git-update-cache] and
22link:git-read-tree.html[git-read-tree] first - I wish I had!
2cf565c5
DG
23
24David Greaves <david@dgreaves.com>
2508/05/05
26
27Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
28reflect recent changes.
29
30Commands Overview
31-----------------
32The git commands can helpfully be split into those that manipulate
2f2de9b4
JH
33the repository, the cache and the working fileset, those that
34interrogate and compare them, and those that moves objects and
35references between repositories.
2cf565c5 36
204ee6a9
DG
37There are also some ancilliary programs that can be viewed as useful
38aids for using the core commands but which are unlikely to be used by
39SCMs layered over git.
40
2cf565c5
DG
41Manipulation commands
42~~~~~~~~~~~~~~~~~~~~~
2cf565c5
DG
43link:git-checkout-cache.html[git-checkout-cache]::
44 Copy files from the cache to the working directory
45
46link:git-commit-tree.html[git-commit-tree]::
47 Creates a new commit object
48
2cf565c5
DG
49link:git-init-db.html[git-init-db]::
50 Creates an empty git object database
51
2cf565c5
DG
52link:git-merge-base.html[git-merge-base]::
53 Finds as good a common ancestor as possible for a merge
54
2cf565c5
DG
55link:git-mktag.html[git-mktag]::
56 Creates a tag object
57
2cf565c5
DG
58link:git-read-tree.html[git-read-tree]::
59 Reads tree information into the directory cache
60
2cf565c5
DG
61link:git-update-cache.html[git-update-cache]::
62 Modifies the index or directory cache
63
7672db20
BL
64link:git-hash-object.html[git-hash-object]::
65 Computes the object ID from a file.
2cf565c5
DG
66
67link:git-write-tree.html[git-write-tree]::
68 Creates a tree from the current cache
69
70Interrogation commands
71~~~~~~~~~~~~~~~~~~~~~~
72link:git-cat-file.html[git-cat-file]::
73 Provide content or type information for repository objects
74
75link:git-check-files.html[git-check-files]::
76 Verify a list of files are up-to-date
77
78link:git-diff-cache.html[git-diff-cache]::
79 Compares content and mode of blobs between the cache and repository
80
81link:git-diff-files.html[git-diff-files]::
82 Compares files in the working tree and the cache
83
84link:git-diff-tree.html[git-diff-tree]::
85 Compares the content and mode of blobs found via two tree objects
86
2cf565c5
DG
87link:git-export.html[git-export]::
88 Exports each commit and a diff against each of its parents
89
90link:git-fsck-cache.html[git-fsck-cache]::
91 Verifies the connectivity and validity of the objects in the database
92
93link:git-ls-files.html[git-ls-files]::
94 Information about files in the cache/working directory
95
96link:git-ls-tree.html[git-ls-tree]::
97 Displays a tree object in human readable form
98
99link:git-merge-cache.html[git-merge-cache]::
100 Runs a merge for files needing merging
101
102link:git-rev-list.html[git-rev-list]::
103 Lists commit objects in reverse chronological order
104
105link:git-rev-tree.html[git-rev-tree]::
106 Provides the revision tree for one or more commits
107
2cf565c5
DG
108link:git-tar-tree.html[git-tar-tree]::
109 Creates a tar archive of the files in the named tree
110
111link:git-unpack-file.html[git-unpack-file]::
112 Creates a temporary file with a blob's contents
113
aed022ab
EB
114link:git-var.html[git-var]::
115 Displays a git logical variable
116
f9253394
JH
117link:git-verify-pack.html[git-verify-pack]::
118 Validates packed GIT archive files
119
2cf565c5
DG
120The interrogate commands may create files - and you can force them to
121touch the working file set - but in general they don't
122
123
6ec311da
JH
124link:git-clone-script.html[git-clone-script]::
125 Clones a repository into the current repository (user interface)
126
127link:git-clone-pack.html[git-clone-pack]::
128 Clones a repository into the current repository (engine
129 for ssh and local transport)
130
2f2de9b4
JH
131link:git-pull-script.html[git-pull-script]::
132 Pull from a repote repository via various protocols
133 (user interface).
134
204ee6a9
DG
135link:git-http-pull.html[git-http-pull]::
136 Downloads a remote GIT repository via HTTP
137
138link:git-local-pull.html[git-local-pull]::
139 Duplicates another GIT repository on a local system
140
2f2de9b4
JH
141link:git-ssh-pull.html[git-ssh-pull]::
142 Pulls from a remote repository over ssh connection
143
144link:git-send-pack.html[git-send-pack]::
145 Pushes to a remote repository, intelligently.
146
147link:git-receive-pack.html[git-receive-pack]::
148 Invoked by 'git-send-pack' to receive what is pushed to it.
149
150link:git-clone-pack.html[git-clone-pack]::
151 Clones from a remote repository.
152
153link:git-fetch-pack.html[git-fetch-pack]::
154 Updates from a remote repository.
155
156link:git-upload-pack.html[git-upload-pack]::
157 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
158 what are asked for.
159
160
161Ancilliary Commands
162-------------------
163Manipulators:
164
165link:git-apply-patch-script.html[git-apply-patch-script]::
166 Sample script to apply the diffs from git-diff-*
167
168link:git-convert-cache.html[git-convert-cache]::
169 Converts old-style GIT repository
170
204ee6a9
DG
171link:git-merge-one-file-script.html[git-merge-one-file-script]::
172 The standard helper program to use with "git-merge-cache"
173
204ee6a9
DG
174link:git-prune-script.html[git-prune-script]::
175 Prunes all unreachable objects from the object database
176
177link:git-resolve-script.html[git-resolve-script]::
178 Script used to merge two trees
179
180link:git-tag-script.html[git-tag-script]::
181 An example script to create a tag object signed with GPG
182
204ee6a9
DG
183
184Interogators:
185
99665af5 186link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
187 Generates patch format output for git-diff-*
188
418aaf84
JH
189link:git-ssh-push.html[git-ssh-push]::
190 Helper "server-side" program used by git-ssh-pull
204ee6a9
DG
191
192
193
6c84e2e0 194Identifier Terminology
2cf565c5
DG
195----------------------
196<object>::
6c84e2e0 197 Indicates the sha1 identifier for any type of object
2cf565c5
DG
198
199<blob>::
200 Indicates a blob object sha1 identifier
201
202<tree>::
203 Indicates a tree object sha1 identifier
204
205<commit>::
206 Indicates a commit object sha1 identifier
207
208<tree-ish>::
6c84e2e0
DG
209 Indicates a tree, commit or tag object sha1 identifier. A
210 command that takes a <tree-ish> argument ultimately wants to
211 operate on a <tree> object but automatically dereferences
212 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
213
214<type>::
215 Indicates that an object type is required.
216 Currently one of: blob/tree/commit/tag
217
218<file>::
219 Indicates a filename - always relative to the root of
220 the tree structure GIT_INDEX_FILE describes.
221
c1bdacf9
DG
222Symbolic Identifiers
223--------------------
6c84e2e0
DG
224Any git comand accepting any <object> can also use the following
225symbolic notation:
c1bdacf9
DG
226
227HEAD::
6c84e2e0
DG
228 indicates the head of the repository (ie the contents of
229 `$GIT_DIR/HEAD`)
c1bdacf9
DG
230<tag>::
231 a valid tag 'name'+
232 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
233<head>::
234 a valid head 'name'+
235 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
236<snap>::
237 a valid snapshot 'name'+
238 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
239
240
241File/Directory Structure
242------------------------
243The git-core manipulates the following areas in the directory:
244
245 .git/ The base (overridden with $GIT_DIR)
246 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
2f2de9b4
JH
247 ??/ 'First 2 chars of object' directories.
248 pack/ Packed archives.
c1bdacf9
DG
249
250 refs/ Directories containing symbolic names for objects
251 (each file contains the hex SHA1 + newline)
252 heads/ Commits which are heads of various sorts
253 tags/ Tags, by the tag name (or some local renaming of it)
2f2de9b4
JH
254 */ Any other subdirectory of refs/ can be used to store
255 files similar to what are under refs/heads/.
256 HEAD Symlink to refs/heads/<current-branch-name>
c1bdacf9
DG
257
258Higher level SCMs may provide and manage additional information in the
259GIT_DIR.
260
2cf565c5
DG
261Terminology
262-----------
6c84e2e0 263Each line contains terms which you may see used interchangeably
2cf565c5
DG
264
265 object database, .git directory
266 directory cache, index
267 id, sha1, sha1-id, sha1 hash
268 type, tag
2cf565c5
DG
269
270
271Environment Variables
272---------------------
273Various git commands use the following environment variables:
274
c1bdacf9
DG
275The git Repository
276~~~~~~~~~~~~~~~~~~
277These environment variables apply to 'all' core git commands. Nb: it
278is worth noting that they may be used/overridden by SCMS sitting above
279git so take care if using Cogito etc
280
281'GIT_INDEX_FILE'::
282 This environment allows the specification of an alternate
283 cache/index file. If not specified, the default of
284 `$GIT_DIR/index` is used.
285
286'GIT_OBJECT_DIRECTORY'::
287 If the object storage directory is specified via this
288 environment variable then the sha1 directories are created
289 underneath - otherwise the default `$GIT_DIR/objects`
290 directory is used.
291
292'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
293 Due to the immutable nature of git objects, old objects can be
294 archived into shared, read-only directories. This variable
295 specifies a ":" seperated list of git object directories which
296 can be used to search for git objects. New objects will not be
297 written to these directories.
298
299'GIT_DIR'::
300 If the 'GIT_DIR' environment variable is set then it specifies
301 a path to use instead of `./.git` for the base of the
302 repository.
303
304git Commits
305~~~~~~~~~~~
306'GIT_AUTHOR_NAME'::
307'GIT_AUTHOR_EMAIL'::
308'GIT_AUTHOR_DATE'::
309'GIT_COMMITTER_NAME'::
310'GIT_COMMITTER_EMAIL'::
311 see link:git-commit-tree.html[git-commit-tree]
312
313git Diffs
314~~~~~~~~~
d81ed1b5
JH
315'GIT_DIFF_OPTS'::
316'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
317 see the "generating patches" section in :
318 link:git-diff-cache.html[git-diff-cache];
319 link:git-diff-files.html[git-diff-files];
320 link:git-diff-tree.html[git-diff-tree]
2cf565c5 321
6c84e2e0
DG
322Discussion
323----------
324include::../README[]
325
2cf565c5
DG
326Author
327------
6c84e2e0 328Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
329
330Documentation
331--------------
332Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
333
334GIT
335---
336Part of the link:git.html[git] suite
337