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