Merge http://www.kernel.org/pub/scm/gitk/gitk
[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 both a program and a directory content tracker system.
16 The program 'git' is just a wrapper to reach the core git programs
17 (or a potty if you like, as it's not exactly porcelain but still
18 brings your stuff to the plumbing).
19
20 OPTIONS
21 -------
22 --version::
23         prints the git suite version that the 'git' program came from.
24
25 --help::
26         prints the synopsis and a list of available commands.
27         If a git command is named this option will bring up the
28         man-page for that command.
29
30 --exec-path::
31         path to wherever your core git programs are installed.
32         This can also be controlled by setting the GIT_EXEC_PATH
33         environment variable. If no path is given 'git' will print
34         the current setting and then exit.
35
36 CORE GIT COMMANDS
37 -----------------
38 Before reading this cover to cover, you may want to take a look
39 at the link:tutorial.html[tutorial] document.
40
41 The <<Discussion>> section below contains much useful definition and
42 clarification info - read that first.  And of the commands, I suggest
43 reading gitlink:git-update-index[1] and
44 gitlink:git-read-tree[1] first - I wish I had!
45
46 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
47 document may be helpful after you finish the tutorial.
48
49 After you get the general feel from the tutorial and this
50 overview page, you may want to take a look at the
51 link:howto-index.html[howto] documents.
52
53
54 David Greaves <david@dgreaves.com>
55 08/05/05
56
57 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
58 reflect recent changes.
59
60 Commands Overview
61 -----------------
62 The git commands can helpfully be split into those that manipulate
63 the repository, the index and the working fileset, those that
64 interrogate and compare them, and those that moves objects and
65 references between repositories.
66
67 In addition, git itself comes with a spartan set of porcelain
68 commands.  They are usable but are not meant to compete with real
69 Porcelains.
70
71 There are also some ancillary programs that can be viewed as useful
72 aids for using the core commands but which are unlikely to be used by
73 SCMs layered over git.
74
75 Manipulation commands
76 ~~~~~~~~~~~~~~~~~~~~~
77 gitlink:git-apply[1]::
78         Reads a "diff -up1" or git generated patch file and
79         applies it to the working tree.
80
81 gitlink:git-checkout-index[1]::
82         Copy files from the index to the working directory
83
84 gitlink:git-commit-tree[1]::
85         Creates a new commit object
86
87 gitlink:git-config-set[1]::
88         Set options in .git/config.
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 index file for an existing packed archive.
95
96 gitlink:git-init-db[1]::
97         Creates an empty git object database
98
99 gitlink:git-merge-index[1]::
100         Runs a merge for files needing merging
101
102 gitlink:git-mktag[1]::
103         Creates a tag object
104
105 gitlink:git-pack-objects[1]::
106         Creates a packed archive of objects.
107
108 gitlink:git-prune-packed[1]::
109         Remove extra objects that are already in pack files.
110
111 gitlink:git-read-tree[1]::
112         Reads tree information into the directory index
113
114 gitlink:git-unpack-objects[1]::
115         Unpacks objects out of a packed archive.
116
117 gitlink:git-update-index[1]::
118         Modifies the index or directory cache
119
120 gitlink:git-write-tree[1]::
121         Creates a tree from the current index
122
123
124 Interrogation commands
125 ~~~~~~~~~~~~~~~~~~~~~~
126
127 gitlink:git-cat-file[1]::
128         Provide content or type information for repository objects
129
130 gitlink:git-diff-index[1]::
131         Compares content and mode of blobs between the index and repository
132
133 gitlink:git-diff-files[1]::
134         Compares files in the working tree and the index
135
136 gitlink:git-diff-stages[1]::
137         Compares two "merge stages" in the index file.
138
139 gitlink:git-diff-tree[1]::
140         Compares the content and mode of blobs found via two tree objects
141
142 gitlink:git-fsck-objects[1]::
143         Verifies the connectivity and validity of the objects in the database
144
145 gitlink:git-ls-files[1]::
146         Information about files in the index/working directory
147
148 gitlink:git-ls-tree[1]::
149         Displays a tree object in human readable form
150
151 gitlink:git-merge-base[1]::
152         Finds as good a common ancestor as possible for a merge
153
154 gitlink:git-name-rev[1]::
155         Find symbolic names for given revs
156
157 gitlink:git-rev-list[1]::
158         Lists commit objects in reverse chronological order
159
160 gitlink:git-show-index[1]::
161         Displays contents of a pack idx file.
162
163 gitlink:git-tar-tree[1]::
164         Creates a tar archive of the files in the named tree
165
166 gitlink:git-unpack-file[1]::
167         Creates a temporary file with a blob's contents
168
169 gitlink:git-var[1]::
170         Displays a git logical variable
171
172 gitlink:git-verify-pack[1]::
173         Validates packed git archive files
174
175 The interrogate commands may create files - and you can force them to
176 touch the working file set - but in general they don't
177
178
179 Synching repositories
180 ~~~~~~~~~~~~~~~~~~~~~
181
182 gitlink:git-clone-pack[1]::
183         Clones a repository into the current repository (engine
184         for ssh and local transport)
185
186 gitlink:git-fetch-pack[1]::
187         Updates from a remote repository.
188
189 gitlink:git-http-fetch[1]::
190         Downloads a remote git repository via HTTP
191
192 gitlink:git-local-fetch[1]::
193         Duplicates another git repository on a local system
194
195 gitlink:git-peek-remote[1]::
196         Lists references on a remote repository using upload-pack protocol.
197
198 gitlink:git-receive-pack[1]::
199         Invoked by 'git-send-pack' to receive what is pushed to it.
200
201 gitlink:git-send-pack[1]::
202         Pushes to a remote repository, intelligently.
203
204 gitlink:git-shell[1]::
205         Restricted shell for GIT-only SSH access.
206
207 gitlink:git-ssh-fetch[1]::
208         Pulls from a remote repository over ssh connection
209
210 gitlink:git-ssh-upload[1]::
211         Helper "server-side" program used by git-ssh-fetch
212
213 gitlink:git-update-server-info[1]::
214         Updates auxiliary information on a dumb server to help
215         clients discover references and packs on it.
216
217 gitlink:git-upload-pack[1]::
218         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
219         what are asked for.
220
221
222 Porcelain-ish Commands
223 ----------------------
224
225 gitlink:git-add[1]::
226         Add paths to the index file.
227
228 gitlink:git-am[1]::
229         Apply patches from a mailbox, but cooler.
230
231 gitlink:git-applymbox[1]::
232         Apply patches from a mailbox.
233
234 gitlink:git-bisect[1]::
235         Find the change that introduced a bug.
236
237 gitlink:git-branch[1]::
238         Create and Show branches.
239
240 gitlink:git-checkout[1]::
241         Checkout and switch to a branch.
242
243 gitlink:git-cherry-pick[1]::
244         Cherry-pick the effect of an existing commit.
245
246 gitlink:git-clone[1]::
247         Clones a repository into a new directory.
248
249 gitlink:git-commit[1]::
250         Record changes to the repository.
251
252 gitlink:git-diff[1]::
253         Show changes between commits, commit and working tree, etc.
254
255 gitlink:git-fetch[1]::
256         Download from a remote repository via various protocols.
257
258 gitlink:git-format-patch[1]::
259         Prepare patches for e-mail submission.
260
261 gitlink:git-grep[1]::
262         Print lines matching a pattern
263
264 gitlink:git-log[1]::
265         Shows commit logs.
266
267 gitlink:git-ls-remote[1]::
268         Shows references in a remote or local repository.
269
270 gitlink:git-merge[1]::
271         Grand unified merge driver.
272
273 gitlink:git-mv[1]::
274         Move or rename a file, a directory, or a symlink.
275
276 gitlink:git-octopus[1]::
277         Merge more than two commits.
278
279 gitlink:git-pull[1]::
280         Fetch from and merge with a remote repository.
281
282 gitlink:git-push[1]::
283         Update remote refs along with associated objects.
284
285 gitlink:git-rebase[1]::
286         Rebase local commits to new upstream head.
287
288 gitlink:git-repack[1]::
289         Pack unpacked objects in a repository.
290
291 gitlink:git-reset[1]::
292         Reset current HEAD to the specified state.
293
294 gitlink:git-resolve[1]::
295         Merge two commits.
296
297 gitlink:git-revert[1]::
298         Revert an existing commit.
299
300 gitlink:git-shortlog[1]::
301         Summarizes 'git log' output.
302
303 gitlink:git-show-branch[1]::
304         Show branches and their commits.
305
306 gitlink:git-status[1]::
307         Shows the working tree status.
308
309 gitlink:git-verify-tag[1]::
310         Check the GPG signature of tag.
311
312 gitlink:git-whatchanged[1]::
313         Shows commit logs and differences they introduce.
314
315
316 Ancillary Commands
317 ------------------
318 Manipulators:
319
320 gitlink:git-applypatch[1]::
321         Apply one patch extracted from an e-mail.
322
323 gitlink:git-archimport[1]::
324         Import an arch repository into git.
325
326 gitlink:git-convert-objects[1]::
327         Converts old-style git repository
328
329 gitlink:git-cvsimport[1]::
330         Salvage your data out of another SCM people love to hate.
331
332 gitlink:git-lost-found[1]::
333         Recover lost refs that luckily have not yet been pruned.
334
335 gitlink:git-merge-one-file[1]::
336         The standard helper program to use with "git-merge-index"
337
338 gitlink:git-prune[1]::
339         Prunes all unreachable objects from the object database
340
341 gitlink:git-relink[1]::
342         Hardlink common objects in local repositories.
343
344 gitlink:git-svnimport[1]::
345         Import a SVN repository into git.
346
347 gitlink:git-sh-setup[1]::
348         Common git shell script setup code.
349
350 gitlink:git-symbolic-ref[1]::
351         Read and modify symbolic refs
352
353 gitlink:git-tag[1]::
354         An example script to create a tag object signed with GPG
355
356 gitlink:git-update-ref[1]::
357         Update the object name stored in a ref safely.
358
359
360 Interrogators:
361
362 gitlink:git-check-ref-format[1]::
363         Make sure ref name is well formed.
364
365 gitlink:git-cherry[1]::
366         Find commits not merged upstream.
367
368 gitlink:git-count-objects[1]::
369         Count unpacked number of objects and their disk consumption.
370
371 gitlink:git-daemon[1]::
372         A really simple server for git repositories.
373
374 gitlink:git-get-tar-commit-id[1]::
375         Extract commit ID from an archive created using git-tar-tree.
376
377 gitlink:git-mailinfo[1]::
378         Extracts patch from a single e-mail message.
379
380 gitlink:git-mailsplit[1]::
381         git-mailsplit.
382
383 gitlink:git-patch-id[1]::
384         Compute unique ID for a patch.
385
386 gitlink:git-parse-remote[1]::
387         Routines to help parsing $GIT_DIR/remotes/
388
389 gitlink:git-request-pull[1]::
390         git-request-pull.
391
392 gitlink:git-rev-parse[1]::
393         Pick out and massage parameters.
394
395 gitlink:git-send-email[1]::
396         Send patch e-mails out of "format-patch --mbox" output.
397
398 gitlink:git-symbolic-refs[1]::
399         Read and modify symbolic refs.
400
401 gitlink:git-stripspace[1]::
402         Filter out empty lines.
403
404
405 Commands not yet documented
406 ---------------------------
407
408 gitlink:gitk[1]::
409         gitk.
410
411
412 Configuration Mechanism
413 -----------------------
414
415 Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
416 is used to hold per-repository configuration options.  It is a
417 simple text file modelled after `.ini` format familiar to some
418 people.  Here is an example:
419
420 ------------
421 #
422 # This is the config file, and
423 # a '#' or ';' character indicates
424 # a comment
425 #
426
427 ; core variables
428 [core]
429         ; Don't trust file modes
430         filemode = false
431
432 ; user identity
433 [user]
434         name = "Junio C Hamano"
435         email = "junkio@twinsun.com"
436
437 ------------
438
439 Various commands read from the configuration file and adjust
440 their operation accordingly.
441
442
443 Identifier Terminology
444 ----------------------
445 <object>::
446         Indicates the sha1 identifier for any type of object
447
448 <blob>::
449         Indicates a blob object sha1 identifier
450
451 <tree>::
452         Indicates a tree object sha1 identifier
453
454 <commit>::
455         Indicates a commit object sha1 identifier
456
457 <tree-ish>::
458         Indicates a tree, commit or tag object sha1 identifier.  A
459         command that takes a <tree-ish> argument ultimately wants to
460         operate on a <tree> object but automatically dereferences
461         <commit> and <tag> objects that point at a <tree>.
462
463 <type>::
464         Indicates that an object type is required.
465         Currently one of: blob/tree/commit/tag
466
467 <file>::
468         Indicates a filename - always relative to the root of
469         the tree structure GIT_INDEX_FILE describes.
470
471 Symbolic Identifiers
472 --------------------
473 Any git command accepting any <object> can also use the following
474 symbolic notation:
475
476 HEAD::
477         indicates the head of the repository (ie the contents of
478         `$GIT_DIR/HEAD`)
479 <tag>::
480         a valid tag 'name'+
481         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
482 <head>::
483         a valid head 'name'+
484         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
485 <snap>::
486         a valid snapshot 'name'+
487         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
488
489
490 File/Directory Structure
491 ------------------------
492
493 Please see link:repository-layout.html[repository layout] document.
494
495 Higher level SCMs may provide and manage additional information in the
496 GIT_DIR.
497
498
499 Terminology
500 -----------
501 Please see link:glossary.html[glossary] document.
502
503
504 Environment Variables
505 ---------------------
506 Various git commands use the following environment variables:
507
508 The git Repository
509 ~~~~~~~~~~~~~~~~~~
510 These environment variables apply to 'all' core git commands. Nb: it
511 is worth noting that they may be used/overridden by SCMS sitting above
512 git so take care if using Cogito etc
513
514 'GIT_INDEX_FILE'::
515         This environment allows the specification of an alternate
516         index file. If not specified, the default of `$GIT_DIR/index`
517         is used.
518
519 'GIT_OBJECT_DIRECTORY'::
520         If the object storage directory is specified via this
521         environment variable then the sha1 directories are created
522         underneath - otherwise the default `$GIT_DIR/objects`
523         directory is used.
524
525 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
526         Due to the immutable nature of git objects, old objects can be
527         archived into shared, read-only directories. This variable
528         specifies a ":" separated list of git object directories which
529         can be used to search for git objects. New objects will not be
530         written to these directories.
531
532 'GIT_DIR'::
533         If the 'GIT_DIR' environment variable is set then it specifies
534         a path to use instead of `./.git` for the base of the
535         repository.
536
537 git Commits
538 ~~~~~~~~~~~
539 'GIT_AUTHOR_NAME'::
540 'GIT_AUTHOR_EMAIL'::
541 'GIT_AUTHOR_DATE'::
542 'GIT_COMMITTER_NAME'::
543 'GIT_COMMITTER_EMAIL'::
544         see gitlink:git-commit-tree[1]
545
546 git Diffs
547 ~~~~~~~~~
548 'GIT_DIFF_OPTS'::
549 'GIT_EXTERNAL_DIFF'::
550         see the "generating patches" section in :
551         gitlink:git-diff-index[1];
552         gitlink:git-diff-files[1];
553         gitlink:git-diff-tree[1]
554
555 Discussion[[Discussion]]
556 ------------------------
557 include::../README[]
558
559 Authors
560 -------
561         git's founding father is Linus Torvalds <torvalds@osdl.org>.
562         The current git nurse is Junio C. Hamano <junkio@cox.net>.
563         The git potty was written by Andres Ericsson <ae@op5.se>.
564         General upbringing is handled by the git-list <git@vger.kernel.org>.
565
566 Documentation
567 --------------
568 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
569
570 GIT
571 ---
572 Part of the gitlink:git[7] suite
573