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