'git bisect visualize'
[git/git.git] / Documentation / git.txt
CommitLineData
7984eabe 1git(7)
2cf565c5 2======
905197de 3v0.99.5, Aug 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
0d6a873c
JH
19Before reading this cover to cover, you may want to take a look
20at the link:tutorial.html[tutorial] document.
21
6c84e2e0
DG
22The Discussion section below contains much useful definition and
23clarification info - read that first. And of the commands, I suggest
24reading link:git-update-cache.html[git-update-cache] and
25link:git-read-tree.html[git-read-tree] first - I wish I had!
2cf565c5 26
e6fc2346
JH
27After you get the general feel from the tutorial and this
28overview page, you may want to take a look at the
29link:howto-index.html[howto] documents.
30
31
2cf565c5
DG
32David Greaves <david@dgreaves.com>
3308/05/05
34
35Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
36reflect recent changes.
37
38Commands Overview
39-----------------
40The git commands can helpfully be split into those that manipulate
2f2de9b4
JH
41the repository, the cache and the working fileset, those that
42interrogate and compare them, and those that moves objects and
43references between repositories.
2cf565c5 44
62033318
JH
45In addition, git itself comes with a spartan set of porcelain
46commands. They are usable but are not meant to compete with real
47Porcelains.
48
90933efb 49There are also some ancillary programs that can be viewed as useful
204ee6a9
DG
50aids for using the core commands but which are unlikely to be used by
51SCMs layered over git.
52
2cf565c5
DG
53Manipulation commands
54~~~~~~~~~~~~~~~~~~~~~
f85a4191
JH
55link:git-apply.html[git-apply]::
56 Reads a "diff -up1" or git generated patch file and
57 applies it to the working tree.
58
2cf565c5
DG
59link:git-checkout-cache.html[git-checkout-cache]::
60 Copy files from the cache to the working directory
61
62link:git-commit-tree.html[git-commit-tree]::
63 Creates a new commit object
64
f85a4191
JH
65link:git-hash-object.html[git-hash-object]::
66 Computes the object ID from a file.
67
2cf565c5
DG
68link:git-init-db.html[git-init-db]::
69 Creates an empty git object database
70
f85a4191
JH
71link:git-merge-cache.html[git-merge-cache]::
72 Runs a merge for files needing merging
2cf565c5 73
2cf565c5
DG
74link:git-mktag.html[git-mktag]::
75 Creates a tag object
76
f85a4191
JH
77link:git-pack-objects.html[git-pack-objects]::
78 Creates a packed archive of objects.
79
80link:git-prune-packed.html[git-prune-packed]::
81 Remove extra objects that are already in pack files.
82
2cf565c5
DG
83link:git-read-tree.html[git-read-tree]::
84 Reads tree information into the directory cache
85
f85a4191
JH
86link:git-unpack-objects.html[git-unpack-objects]::
87 Unpacks objects out of a packed archive.
88
2cf565c5
DG
89link:git-update-cache.html[git-update-cache]::
90 Modifies the index or directory cache
91
2cf565c5
DG
92link:git-write-tree.html[git-write-tree]::
93 Creates a tree from the current cache
94
e31bb3bb 95
2cf565c5
DG
96Interrogation commands
97~~~~~~~~~~~~~~~~~~~~~~
f85a4191 98
2cf565c5
DG
99link:git-cat-file.html[git-cat-file]::
100 Provide content or type information for repository objects
101
2cf565c5
DG
102link:git-diff-cache.html[git-diff-cache]::
103 Compares content and mode of blobs between the cache and repository
104
105link:git-diff-files.html[git-diff-files]::
106 Compares files in the working tree and the cache
107
83db04ff
JH
108link:git-diff-stages.html[git-diff-stages]::
109 Compares two "merge stages" in the index file.
110
f85a4191
JH
111link:git-diff-tree.html[git-diff-tree]::
112 Compares the content and mode of blobs found via two tree objects
113
2cf565c5
DG
114link:git-export.html[git-export]::
115 Exports each commit and a diff against each of its parents
116
117link:git-fsck-cache.html[git-fsck-cache]::
118 Verifies the connectivity and validity of the objects in the database
119
120link:git-ls-files.html[git-ls-files]::
121 Information about files in the cache/working directory
122
123link:git-ls-tree.html[git-ls-tree]::
124 Displays a tree object in human readable form
125
f85a4191
JH
126link:git-merge-base.html[git-merge-base]::
127 Finds as good a common ancestor as possible for a merge
2cf565c5
DG
128
129link:git-rev-list.html[git-rev-list]::
130 Lists commit objects in reverse chronological order
131
132link:git-rev-tree.html[git-rev-tree]::
133 Provides the revision tree for one or more commits
134
f85a4191
JH
135link:git-show-index.html[git-show-index]::
136 Displays contents of a pack idx file.
137
2cf565c5
DG
138link:git-tar-tree.html[git-tar-tree]::
139 Creates a tar archive of the files in the named tree
140
141link:git-unpack-file.html[git-unpack-file]::
142 Creates a temporary file with a blob's contents
143
aed022ab
EB
144link:git-var.html[git-var]::
145 Displays a git logical variable
146
f9253394
JH
147link:git-verify-pack.html[git-verify-pack]::
148 Validates packed GIT archive files
149
2cf565c5
DG
150The interrogate commands may create files - and you can force them to
151touch the working file set - but in general they don't
152
153
0c04094b
JH
154Synching repositories
155~~~~~~~~~~~~~~~~~~~~~
156
6ec311da
JH
157link:git-clone-pack.html[git-clone-pack]::
158 Clones a repository into the current repository (engine
159 for ssh and local transport)
160
f85a4191
JH
161link:git-fetch-pack.html[git-fetch-pack]::
162 Updates from a remote repository.
163
204ee6a9
DG
164link:git-http-pull.html[git-http-pull]::
165 Downloads a remote GIT repository via HTTP
166
167link:git-local-pull.html[git-local-pull]::
168 Duplicates another GIT repository on a local system
169
f85a4191
JH
170link:git-peek-remote.html[git-peek-remote]::
171 Lists references on a remote repository using upload-pack protocol.
2f2de9b4
JH
172
173link:git-receive-pack.html[git-receive-pack]::
174 Invoked by 'git-send-pack' to receive what is pushed to it.
175
f85a4191
JH
176link:git-send-pack.html[git-send-pack]::
177 Pushes to a remote repository, intelligently.
2f2de9b4 178
f85a4191
JH
179link:git-ssh-pull.html[git-ssh-pull]::
180 Pulls from a remote repository over ssh connection
508e67ab 181
f85a4191
JH
182link:git-ssh-push.html[git-ssh-push]::
183 Helper "server-side" program used by git-ssh-pull
2f2de9b4 184
61e3ef36
JH
185link:git-update-server-info.html[git-update-server-info]::
186 Updates auxiliary information on a dumb server to help
187 clients discover references and packs on it.
188
f85a4191
JH
189link:git-upload-pack.html[git-upload-pack]::
190 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
191 what are asked for.
192
2f2de9b4 193
3f971fc4
JH
194Porcelain-ish Commands
195----------------------
905197de
JH
196
197link:git-add-script.html[git-add-script]::
198 Add paths to the index file.
199
f85a4191
JH
200link:git-applymbox.html[git-applymbox]::
201 Apply patches from a mailbox.
202
203link:git-bisect-script.html[git-bisect-script]::
204 Find the change that introduced a bug.
205
905197de
JH
206link:git-branch-script.html[git-branch-script]::
207 Create and Show branches.
208
f85a4191
JH
209link:git-cherry-pick-script.html[git-cherry-pick-script]::
210 Cherry-pick the effect of an existing commit.
3f971fc4 211
f85a4191
JH
212link:git-clone-script.html[git-clone-script]::
213 Clones a repository into a new directory.
3f971fc4 214
f85a4191
JH
215link:git-commit-script.html[git-commit-script]::
216 Record changes to the repository.
3f971fc4 217
62033318
JH
218link:git-fetch-script.html[git-fetch-script]::
219 Download from a remote repository via various protocols.
220
f85a4191
JH
221link:git-log-script.html[git-log-script]::
222 Shows commit logs.
62033318 223
f85a4191
JH
224link:git-ls-remote-script.html[git-ls-remote-script]::
225 Shows references in a remote or local repository.
ab9b3138
JH
226
227link:git-octopus-script.html[git-octopus-script]::
228 Merge more than two commits.
229
f85a4191
JH
230link:git-pull-script.html[git-pull-script]::
231 Fetch from and merge with a remote repository.
232
ab9b3138
JH
233link:git-push-script.html[git-push-script]::
234 Update remote refs along with associated objects.
235
f85a4191
JH
236link:git-rebase-script.html[git-rebase-script]::
237 Rebase local commits to new upstream head.
62033318 238
f85a4191
JH
239link:git-rename-script.html[git-rename]::
240 Rename files and directories.
62033318 241
e31bb3bb
JH
242link:git-repack-script.html[git-repack-script]::
243 Pack unpacked objects in a repository.
244
f85a4191
JH
245link:git-resolve-script.html[git-resolve-script]::
246 Merge two commits.
83db04ff 247
f85a4191
JH
248link:git-revert-script.html[git-revert-script]::
249 Revert an existing commit.
250
251link:git-shortlog.html[git-shortlog]::
252 Summarizes 'git log' output.
253
254link:git-show-branch.html[git-show-branch]::
255 Show branches and their commits.
256
257link:git-status-script.html[git-status-script]::
258 Shows the working tree status.
83db04ff 259
905197de
JH
260link:git-verify-tag-script.html[git-verify-tag-script]::
261 Check the GPG signature of tag.
262
f85a4191
JH
263link:git-whatchanged.html[git-whatchanged]::
264 Shows commit logs and differences they introduce.
265
e31bb3bb 266
90933efb
YS
267Ancillary Commands
268------------------
2f2de9b4
JH
269Manipulators:
270
f85a4191
JH
271link:git-applypatch.html[git-applypatch]::
272 Apply one patch extracted from an e-mail.
905197de 273
2f2de9b4
JH
274link:git-convert-cache.html[git-convert-cache]::
275 Converts old-style GIT repository
276
f85a4191
JH
277link:git-cvsimport-script.html[git-cvsimport-script]::
278 Salvage your data out of another SCM people love to hate.
279
204ee6a9
DG
280link:git-merge-one-file-script.html[git-merge-one-file-script]::
281 The standard helper program to use with "git-merge-cache"
282
204ee6a9
DG
283link:git-prune-script.html[git-prune-script]::
284 Prunes all unreachable objects from the object database
285
f85a4191
JH
286link:git-relink-script.html[git-relink-script]::
287 Hardlink common objects in local repositories.
288
289link:git-sh-setup-script.html[git-sh-setup-script]::
290 Common git shell script setup code.
291
204ee6a9
DG
292link:git-tag-script.html[git-tag-script]::
293 An example script to create a tag object signed with GPG
294
204ee6a9 295
90933efb 296Interrogators:
204ee6a9 297
f85a4191
JH
298link:git-cherry.html[git-cherry]::
299 Find commits not merged upstream.
905197de
JH
300
301link:git-count-objects-script.html[git-count-objects-script]::
302 Count unpacked number of objects and their disk consumption.
303
99665af5 304link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
305 Generates patch format output for git-diff-*
306
f85a4191
JH
307link:git-mailinfo.html[git-mailinfo]::
308 Extracts patch from a single e-mail message.
309
310link:git-mailsplit.html[git-mailsplit]::
311 git-mailsplit.
312
313link:git-patch-id.html[git-patch-id]::
314 Compute unique ID for a patch.
204ee6a9 315
83db04ff
JH
316link:git-send-email-script.html[git-send-email]::
317 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9
DG
318
319
7fc9d69f
JH
320Commands not yet documented
321---------------------------
322
7fc9d69f
JH
323link:git-build-rev-cache.html[git-build-rev-cache]::
324 git-build-rev-cache.
325
326link:git-checkout-script.html[git-checkout-script]::
327 git-checkout-script.
328
7fc9d69f
JH
329link:git-clone-dumb-http.html[git-clone-dumb-http]::
330 git-clone-dumb-http.
331
7fc9d69f
JH
332link:git-daemon.html[git-daemon]::
333 git-daemon.
334
335link:git-diff-script.html[git-diff-script]::
336 git-diff-script.
337
338link:git-format-patch-script.html[git-format-patch-script]::
339 git-format-patch-script.
340
341link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
342 git-get-tar-commit-id.
343
7fc9d69f
JH
344link:git-request-pull-script.html[git-request-pull-script]::
345 git-request-pull-script.
346
347link:git-reset-script.html[git-reset-script]::
348 git-reset-script.
349
350link:git-rev-parse.html[git-rev-parse]::
351 git-rev-parse.
352
7fc9d69f
JH
353link:git-show-rev-cache.html[git-show-rev-cache]::
354 git-show-rev-cache.
355
356link:git-stripspace.html[git-stripspace]::
357 git-stripspace.
358
7fc9d69f
JH
359link:gitk.html[gitk]::
360 gitk.
361
362
6c84e2e0 363Identifier Terminology
2cf565c5
DG
364----------------------
365<object>::
6c84e2e0 366 Indicates the sha1 identifier for any type of object
2cf565c5
DG
367
368<blob>::
369 Indicates a blob object sha1 identifier
370
371<tree>::
372 Indicates a tree object sha1 identifier
373
374<commit>::
375 Indicates a commit object sha1 identifier
376
377<tree-ish>::
6c84e2e0
DG
378 Indicates a tree, commit or tag object sha1 identifier. A
379 command that takes a <tree-ish> argument ultimately wants to
380 operate on a <tree> object but automatically dereferences
381 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
382
383<type>::
384 Indicates that an object type is required.
385 Currently one of: blob/tree/commit/tag
386
387<file>::
388 Indicates a filename - always relative to the root of
389 the tree structure GIT_INDEX_FILE describes.
390
c1bdacf9
DG
391Symbolic Identifiers
392--------------------
90933efb 393Any git command accepting any <object> can also use the following
6c84e2e0 394symbolic notation:
c1bdacf9
DG
395
396HEAD::
6c84e2e0
DG
397 indicates the head of the repository (ie the contents of
398 `$GIT_DIR/HEAD`)
c1bdacf9
DG
399<tag>::
400 a valid tag 'name'+
401 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
402<head>::
403 a valid head 'name'+
404 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
405<snap>::
406 a valid snapshot 'name'+
407 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
408
409
410File/Directory Structure
411------------------------
412The git-core manipulates the following areas in the directory:
413
414 .git/ The base (overridden with $GIT_DIR)
415 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
2f2de9b4
JH
416 ??/ 'First 2 chars of object' directories.
417 pack/ Packed archives.
c1bdacf9
DG
418
419 refs/ Directories containing symbolic names for objects
420 (each file contains the hex SHA1 + newline)
421 heads/ Commits which are heads of various sorts
422 tags/ Tags, by the tag name (or some local renaming of it)
2f2de9b4
JH
423 */ Any other subdirectory of refs/ can be used to store
424 files similar to what are under refs/heads/.
425 HEAD Symlink to refs/heads/<current-branch-name>
c1bdacf9
DG
426
427Higher level SCMs may provide and manage additional information in the
428GIT_DIR.
429
2cf565c5
DG
430Terminology
431-----------
1bff6490 432Please see link:glossary.html[glossary] document.
2cf565c5
DG
433
434
435Environment Variables
436---------------------
437Various git commands use the following environment variables:
438
c1bdacf9
DG
439The git Repository
440~~~~~~~~~~~~~~~~~~
441These environment variables apply to 'all' core git commands. Nb: it
442is worth noting that they may be used/overridden by SCMS sitting above
443git so take care if using Cogito etc
444
445'GIT_INDEX_FILE'::
446 This environment allows the specification of an alternate
447 cache/index file. If not specified, the default of
448 `$GIT_DIR/index` is used.
449
450'GIT_OBJECT_DIRECTORY'::
451 If the object storage directory is specified via this
452 environment variable then the sha1 directories are created
453 underneath - otherwise the default `$GIT_DIR/objects`
454 directory is used.
455
456'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
457 Due to the immutable nature of git objects, old objects can be
458 archived into shared, read-only directories. This variable
90933efb 459 specifies a ":" separated list of git object directories which
c1bdacf9
DG
460 can be used to search for git objects. New objects will not be
461 written to these directories.
462
463'GIT_DIR'::
464 If the 'GIT_DIR' environment variable is set then it specifies
465 a path to use instead of `./.git` for the base of the
466 repository.
467
468git Commits
469~~~~~~~~~~~
470'GIT_AUTHOR_NAME'::
471'GIT_AUTHOR_EMAIL'::
472'GIT_AUTHOR_DATE'::
473'GIT_COMMITTER_NAME'::
474'GIT_COMMITTER_EMAIL'::
475 see link:git-commit-tree.html[git-commit-tree]
476
477git Diffs
478~~~~~~~~~
d81ed1b5
JH
479'GIT_DIFF_OPTS'::
480'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
481 see the "generating patches" section in :
482 link:git-diff-cache.html[git-diff-cache];
483 link:git-diff-files.html[git-diff-files];
484 link:git-diff-tree.html[git-diff-tree]
2cf565c5 485
6c84e2e0
DG
486Discussion
487----------
488include::../README[]
489
2cf565c5
DG
490Author
491------
6c84e2e0 492Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
493
494Documentation
495--------------
496Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
497
498GIT
499---
500Part of the link:git.html[git] suite
501