git.txt 17.6 KB
Newer Older
1
git(7)
2 3 4 5 6 7 8 9 10
======

NAME
----
git - the stupid content tracker


SYNOPSIS
--------
11
[verse]
12 13
'git' [--version] [--exec-path[=GIT_EXEC_PATH]]
    [-p|--paginate|--no-pager]
14 15
    [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
    [--help] COMMAND [ARGS]
16 17 18

DESCRIPTION
-----------
19 20 21 22 23 24 25
Git is a fast, scalable, distributed revision control system with an
unusually rich command set that provides both high-level operations
and full access to internals.

See this link:tutorial.html[tutorial] to get started, then see
link:everyday.html[Everyday Git] for a useful minimum set of commands, and
"man git-commandname" for documentation of each command.  CVS users may
26 27 28
also want to read link:cvs-migration.html[CVS migration].  See
link:user-manual.html[Git User's Manual] for a more in-depth
introduction.
29

P
Petr Baudis 已提交
30
The COMMAND is either a name of a Git command (see below) or an alias
31
as defined in the configuration file (see linkgit:git-config[1]).
P
Petr Baudis 已提交
32

33 34 35 36
Formatted and hyperlinked version of the latest git
documentation can be viewed at
`http://www.kernel.org/pub/software/scm/git/docs/`.

37 38 39 40
ifdef::stalenotes[]
[NOTE]
============

41 42 43 44
You are reading the documentation for the latest (possibly
unreleased) version of git, that is available from 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
45

46
* link:v1.5.4.4/git.html[documentation for release 1.5.4.4]
47 48

* release notes for
49
  link:RelNotes-1.5.4.4.txt[1.5.4.4],
J
Junio C Hamano 已提交
50
  link:RelNotes-1.5.4.3.txt[1.5.4.3],
51
  link:RelNotes-1.5.4.2.txt[1.5.4.2],
52
  link:RelNotes-1.5.4.1.txt[1.5.4.1],
53 54
  link:RelNotes-1.5.4.txt[1.5.4].

J
Junio C Hamano 已提交
55
* link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
56 57

* release notes for
J
Junio C Hamano 已提交
58
  link:RelNotes-1.5.3.8.txt[1.5.3.8],
J
Junio C Hamano 已提交
59
  link:RelNotes-1.5.3.7.txt[1.5.3.7],
60
  link:RelNotes-1.5.3.6.txt[1.5.3.6],
61
  link:RelNotes-1.5.3.5.txt[1.5.3.5],
62
  link:RelNotes-1.5.3.4.txt[1.5.3.4],
63
  link:RelNotes-1.5.3.3.txt[1.5.3.3],
64
  link:RelNotes-1.5.3.2.txt[1.5.3.2],
65 66
  link:RelNotes-1.5.3.1.txt[1.5.3.1],
  link:RelNotes-1.5.3.txt[1.5.3].
67

J
Junio C Hamano 已提交
68
* release notes for
69
  link:RelNotes-1.5.2.5.txt[1.5.2.5],
J
Junio C Hamano 已提交
70
  link:RelNotes-1.5.2.4.txt[1.5.2.4],
71
  link:RelNotes-1.5.2.3.txt[1.5.2.3],
72 73
  link:RelNotes-1.5.2.2.txt[1.5.2.2],
  link:RelNotes-1.5.2.1.txt[1.5.2.1],
J
Junio C Hamano 已提交
74 75 76 77 78 79 80
  link:RelNotes-1.5.2.txt[1.5.2].

* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]

* release notes for
  link:RelNotes-1.5.1.6.txt[1.5.1.6],
  link:RelNotes-1.5.1.5.txt[1.5.1.5],
81 82 83 84 85 86 87 88
  link:RelNotes-1.5.1.4.txt[1.5.1.4],
  link:RelNotes-1.5.1.3.txt[1.5.1.3],
  link:RelNotes-1.5.1.2.txt[1.5.1.2],
  link:RelNotes-1.5.1.1.txt[1.5.1.1],
  link:RelNotes-1.5.1.txt[1.5.1].

* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]

J
Junio C Hamano 已提交
89 90
* release notes for
  link:RelNotes-1.5.0.7.txt[1.5.0.7],
