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