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