91 92 93 94 95 96 97 98 99 100 101
  link:RelNotes-1.5.0.6.txt[1.5.0.6],
  link:RelNotes-1.5.0.5.txt[1.5.0.5],
  link:RelNotes-1.5.0.3.txt[1.5.0.3],
  link:RelNotes-1.5.0.2.txt[1.5.0.2],
  link:RelNotes-1.5.0.1.txt[1.5.0.1],
  link:RelNotes-1.5.0.txt[1.5.0].

* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
  link:v1.3.3/git.html[1.3.3],
  link:v1.2.6/git.html[1.2.6],
  link:v1.0.13/git.html[1.0.13].
102 103 104 105 106

============

endif::stalenotes[]

107 108 109
OPTIONS
-------
--version::
F
Fredrik Kuivinen 已提交
110
	Prints the git suite version that the 'git' program came from.
111 112

--help::
F
Fredrik Kuivinen 已提交
113
	Prints the synopsis and a list of the most commonly used
114 115 116
	commands. If the option '--all' or '-a' is given then all
	available commands are printed. If a git command is named this
	option will bring up the manual page for that command.
117 118
+
Other options are available to control how the manual page is
119
displayed. See linkgit:git-help[1] for more information,
120 121
because 'git --help ...' is converted internally into 'git
help ...'.
122 123

--exec-path::
F
Fredrik Kuivinen 已提交
124
	Path to wherever your core git programs are installed.
125 126 127 128
	This can also be controlled by setting the GIT_EXEC_PATH
	environment variable. If no path is given 'git' will print
	the current setting and then exit.

129 130 131
-p|--paginate::
	Pipe all output into 'less' (or if set, $PAGER).

132 133 134
--no-pager::
	Do not pipe git output into a pager.

135 136 137 138
--git-dir=<path>::
	Set the path to the repository. This can also be controlled by
	setting the GIT_DIR environment variable.

139 140 141 142 143 144 145 146
--work-tree=<path>::
	Set the path to the working tree.  The value will not be
	used in combination with repositories found automatically in
	a .git directory (i.e. $GIT_DIR is not set).
	This can also be controlled by setting the GIT_WORK_TREE
	environment variable and the core.worktree configuration
	variable.

147
--bare::
148 149 150 151
	Treat the repository as a bare repository.  If GIT_DIR
	environment is not set, it is set to the current working
	directory.

152

153 154
FURTHER DOCUMENTATION
---------------------
155

156 157
See the references above to get started using git.  The following is
probably more detail than necessary for a first-time user.
J
Junio C Hamano 已提交
158

159 160 161
The link:user-manual.html#git-concepts[git concepts chapter of the
user-manual] and the link:core-tutorial.html[Core tutorial] both provide
introductions to the underlying git architecture.
162

163 164
See also the link:howto-index.html[howto] documents for some useful
examples.
165

166 167
The internals are documented link:technical/api-index.html[here].

168 169
GIT COMMANDS
------------
170

171 172
We divide git into high level ("porcelain") commands and low level
("plumbing") commands.
173

174 175 176 177 178 179 180 181
High-level commands (porcelain)
-------------------------------

We separate the porcelain commands into the main commands and some
ancillary user utilities.

Main porcelain commands
~~~~~~~~~~~~~~~~~~~~~~~
182

183
include::cmds-mainporcelain.txt[]
184

185
Ancillary Commands
186
~~~~~~~~~~~~~~~~~~
187 188
Manipulators:

189
include::cmds-ancillarymanipulators.txt[]
190

191
Interrogators:
192

193
include::cmds-ancillaryinterrogators.txt[]
194

195 196 197 198 199 200 201 202 203 204

Interacting with Others
~~~~~~~~~~~~~~~~~~~~~~~

These commands are to interact with foreign SCM and with other
people via patch over e-mail.

include::cmds-foreignscminterface.txt[]


205 206 207 208 209 210
Low-level commands (plumbing)
-----------------------------

Although git includes its
own porcelain layer, its low-level commands are sufficient to support
development of alternative porcelains.  Developers of such porcelains
211 212
might start by reading about linkgit:git-update-index[1] and
linkgit:git-read-tree[1].
213

