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