Merge branch 'maint'
[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-archive[1]::
247 Invoked by 'git-archive' to send a generated archive.
248
249 gitlink:git-upload-pack[1]::
250 Invoked by 'git-fetch-pack' to push
251 what are asked for.
252
253
254 High-level commands (porcelain)
255 -------------------------------
256
257 We separate the porcelain commands into the main commands and some
258 ancillary user utilities.
259
260 Main porcelain commands
261 ~~~~~~~~~~~~~~~~~~~~~~~
262
263 gitlink:git-add[1]::
264 Add paths to the index.
265
266 gitlink:git-am[1]::
267 Apply patches from a mailbox, but cooler.
268
269 gitlink:git-applymbox[1]::
270 Apply patches from a mailbox, original version by Linus.
271
272 gitlink:git-archive[1]::
273 Creates an archive of files from a named tree.
274
275 gitlink:git-bisect[1]::
276 Find the change that introduced a bug by binary search.
277
278 gitlink:git-branch[1]::
279 Create and Show branches.
280
281 gitlink:git-checkout[1]::
282 Checkout and switch to a branch.
283
284 gitlink:git-cherry-pick[1]::
285 Cherry-pick the effect of an existing commit.
286
287 gitlink:git-clean[1]::
288 Remove untracked files from the working tree.
289
290 gitlink:git-clone[1]::
291 Clones a repository into a new directory.
292
293 gitlink:git-commit[1]::
294 Record changes to the repository.
295
296 gitlink:git-diff[1]::
297 Show changes between commits, commit and working tree, etc.
298
299 gitlink:git-fetch[1]::
300 Download from a remote repository via various protocols.
301
302 gitlink:git-format-patch[1]::
303 Prepare patches for e-mail submission.
304
305 gitlink:git-grep[1]::
306 Print lines matching a pattern.
307
308 gitlink:gitk[1]::
309 The git repository browser.
310
311 gitlink:git-log[1]::
312 Shows commit logs.
313
314 gitlink:git-ls-remote[1]::
315 Shows references in a remote or local repository.
316
317 gitlink:git-merge[1]::
318 Grand unified merge driver.
319
320 gitlink:git-mv[1]::
321 Move or rename a file, a directory, or a symlink.
322
323 gitlink:git-pull[1]::
324 Fetch from and merge with a remote repository.
325
326 gitlink:git-push[1]::
327 Update remote refs along with associated objects.
328
329 gitlink:git-rebase[1]::
330 Rebase local commits to the updated upstream head.
331
332 gitlink:git-repack[1]::
333 Pack unpacked objects in a repository.
334
335 gitlink:git-rerere[1]::
336 Reuse recorded resolution of conflicted merges.
337
338 gitlink:git-reset[1]::
339 Reset current HEAD to the specified state.
340
341 gitlink:git-resolve[1]::
342 Merge two commits.
343
344 gitlink:git-revert[1]::
345 Revert an existing commit.
346
347 gitlink:git-rm[1]::
348 Remove files from the working tree and from the index.
349
350 gitlink:git-shortlog[1]::
351 Summarizes 'git log' output.
352
353 gitlink:git-show[1]::
354 Show one commit log and its diff.
355
356 gitlink:git-show-branch[1]::
357 Show branches and their commits.
358
359 gitlink:git-status[1]::
360 Shows the working tree status.
361
362 gitlink:git-verify-tag[1]::
363 Check the GPG signature of tag.
364
365 gitlink:git-whatchanged[1]::
366 Shows commit logs and differences they introduce.
367
368
369 Ancillary Commands
370 ~~~~~~~~~~~~~~~~~~
371 Manipulators:
372
373 gitlink:git-applypatch[1]::
374 Apply one patch extracted from an e-mail.
375
376 gitlink:git-archimport[1]::
377 Import an arch repository into git.
378
379 gitlink:git-convert-objects[1]::
380 Converts old-style git repository.
381
382 gitlink:git-cvsimport[1]::
383 Salvage your data out of another SCM people love to hate.
384
385 gitlink:git-cvsexportcommit[1]::
386 Export a single commit to a CVS checkout.
387
388 gitlink:git-cvsserver[1]::
389 A CVS server emulator for git.
390
391 gitlink:git-lost-found[1]::
392 Recover lost refs that luckily have not yet been pruned.
393
394 gitlink:git-merge-one-file[1]::
395 The standard helper program to use with `git-merge-index`.
396
397 gitlink:git-prune[1]::
398 Prunes all unreachable objects from the object database.
399
400 gitlink:git-quiltimport[1]::
401 Applies a quilt patchset onto the current branch.
402
403 gitlink:git-relink[1]::
404 Hardlink common objects in local repositories.
405
406 gitlink:git-svn[1]::
407 Bidirectional operation between a single Subversion branch and git.
408
409 gitlink:git-svnimport[1]::
410 Import a SVN repository into git.
411
412 gitlink:git-sh-setup[1]::
413 Common git shell script setup code.
414
415 gitlink:git-symbolic-ref[1]::
416 Read and modify symbolic refs.
417
418 gitlink:git-tag[1]::
419 An example script to create a tag object signed with GPG.
420
421 gitlink:git-update-ref[1]::
422 Update the object name stored in a ref safely.
423
424
425 Interrogators:
426
427 gitlink:git-annotate[1]::
428 Annotate file lines with commit info.
429
430 gitlink:git-blame[1]::
431 Blame file lines on commits.
432
433 gitlink:git-check-ref-format[1]::
434 Make sure ref name is well formed.
435
436 gitlink:git-cherry[1]::
437 Find commits not merged upstream.
438
439 gitlink:git-count-objects[1]::
440 Count unpacked number of objects and their disk consumption.
441
442 gitlink:git-daemon[1]::
443 A really simple server for git repositories.
444
445 gitlink:git-fmt-merge-msg[1]::
446 Produce a merge commit message.
447
448 gitlink:git-get-tar-commit-id[1]::
449 Extract commit ID from an archive created using git-tar-tree.
450
451 gitlink:git-imap-send[1]::
452 Dump a mailbox from stdin into an imap folder.
453
454 gitlink:git-instaweb[1]::
455 Instantly browse your working repository in gitweb.
456
457 gitlink:git-mailinfo[1]::
458 Extracts patch and authorship information from a single
459 e-mail message, optionally transliterating the commit
460 message into utf-8.
461
462 gitlink:git-mailsplit[1]::
463 A stupid program to split UNIX mbox format mailbox into
464 individual pieces of e-mail.
465
466 gitlink:git-merge-tree[1]::
467 Show three-way merge without touching index.
468
469 gitlink:git-patch-id[1]::
470 Compute unique ID for a patch.
471
472 gitlink:git-parse-remote[1]::
473 Routines to help parsing `$GIT_DIR/remotes/` files.
474
475 gitlink:git-request-pull[1]::
476 git-request-pull.
477
478 gitlink:git-rev-parse[1]::
479 Pick out and massage parameters.
480
481 gitlink:git-send-email[1]::
482 Send patch e-mails out of "format-patch --mbox" output.
483
484 gitlink:git-symbolic-ref[1]::
485 Read and modify symbolic refs.
486
487 gitlink:git-stripspace[1]::
488 Filter out empty lines.
489
490
491 Configuration Mechanism
492 -----------------------
493
494 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
495 is used to hold per-repository configuration options. It is a
496 simple text file modeled after `.ini` format familiar to some
497 people. Here is an example:
498
499 ------------
500 #
501 # A '#' or ';' character indicates a comment.
502 #
503
504 ; core variables
505 [core]
506 ; Don't trust file modes
507 filemode = false
508
509 ; user identity
510 [user]
511 name = "Junio C Hamano"
512 email = "junkio@twinsun.com"
513
514 ------------
515
516 Various commands read from the configuration file and adjust
517 their operation accordingly.
518
519
520 Identifier Terminology
521 ----------------------
522 <object>::
523 Indicates the object name for any type of object.
524
525 <blob>::
526 Indicates a blob object name.
527
528 <tree>::
529 Indicates a tree object name.
530
531 <commit>::
532 Indicates a commit object name.
533
534 <tree-ish>::
535 Indicates a tree, commit or tag object name. A
536 command that takes a <tree-ish> argument ultimately wants to
537 operate on a <tree> object but automatically dereferences
538 <commit> and <tag> objects that point at a <tree>.
539
540 <type>::
541 Indicates that an object type is required.
542 Currently one of: `blob`, `tree`, `commit`, or `tag`.
543
544 <file>::
545 Indicates a filename - almost always relative to the
546 root of the tree structure `GIT_INDEX_FILE` describes.
547
548 Symbolic Identifiers
549 --------------------
550 Any git command accepting any <object> can also use the following
551 symbolic notation:
552
553 HEAD::
554 indicates the head of the current branch (i.e. the
555 contents of `$GIT_DIR/HEAD`).
556
557 <tag>::
558 a valid tag 'name'
559 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
560
561 <head>::
562 a valid head 'name'
563 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
564
565
566 File/Directory Structure
567 ------------------------
568
569 Please see link:repository-layout.html[repository layout] document.
570
571 Read link:hooks.html[hooks] for more details about each hook.
572
573 Higher level SCMs may provide and manage additional information in the
574 `$GIT_DIR`.
575
576
577 Terminology
578 -----------
579 Please see link:glossary.html[glossary] document.
580
581
582 Environment Variables
583 ---------------------
584 Various git commands use the following environment variables:
585
586 The git Repository
587 ~~~~~~~~~~~~~~~~~~
588 These environment variables apply to 'all' core git commands. Nb: it
589 is worth noting that they may be used/overridden by SCMS sitting above
590 git so take care if using Cogito etc.
591
592 'GIT_INDEX_FILE'::
593 This environment allows the specification of an alternate
594 index file. If not specified, the default of `$GIT_DIR/index`
595 is used.
596
597 'GIT_OBJECT_DIRECTORY'::
598 If the object storage directory is specified via this
599 environment variable then the sha1 directories are created
600 underneath - otherwise the default `$GIT_DIR/objects`
601 directory is used.
602
603 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
604 Due to the immutable nature of git objects, old objects can be
605 archived into shared, read-only directories. This variable
606 specifies a ":" separated list of git object directories which
607 can be used to search for git objects. New objects will not be
608 written to these directories.
609
610 'GIT_DIR'::
611 If the 'GIT_DIR' environment variable is set then it
612 specifies a path to use instead of the default `.git`
613 for the base of the repository.
614
615 git Commits
616 ~~~~~~~~~~~
617 'GIT_AUTHOR_NAME'::
618 'GIT_AUTHOR_EMAIL'::
619 'GIT_AUTHOR_DATE'::
620 'GIT_COMMITTER_NAME'::
621 'GIT_COMMITTER_EMAIL'::
622 see gitlink:git-commit-tree[1]
623
624 git Diffs
625 ~~~~~~~~~
626 'GIT_DIFF_OPTS'::
627 'GIT_EXTERNAL_DIFF'::
628 see the "generating patches" section in :
629 gitlink:git-diff-index[1];
630 gitlink:git-diff-files[1];
631 gitlink:git-diff-tree[1]
632
633 other
634 ~~~~~
635 'GIT_PAGER'::
636 This environment variable overrides `$PAGER`.
637
638 'GIT_TRACE'::
639 If this variable is set to "1", "2" or "true" (comparison
640 is case insensitive), git will print `trace:` messages on
641 stderr telling about alias expansion, built-in command
642 execution and external command execution.
643 If this variable is set to an integer value greater than 1
644 and lower than 10 (strictly) then git will interpret this
645 value as an open file descriptor and will try to write the
646 trace messages into this file descriptor.
647 Alternatively, if this variable is set to an absolute path
648 (starting with a '/' character), git will interpret this
649 as a file path and will try to write the trace messages
650 into it.
651
652 Discussion[[Discussion]]
653 ------------------------
654 include::README[]
655
656 Authors
657 -------
658 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
659 * The current git nurse is Junio C Hamano <junkio@cox.net>.
660 * The git potty was written by Andres Ericsson <ae@op5.se>.
661 * General upbringing is handled by the git-list <git@vger.kernel.org>.
662
663 Documentation
664 --------------
665 The documentation for git suite was started by David Greaves
666 <david@dgreaves.com>, and later enhanced greatly by the
667 contributors on the git-list <git@vger.kernel.org>.
668
669 GIT
670 ---
671 Part of the gitlink:git[7] suite
672