214 215 216 217 218 219 220 221 222
The interface (input, output, set of options and the semantics)
to these low-level commands are meant to be a lot more stable
than Porcelain level commands, because these commands are
primarily for scripted use.  The interface to Porcelain commands
on the other hand are subject to change in order to improve the
end user experience.

The following description divides
the low-level commands into commands that manipulate objects (in
223 224 225 226
the repository, index, and working tree), commands that interrogate and
compare objects, and commands that move objects and references between
repositories.

227

228 229 230
Manipulation commands
~~~~~~~~~~~~~~~~~~~~~

231
include::cmds-plumbingmanipulators.txt[]
232 233 234 235 236


Interrogation commands
~~~~~~~~~~~~~~~~~~~~~~

237
include::cmds-plumbinginterrogators.txt[]
238 239 240 241 242 243 244 245

In general, the interrogate commands do not touch the files in
the working tree.


Synching repositories
~~~~~~~~~~~~~~~~~~~~~

246
include::cmds-synchingrepositories.txt[]
247

248 249 250 251 252 253 254 255 256 257 258 259 260 261
The following are helper programs used by the above; end users
typically do not use them directly.

include::cmds-synchelpers.txt[]


Internal helper commands
~~~~~~~~~~~~~~~~~~~~~~~~

These are internal helper commands used by other commands; end
users typically do not use them directly.

include::cmds-purehelpers.txt[]

262

J
Junio C Hamano 已提交
263 264 265
Configuration Mechanism
-----------------------

J
Junio C Hamano 已提交
266
Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
J
Junio C Hamano 已提交
267
is used to hold per-repository configuration options.  It is a
P
Pavel Roskin 已提交
268
simple text file modeled after `.ini` format familiar to some
J
Junio C Hamano 已提交
269 270 271 272
people.  Here is an example:

------------
#
J
Junio C Hamano 已提交
273
# A '#' or ';' character indicates a comment.
J
Junio C Hamano 已提交
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
#

; core variables
[core]
	; Don't trust file modes
	filemode = false

; user identity
[user]
	name = "Junio C Hamano"
	email = "junkio@twinsun.com"

------------

Various commands read from the configuration file and adjust
their operation accordingly.


292
Identifier Terminology
293 294
----------------------
<object>::
J
Junio C Hamano 已提交
295
	Indicates the object name for any type of object.
296 297

<blob>::
J
Junio C Hamano 已提交
298
	Indicates a blob object name.
299 300

<tree>::
J
Junio C Hamano 已提交
301
	Indicates a tree object name.
302 303

<commit>::
J
Junio C Hamano 已提交
304
	Indicates a commit object name.
305 306

<tree-ish>::
J
Junio C Hamano 已提交
307
	Indicates a tree, commit or tag object name.  A
308 309 310
	command that takes a <tree-ish> argument ultimately wants to
	operate on a <tree> object but automatically dereferences
	<commit> and <tag> objects that point at a <tree>.
311

312 313 314 315 316 317
<commit-ish>::
	Indicates a commit or tag object name.  A
	command that takes a <commit-ish> argument ultimately wants to
	operate on a <commit> object but automatically dereferences
	<tag> objects that point at a <commit>.

318 319
<type>::
	Indicates that an object type is required.
J
Junio C Hamano 已提交
320
	Currently one of: `blob`, `tree`, `commit`, or `tag`.
321 322

<file>::
J
Junio C Hamano 已提交
323 324
	Indicates a filename - almost always relative to the
	root of the tree structure `GIT_INDEX_FILE` describes.
325

326 327
Symbolic Identifiers
--------------------
328
Any git command accepting any <object> can also use the following
329
symbolic notation:
330 331

HEAD::
J
Junio C Hamano 已提交
332 333 334
	indicates the head of the current branch (i.e. the
	contents of `$GIT_DIR/HEAD`).

335
<tag>::
J
Junio C Hamano 已提交
336 337 338
	a valid tag 'name'
	(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).

339
<head>::
J
Junio C Hamano 已提交
340 341 342
	a valid head 'name'
	(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).

343
For a more complete list of ways to spell object names, see
344
"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
345

346 347 348 349

File/Directory Structure
------------------------

350
Please see the link:repository-layout.html[repository layout] document.
351

352 353
Read link:hooks.html[hooks] for more details about each hook.

