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