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