354
Higher level SCMs may provide and manage additional information in the
J
Junio C Hamano 已提交
355
`$GIT_DIR`.
356

J
Junio C Hamano 已提交
357

358 359
Terminology
-----------
360
Please see the link:glossary.html[glossary] document.
361 362 363 364 365 366


Environment Variables
---------------------
Various git commands use the following environment variables:

367 368 369 370
The git Repository
~~~~~~~~~~~~~~~~~~
These environment variables apply to 'all' core git commands. Nb: it
is worth noting that they may be used/overridden by SCMS sitting above
J
Junio C Hamano 已提交
371
git so take care if using Cogito etc.
372 373 374

'GIT_INDEX_FILE'::
	This environment allows the specification of an alternate
375 376
	index file. If not specified, the default of `$GIT_DIR/index`
	is used.
377 378 379 380 381 382 383 384 385 386

'GIT_OBJECT_DIRECTORY'::
	If the object storage directory is specified via this
	environment variable then the sha1 directories are created
	underneath - otherwise the default `$GIT_DIR/objects`
	directory is used.

'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
	Due to the immutable nature of git objects, old objects can be
	archived into shared, read-only directories. This variable
387
	specifies a ":" separated list of git object directories which
388 389 390 391
	can be used to search for git objects. New objects will not be
	written to these directories.

'GIT_DIR'::
J
Junio C Hamano 已提交
392 393 394
	If the 'GIT_DIR' environment variable is set then it
	specifies a path to use instead of the default `.git`
	for the base of the repository.
395

396 397 398 399 400 401 402
'GIT_WORK_TREE'::
	Set the path to the working tree.  The value will not be
	used in combination with repositories found automatically in
	a .git directory (i.e. $GIT_DIR is not set).
	This can also be controlled by the '--work-tree' command line
	option and the core.worktree configuration variable.

403 404 405 406 407 408 409
git Commits
~~~~~~~~~~~
'GIT_AUTHOR_NAME'::
'GIT_AUTHOR_EMAIL'::
'GIT_AUTHOR_DATE'::
'GIT_COMMITTER_NAME'::
'GIT_COMMITTER_EMAIL'::
410
'GIT_COMMITTER_DATE'::
411
'EMAIL'::
412
	see linkgit:git-commit-tree[1]
413 414 415

git Diffs
~~~~~~~~~
416
'GIT_DIFF_OPTS'::
417 418 419 420 421
	Only valid setting is "--unified=??" or "-u??" to set the
	number of context lines shown when a unified diff is created.
	This takes precedence over any "-U" or "--unified" option
	value passed on the git diff command line.

422
'GIT_EXTERNAL_DIFF'::
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
	When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
	program named by it is called, instead of the diff invocation
	described above.  For a path that is added, removed, or modified,
        'GIT_EXTERNAL_DIFF' is called with 7 parameters:

	path old-file old-hex old-mode new-file new-hex new-mode
+
where:

	<old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
                         contents of <old|new>,
	<old|new>-hex:: are the 40-hexdigit SHA1 hashes,
	<old|new>-mode:: are the octal representation of the file modes.

