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