Merge branch 'jc/for-each-ref' into jc/ref-locking
[git/git.git] / Documentation / git.txt
1 git(7)
2 ======
3
4 NAME
5 ----
6 git - the stupid content tracker
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate]
13 [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS]
14
15 DESCRIPTION
16 -----------
17 Git is a fast, scalable, distributed revision control system with an
18 unusually rich command set that provides both high-level operations
19 and full access to internals.
20
21 See this link:tutorial.html[tutorial] to get started, then see
22 link:everyday.html[Everyday Git] for a useful minimum set of commands, and
23 "man git-commandname" for documentation of each command. CVS users may
24 also want to read link:cvs-migration.html[CVS migration].
25
26 The COMMAND is either a name of a Git command (see below) or an alias
27 as defined in the configuration file (see gitlink:git-repo-config[1]).
28
29 OPTIONS
30 -------
31 --version::
32 Prints the git suite version that the 'git' program came from.
33
34 --help::
35 Prints the synopsis and a list of the most commonly used
36 commands. If a git command is named this option will bring up
37 the man-page for that command. If the option '--all' or '-a' is
38 given then all available commands are printed.
39
40 --exec-path::
41 Path to wherever your core git programs are installed.
42 This can also be controlled by setting the GIT_EXEC_PATH
43 environment variable. If no path is given 'git' will print
44 the current setting and then exit.
45
46 -p|--paginate::
47 Pipe all output into 'less' (or if set, $PAGER).
48
49 --git-dir=<path>::
50 Set the path to the repository. This can also be controlled by
51 setting the GIT_DIR environment variable.
52
53 --bare::
54 Same as --git-dir=`pwd`.
55
56 FURTHER DOCUMENTATION
57 ---------------------
58
59 See the references above to get started using git. The following is
60 probably more detail than necessary for a first-time user.
61
62 The <<Discussion,Discussion>> section below and the
63 link:core-tutorial.html[Core tutorial] both provide introductions to the
64 underlying git architecture.
65
66 See also the link:howto-index.html[howto] documents for some useful
67 examples.
68
69 GIT COMMANDS
70 ------------
71
72 We divide git into high level ("porcelain") commands and low level
73 ("plumbing") commands.
74
75 Low-level commands (plumbing)
76 -----------------------------
77
78 Although git includes its
79 own porcelain layer, its low-level commands are sufficient to support
80 development of alternative porcelains. Developers of such porcelains
81 might start by reading about gitlink:git-update-index[1] and
82 gitlink:git-read-tree[1].
83
84 We divide the low-level commands into commands that manipulate objects (in
85 the repository, index, and working tree), commands that interrogate and
86 compare objects, and commands that move objects and references between
87 repositories.
88
89 Manipulation commands
90 ~~~~~~~~~~~~~~~~~~~~~
91 gitlink:git-apply[1]::
92 Reads a "diff -up1" or git generated patch file and
93 applies it to the working tree.
94
95 gitlink:git-checkout-index[1]::
96 Copy files from the index to the working tree.
97
98 gitlink:git-commit-tree[1]::
99 Creates a new commit object.
100
101 gitlink:git-hash-object[1]::
102 Computes the object ID from a file.
103
104 gitlink:git-index-pack[1]::
105 Build pack idx file for an existing packed archive.
106
107 gitlink:git-init-db[1]::
108 Creates an empty git object database, or reinitialize an
109 existing one.
110
111 gitlink:git-merge-index[1]::
112 Runs a merge for files needing merging.
113
114 gitlink:git-mktag[1]::
115 Creates a tag object.
116
117 gitlink:git-mktree[1]::
118 Build a tree-object from ls-tree formatted text.
119
120 gitlink:git-pack-objects[1]::
121 Creates a packed archive of objects.
122
123 gitlink:git-prune-packed[1]::
124 Remove extra objects that are already in pack files.
125
126 gitlink:git-read-tree[1]::
127 Reads tree information into the index.
128
129 gitlink:git-repo-config[1]::
130 Get and set options in .git/config.
131
132 gitlink:git-unpack-objects[1]::
133 Unpacks objects out of a packed archive.
134
135 gitlink:git-update-index[1]::
136 Registers files in the working tree to the index.
137
138 gitlink:git-write-tree[1]::
139 Creates a tree from the index.
140
141
142 Interrogation commands
143 ~~~~~~~~~~~~~~~~~~~~~~
144
145 gitlink:git-cat-file[1]::
146 Provide content or type/size information for repository objects.
147
148 gitlink:git-describe[1]::
149 Show the most recent tag that is reachable from a commit.
150
151 gitlink:git-diff-index[1]::
152 Compares content and mode of blobs between the index and repository.
153
154 gitlink:git-diff-files[1]::
155 Compares files in the working tree and the index.
156
157 gitlink:git-diff-stages[1]::
158 Compares two "merge stages" in the index.
159
160 gitlink:git-diff-tree[1]::
161 Compares the content and mode of blobs found via two tree objects.
162
163 gitlink:git-fsck-objects[1]::
164 Verifies the connectivity and validity of the objects in the database.
165
166 gitlink:git-ls-files[1]::
167 Information about files in the index and the working tree.
168
169 gitlink:git-ls-tree[1]::
170 Displays a tree object in human readable form.
171
172 gitlink:git-merge-base[1]::
173 Finds as good common ancestors as possible for a merge.
174
175 gitlink:git-name-rev[1]::
176 Find symbolic names for given revs.
177
178 gitlink:git-pack-redundant[1]::
179 Find redundant pack files.
180
181 gitlink:git-rev-list[1]::
182 Lists commit objects in reverse chronological order.
183
184 gitlink:git-show-index[1]::
185 Displays contents of a pack idx file.
186
187 gitlink:git-tar-tree[1]::
188 Creates a tar archive of the files in the named tree object.
189
190 gitlink:git-unpack-file[1]::
191 Creates a temporary file with a blob's contents.
192
193 gitlink:git-var[1]::
194 Displays a git logical variable.
195
196 gitlink:git-verify-pack[1]::
197 Validates packed git archive files.
198
199 In general, the interrogate commands do not touch the files in
200 the working tree.
201
202
203 Synching repositories
204 ~~~~~~~~~~~~~~~~~~~~~
205
206 gitlink:git-fetch-pack[1]::
207 Updates from a remote repository (engine for ssh and
208 local transport).
209
210 gitlink:git-http-fetch[1]::
211 Downloads a remote git repository via HTTP by walking
212 commit chain.
213
214 gitlink:git-local-fetch[1]::
215 Duplicates another git repository on a local system by
216 walking commit chain.
217
218 gitlink:git-peek-remote[1]::
219 Lists references on a remote repository using
220 upload-pack protocol (engine for ssh and local
221 transport).
222
223 gitlink:git-receive-pack[1]::
224 Invoked by 'git-send-pack' to receive what is pushed to it.
225
226 gitlink:git-send-pack[1]::
227 Pushes to a remote repository, intelligently.
228
229 gitlink:git-http-push[1]::
230 Push missing objects using HTTP/DAV.
231
232 gitlink:git-shell[1]::
233 Restricted shell for GIT-only SSH access.
234
235 gitlink:git-ssh-fetch[1]::
236 Pulls from a remote repository over ssh connection by
237 walking commit chain.
238
239 gitlink:git-ssh-upload[1]::
240 Helper "server-side" program used by git-ssh-fetch.
241
242 gitlink:git-update-server-info[1]::
243 Updates auxiliary information on a dumb server to help
244 clients discover references and packs on it.
245
246 gitlink:git-upload-pack[1]::
247 Invoked by 'git-fetch-pack' to push
248 what are asked for.
249
250 gitlink:git-upload-tar[1]::
251 Invoked by 'git-tar-tree --remote' to return the tar
252 archive the other end asked for.
253
254
255 High-level commands (porcelain)
256 -------------------------------
257
258 We separate the porcelain commands into the main commands and some
259 ancillary user utilities.
260
261 Main porcelain commands
262 ~~~~~~~~~~~~~~~~~~~~~~~
263
264 gitlink:git-add[1]::
265 Add paths to the index.
266
267 gitlink:git-am[1]::
268 Apply patches from a mailbox, but cooler.
269
270 gitlink:git-applymbox[1]::
271 Apply patches from a mailbox, original version by Linus.
272
273 gitlink:git-bisect[1]::
274 Find the change that introduced a bug by binary search.
275
276 gitlink:git-branch[1]::
277 Create and Show branches.
278
279 gitlink:git-checkout[1]::
280 Checkout and switch to a branch.
281
282 gitlink:git-cherry-pick[1]::
283 Cherry-pick the effect of an existing commit.
284
285 gitlink:git-clean[1]::
286 Remove untracked files from the working tree.
287
288 gitlink:git-clone[1]::
289 Clones a repository into a new directory.
290
291 gitlink:git-commit[1]::
292 Record changes to the repository.
293
294 gitlink:git-diff[1]::
295 Show changes between commits, commit and working tree, etc.
296
297 gitlink:git-fetch[1]::
298 Download from a remote repository via various protocols.
299
300 gitlink:git-format-patch[1]::
301 Prepare patches for e-mail submission.
302
303 gitlink:git-grep[1]::
304 Print lines matching a pattern.
305
306 gitlink:gitk[1]::
307 The git repository browser.
308
309 gitlink:git-log[1]::
310 Shows commit logs.
311
312 gitlink:git-ls-remote[1]::
313 Shows references in a remote or local repository.
314
315 gitlink:git-merge[1]::
316 Grand unified merge driver.
317
318 gitlink:git-mv[1]::
319 Move or rename a file, a directory, or a symlink.
320
321 gitlink:git-pull[1]::
322 Fetch from and merge with a remote repository.
323
324 gitlink:git-push[1]::
325 Update remote refs along with associated objects.
326
327 gitlink:git-rebase[1]::
328 Rebase local commits to the updated upstream head.
329
330 gitlink:git-repack[1]::
331 Pack unpacked objects in a repository.
332
333 gitlink:git-rerere[1]::
334 Reuse recorded resolution of conflicted merges.
335
336 gitlink:git-reset[1]::
337 Reset current HEAD to the specified state.
338
339 gitlink:git-resolve[1]::
340 Merge two commits.
341
342 gitlink:git-revert[1]::
343 Revert an existing commit.
344
345 gitlink:git-rm[1]::
346 Remove files from the working tree and from the index.
347
348 gitlink:git-shortlog[1]::
349 Summarizes 'git log' output.
350
351 gitlink:git-show[1]::
352 Show one commit log and its diff.
353
354 gitlink:git-show-branch[1]::
355 Show branches and their commits.
356
357 gitlink:git-status[1]::
358 Shows the working tree status.
359
360 gitlink:git-verify-tag[1]::
361 Check the GPG signature of tag.
362
363 gitlink:git-whatchanged[1]::
364 Shows commit logs and differences they introduce.
365
366
367 Ancillary Commands
368 ~~~~~~~~~~~~~~~~~~
369 Manipulators:
370
371 gitlink:git-applypatch[1]::
372 Apply one patch extracted from an e-mail.
373
374 gitlink:git-archimport[1]::
375 Import an arch repository into git.
376
377 gitlink:git-convert-objects[1]::
378 Converts old-style git repository.
379
380 gitlink:git-cvsimport[1]::
381 Salvage your data out of another SCM people love to hate.
382
383 gitlink:git-cvsexportcommit[1]::
384 Export a single commit to a CVS checkout.
385
386 gitlink:git-cvsserver[1]::
387 A CVS server emulator for git.
388
389 gitlink:git-lost-found[1]::
390 Recover lost refs that luckily have not yet been pruned.
391
392 gitlink:git-merge-one-file[1]::
393 The standard helper program to use with `git-merge-index`.
394
395 gitlink:git-prune[1]::
396 Prunes all unreachable objects from the object database.
397
398 gitlink:git-quiltimport[1]::
399 Applies a quilt patchset onto the current branch.
400
401 gitlink:git-relink[1]::
402 Hardlink common objects in local repositories.
403
404 gitlink:git-svn[1]::
405 Bidirectional operation between a single Subversion branch and git.
406
407 gitlink:git-svnimport[1]::
408 Import a SVN repository into git.
409
410 gitlink:git-sh-setup[1]::
411 Common git shell script setup code.
412
413 gitlink:git-symbolic-ref[1]::
414 Read and modify symbolic refs.
415
416 gitlink:git-tag[1]::
417 An example script to create a tag object signed with GPG.
418
419 gitlink:git-update-ref[1]::
420 Update the object name stored in a ref safely.
421
422
423 Interrogators:
424
425 gitlink:git-annotate[1]::
426 Annotate file lines with commit info.
427
428 gitlink:git-blame[1]::
429 Blame file lines on commits.
430
431 gitlink:git-check-ref-format[1]::
432 Make sure ref name is well formed.
433
434 gitlink:git-cherry[1]::
435 Find commits not merged upstream.
436
437 gitlink:git-count-objects[1]::
438 Count unpacked number of objects and their disk consumption.
439
440 gitlink:git-daemon[1]::
441 A really simple server for git repositories.
442
443 gitlink:git-fmt-merge-msg[1]::
444 Produce a merge commit message.
445
446 gitlink:git-get-tar-commit-id[1]::
447 Extract commit ID from an archive created using git-tar-tree.
448
449 gitlink:git-imap-send[1]::
450 Dump a mailbox from stdin into an imap folder.
451
452 gitlink:git-instaweb[1]::
453 Instantly browse your working repository in gitweb.
454
455 gitlink:git-mailinfo[1]::
456 Extracts patch and authorship information from a single
457 e-mail message, optionally transliterating the commit
458 message into utf-8.
459
460 gitlink:git-mailsplit[1]::
461 A stupid program to split UNIX mbox format mailbox into
462 individual pieces of e-mail.
463
464 gitlink:git-merge-tree[1]::
465 Show three-way merge without touching index.
466
467 gitlink:git-patch-id[1]::
468 Compute unique ID for a patch.
469
470 gitlink:git-parse-remote[1]::
471 Routines to help parsing `$GIT_DIR/remotes/` files.
472
473 gitlink:git-request-pull[1]::
474 git-request-pull.
475
476 gitlink:git-rev-parse[1]::
477 Pick out and massage parameters.
478
479 gitlink:git-send-email[1]::
480 Send patch e-mails out of "format-patch --mbox" output.
481
482 gitlink:git-symbolic-ref[1]::
483 Read and modify symbolic refs.
484
485 gitlink:git-stripspace[1]::
486 Filter out empty lines.
487
488
489 Configuration Mechanism
490 -----------------------
491
492 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
493 is used to hold per-repository configuration options. It is a
494 simple text file modeled after `.ini` format familiar to some
495 people. Here is an example:
496
497 ------------
498 #
499 # A '#' or ';' character indicates a comment.
500 #
501
502 ; core variables
503 [core]
504 ; Don't trust file modes
505 filemode = false
506
507 ; user identity
508 [user]
509 name = "Junio C Hamano"
510 email = "junkio@twinsun.com"
511
512 ------------
513
514 Various commands read from the configuration file and adjust
515 their operation accordingly.
516
517
518 Identifier Terminology
519 ----------------------
520 <object>::
521 Indicates the object name for any type of object.
522
523 <blob>::
524 Indicates a blob object name.
525
526 <tree>::
527 Indicates a tree object name.
528
529 <commit>::
530 Indicates a commit object name.
531
532 <tree-ish>::
533 Indicates a tree, commit or tag object name. A
534 command that takes a <tree-ish> argument ultimately wants to
535 operate on a <tree> object but automatically dereferences
536 <commit> and <tag> objects that point at a <tree>.
537
538 <type>::
539 Indicates that an object type is required.
540 Currently one of: `blob`, `tree`, `commit`, or `tag`.
541
542 <file>::
543 Indicates a filename - almost always relative to the
544 root of the tree structure `GIT_INDEX_FILE` describes.
545
546 Symbolic Identifiers
547 --------------------
548 Any git command accepting any <object> can also use the following
549 symbolic notation:
550
551 HEAD::
552 indicates the head of the current branch (i.e. the
553 contents of `$GIT_DIR/HEAD`).
554
555 <tag>::
556 a valid tag 'name'
557 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
558
559 <head>::
560 a valid head 'name'
561 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
562
563
564 File/Directory Structure
565 ------------------------
566
567 Please see link:repository-layout.html[repository layout] document.
568
569 Read link:hooks.html[hooks] for more details about each hook.
570
571 Higher level SCMs may provide and manage additional information in the
572 `$GIT_DIR`.
573
574
575 Terminology
576 -----------
577 Please see link:glossary.html[glossary] document.
578
579
580 Environment Variables
581 ---------------------
582 Various git commands use the following environment variables:
583
584 The git Repository
585 ~~~~~~~~~~~~~~~~~~
586 These environment variables apply to 'all' core git commands. Nb: it
587 is worth noting that they may be used/overridden by SCMS sitting above
588 git so take care if using Cogito etc.
589
590 'GIT_INDEX_FILE'::
591 This environment allows the specification of an alternate
592 index file. If not specified, the default of `$GIT_DIR/index`
593 is used.
594
595 'GIT_OBJECT_DIRECTORY'::
596 If the object storage directory is specified via this
597 environment variable then the sha1 directories are created
598 underneath - otherwise the default `$GIT_DIR/objects`
599 directory is used.
600
601 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
602 Due to the immutable nature of git objects, old objects can be
603 archived into shared, read-only directories. This variable
604 specifies a ":" separated list of git object directories which
605 can be used to search for git objects. New objects will not be
606 written to these directories.
607
608 'GIT_DIR'::
609 If the 'GIT_DIR' environment variable is set then it
610 specifies a path to use instead of the default `.git`
611 for the base of the repository.
612
613 git Commits
614 ~~~~~~~~~~~
615 'GIT_AUTHOR_NAME'::
616 'GIT_AUTHOR_EMAIL'::
617 'GIT_AUTHOR_DATE'::
618 'GIT_COMMITTER_NAME'::
619 'GIT_COMMITTER_EMAIL'::
620 see gitlink:git-commit-tree[1]
621
622 git Diffs
623 ~~~~~~~~~
624 'GIT_DIFF_OPTS'::
625 'GIT_EXTERNAL_DIFF'::
626 see the "generating patches" section in :
627 gitlink:git-diff-index[1];
628 gitlink:git-diff-files[1];
629 gitlink:git-diff-tree[1]
630
631 other
632 ~~~~~
633 'GIT_PAGER'::
634 This environment variable overrides `$PAGER`.
635
636 'GIT_TRACE'::
637 If this variable is set to "1", "2" or "true" (comparison
638 is case insensitive), git will print `trace:` messages on
639 stderr telling about alias expansion, built-in command
640 execution and external command execution.
641 If this variable is set to an integer value greater than 1
642 and lower than 10 (strictly) then git will interpret this
643 value as an open file descriptor and will try to write the
644 trace messages into this file descriptor.
645 Alternatively, if this variable is set to an absolute path
646 (starting with a '/' character), git will interpret this
647 as a file path and will try to write the trace messages
648 into it.
649
650 Discussion[[Discussion]]
651 ------------------------
652 include::README[]
653
654 Authors
655 -------
656 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
657 * The current git nurse is Junio C Hamano <junkio@cox.net>.
658 * The git potty was written by Andres Ericsson <ae@op5.se>.
659 * General upbringing is handled by the git-list <git@vger.kernel.org>.
660
661 Documentation
662 --------------
663 The documentation for git suite was started by David Greaves
664 <david@dgreaves.com>, and later enhanced greatly by the
665 contributors on the git-list <git@vger.kernel.org>.
666
667 GIT
668 ---
669 Part of the gitlink:git[7] suite
670