+
The file parameters can point at the user's working file
(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
when a new file is added), or a temporary file (e.g. `old-file` in the
index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
+
For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
parameter, <path>.
446

447 448
other
~~~~~
J
Jakub Narebski 已提交
449 450 451
'GIT_MERGE_VERBOSITY'::
	A number controlling the amount of output shown by
	the recursive merge strategy.  Overrides merge.verbosity.
452
	See linkgit:git-merge[1]
J
Jakub Narebski 已提交
453

454
'GIT_PAGER'::
455 456 457
	This environment variable overrides `$PAGER`. If it is set
	to an empty string or to the value "cat", git will not launch
	a pager.
458

459
'GIT_SSH'::
460 461
	If this environment variable is set then linkgit:git-fetch[1]
	and linkgit:git-push[1] will use this command instead
462 463 464 465 466 467 468 469 470 471 472 473 474
	of `ssh` when they need to connect to a remote system.
	The 'GIT_SSH' command will be given exactly two arguments:
	the 'username@host' (or just 'host') from the URL and the
	shell command to execute on that remote system.
+
To pass options to the program that you want to list in GIT_SSH
you will need to wrap the program and options into a shell script,
then set GIT_SSH to refer to the shell script.
+
Usually it is easier to configure any desired options through your
personal `.ssh/config` file.  Please consult your ssh documentation
for further details.

475 476 477 478 479 480 481 482 483 484
'GIT_FLUSH'::
	If this environment variable is set to "1", then commands such
	as git-blame (in incremental mode), git-rev-list, git-log,
	git-whatchanged, etc., will force a flush of the output stream
	after each commit-oriented record have been flushed.   If this
	variable is set to "0", the output of these commands will be done
	using completely buffered I/O.   If this environment variable is
	not set, git will choose buffered or record-oriented flushing
	based on whether stdout appears to be redirected to a file or not.

485
'GIT_TRACE'::
486 487
	If this variable is set to "1", "2" or "true" (comparison
	is case insensitive), git will print `trace:` messages on
488 489
	stderr telling about alias expansion, built-in command
	execution and external command execution.
490 491 492 493 494 495 496 497
	If this variable is set to an integer value greater than 1
	and lower than 10 (strictly) then git will interpret this
	value as an open file descriptor and will try to write the
	trace messages into this file descriptor.
	Alternatively, if this variable is set to an absolute path
	(starting with a '/' character), git will interpret this
	as a file path and will try to write the trace messages
	into it.
498

J
Junio C Hamano 已提交
499 500
Discussion[[Discussion]]
------------------------
501 502 503 504 505 506 507 508 509 510 511 512 513 514

More detail on the following is available from the
link:user-manual.html#git-concepts[git concepts chapter of the
user-manual] and the link:core-tutorial.html[Core tutorial].

A git project normally consists of a working directory with a ".git"
subdirectory at the top level.  The .git directory contains, among other
things, a compressed object database representing the complete history
of the project, an "index" file which links that history to the current
contents of the working tree, and named pointers into that history such
as tags and branch heads.

The object database contains objects of three main types: blobs, which
hold file data; trees, which point to blobs and other trees to build up
R
Ralf Wildenhues 已提交
515
directory hierarchies; and commits, which each reference a single tree
516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534
and some number of parent commits.

The commit, equivalent to what other systems call a "changeset" or
"version", represents a step in the project's history, and each parent
represents an immediately preceding step.  Commits with more than one
parent represent merges of independent lines of development.

All objects are named by the SHA1 hash of their contents, normally
written as a string of 40 hex digits.  Such names are globally unique.
The entire history leading up to a commit can be vouched for by signing
just that commit.  A fourth object type, the tag, is provided for this
purpose.

When first created, objects are stored in individual files, but for
efficiency may later be compressed together into "pack files".

Named pointers called refs mark interesting points in history.  A ref
may contain the SHA1 name of an object or the name of another ref.  Refs
with names beginning `ref/head/` contain the SHA1 name of the most
R
Ralf Wildenhues 已提交
535
recent commit (or "head") of a branch under development.  SHA1 names of
536 537 538 539 540 541 542 543 544 545 546 547 548 549 550
tags of interest are stored under `ref/tags/`.  A special ref named
`HEAD` contains the name of the currently checked-out branch.

The index file is initialized with a list of all paths and, for each
path, a blob object and a set of attributes.  The blob object represents
the contents of the file as of the head of the current branch.  The
attributes (last modified time, size, etc.) are taken from the
corresponding file in the working tree.  Subsequent changes to the
working tree can be found by comparing these attributes.  The index may
be updated with new content, and new commits may be created from the
content stored in the index.

The index is also capable of storing multiple entries (called "stages")
for a given pathname.  These stages are used to hold the various
unmerged version of a file when a merge is in progress.
551

552 553
Authors
-------
554
* git's founding father is Linus Torvalds <torvalds@osdl.org>.
555
* The current git nurse is Junio C Hamano <gitster@pobox.com>.
J
Junio C Hamano 已提交
556
* The git potty was written by Andreas Ericsson <ae@op5.se>.
557
* General upbringing is handled by the git-list <git@vger.kernel.org>.
558 559 560

Documentation
--------------
561 562 563
The documentation for git suite was started by David Greaves
<david@dgreaves.com>, and later enhanced greatly by the
contributors on the git-list <git@vger.kernel.org>.
564 565 566

GIT
---
567
Part of the linkgit:git[7] suite