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