Document git-merge-cache -o
[git/git.git] / Documentation / git.txt
CommitLineData
2cf565c5
DG
1git(1)
2======
3v0.1, May 2005
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
19The link:README[] contains much useful definition and clarification
20info - read that first. And of the commands, I suggest reading
21'git-update-cache' and 'git-read-tree' first - I wish I had!
22
23David Greaves <david@dgreaves.com>
2408/05/05
25
26Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
27reflect recent changes.
28
29Commands Overview
30-----------------
31The git commands can helpfully be split into those that manipulate
32the repository, the cache and the working fileset and those that
33interrogate and compare them.
34
204ee6a9
DG
35There are also some ancilliary programs that can be viewed as useful
36aids for using the core commands but which are unlikely to be used by
37SCMs layered over git.
38
2cf565c5
DG
39Manipulation commands
40~~~~~~~~~~~~~~~~~~~~~
2cf565c5
DG
41link:git-checkout-cache.html[git-checkout-cache]::
42 Copy files from the cache to the working directory
43
44link:git-commit-tree.html[git-commit-tree]::
45 Creates a new commit object
46
2cf565c5
DG
47link:git-init-db.html[git-init-db]::
48 Creates an empty git object database
49
2cf565c5
DG
50link:git-merge-base.html[git-merge-base]::
51 Finds as good a common ancestor as possible for a merge
52
2cf565c5
DG
53link:git-mktag.html[git-mktag]::
54 Creates a tag object
55
2cf565c5
DG
56link:git-read-tree.html[git-read-tree]::
57 Reads tree information into the directory cache
58
2cf565c5
DG
59link:git-update-cache.html[git-update-cache]::
60 Modifies the index or directory cache
61
62link:git-write-blob.html[git-write-blob]::
63 Creates a blob from a file
64
65link:git-write-tree.html[git-write-tree]::
66 Creates a tree from the current cache
67
68Interrogation commands
69~~~~~~~~~~~~~~~~~~~~~~
70link:git-cat-file.html[git-cat-file]::
71 Provide content or type information for repository objects
72
73link:git-check-files.html[git-check-files]::
74 Verify a list of files are up-to-date
75
76link:git-diff-cache.html[git-diff-cache]::
77 Compares content and mode of blobs between the cache and repository
78
79link:git-diff-files.html[git-diff-files]::
80 Compares files in the working tree and the cache
81
82link:git-diff-tree.html[git-diff-tree]::
83 Compares the content and mode of blobs found via two tree objects
84
2cf565c5
DG
85link:git-export.html[git-export]::
86 Exports each commit and a diff against each of its parents
87
88link:git-fsck-cache.html[git-fsck-cache]::
89 Verifies the connectivity and validity of the objects in the database
90
91link:git-ls-files.html[git-ls-files]::
92 Information about files in the cache/working directory
93
94link:git-ls-tree.html[git-ls-tree]::
95 Displays a tree object in human readable form
96
97link:git-merge-cache.html[git-merge-cache]::
98 Runs a merge for files needing merging
99
100link:git-rev-list.html[git-rev-list]::
101 Lists commit objects in reverse chronological order
102
103link:git-rev-tree.html[git-rev-tree]::
104 Provides the revision tree for one or more commits
105
2cf565c5
DG
106link:git-tar-tree.html[git-tar-tree]::
107 Creates a tar archive of the files in the named tree
108
109link:git-unpack-file.html[git-unpack-file]::
110 Creates a temporary file with a blob's contents
111
112The interrogate commands may create files - and you can force them to
113touch the working file set - but in general they don't
114
115
204ee6a9
DG
116Ancilliary Commands
117-------------------
118Manipulators:
119
120link:git-apply-patch-script.html[git-apply-patch-script]::
121 Sample script to apply the diffs from git-diff-*
122
123link:git-convert-cache.html[git-convert-cache]::
124 Converts old-style GIT repository
125
126link:git-http-pull.html[git-http-pull]::
127 Downloads a remote GIT repository via HTTP
128
129link:git-local-pull.html[git-local-pull]::
130 Duplicates another GIT repository on a local system
131
132link:git-merge-one-file-script.html[git-merge-one-file-script]::
133 The standard helper program to use with "git-merge-cache"
134
135link:git-pull-script.html[git-pull-script]::
136 Script used by Linus to pull and merge a remote repository
137
138link:git-prune-script.html[git-prune-script]::
139 Prunes all unreachable objects from the object database
140
141link:git-resolve-script.html[git-resolve-script]::
142 Script used to merge two trees
143
144link:git-tag-script.html[git-tag-script]::
145 An example script to create a tag object signed with GPG
146
147link:git-rpull.html[git-rpull]::
148 Pulls from a remote repository over ssh connection
149
150Interogators:
151
152link:git-diff-tree-helper.html[git-diff-tree-helper]::
153 Generates patch format output for git-diff-*
154
155link:git-rpush.html[git-rpush]::
156 Helper "server-side" program used by git-rpull
157
158
159
2cf565c5
DG
160Terminology
161-----------
162see README for description
163
164Identifier terminology
165----------------------
166<object>::
167 Indicates any object sha1 identifier
168
169<blob>::
170 Indicates a blob object sha1 identifier
171
172<tree>::
173 Indicates a tree object sha1 identifier
174
175<commit>::
176 Indicates a commit object sha1 identifier
177
178<tree-ish>::
179 Indicates a tree, commit or tag object sha1 identifier.
180 A command that takes a <tree-ish> argument ultimately
181 wants to operate on a <tree> object but automatically
182 dereferences <commit> and <tag> that points at a
183 <tree>.
184
185<type>::
186 Indicates that an object type is required.
187 Currently one of: blob/tree/commit/tag
188
189<file>::
190 Indicates a filename - always relative to the root of
191 the tree structure GIT_INDEX_FILE describes.
192
c1bdacf9
DG
193Symbolic Identifiers
194--------------------
195Any git comand accepting any <object> can also use the following symbolic notation:
196
197HEAD::
198 indicates the head of the repository (ie the contents of `$GIT_DIR/HEAD`)
199<tag>::
200 a valid tag 'name'+
201 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
202<head>::
203 a valid head 'name'+
204 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
205<snap>::
206 a valid snapshot 'name'+
207 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
208
209
210File/Directory Structure
211------------------------
212The git-core manipulates the following areas in the directory:
213
214 .git/ The base (overridden with $GIT_DIR)
215 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
216 ??/ 'First 2 chars of object' directories
217
218It can interrogate (but never updates) the following areas:
219
220 refs/ Directories containing symbolic names for objects
221 (each file contains the hex SHA1 + newline)
222 heads/ Commits which are heads of various sorts
223 tags/ Tags, by the tag name (or some local renaming of it)
224 snap/ ????
225 ... Everything else isn't shared
226 HEAD Symlink to refs/heads/<something>
227
228Higher level SCMs may provide and manage additional information in the
229GIT_DIR.
230
2cf565c5
DG
231Terminology
232-----------
233Each line contains terms used interchangeably
234
235 object database, .git directory
236 directory cache, index
237 id, sha1, sha1-id, sha1 hash
238 type, tag
239 blob, blob object
240 tree, tree object
241 commit, commit object
242 parent
243 root object
244 changeset
245
246
247Environment Variables
248---------------------
249Various git commands use the following environment variables:
250
c1bdacf9
DG
251The git Repository
252~~~~~~~~~~~~~~~~~~
253These environment variables apply to 'all' core git commands. Nb: it
254is worth noting that they may be used/overridden by SCMS sitting above
255git so take care if using Cogito etc
256
257'GIT_INDEX_FILE'::
258 This environment allows the specification of an alternate
259 cache/index file. If not specified, the default of
260 `$GIT_DIR/index` is used.
261
262'GIT_OBJECT_DIRECTORY'::
263 If the object storage directory is specified via this
264 environment variable then the sha1 directories are created
265 underneath - otherwise the default `$GIT_DIR/objects`
266 directory is used.
267
268'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
269 Due to the immutable nature of git objects, old objects can be
270 archived into shared, read-only directories. This variable
271 specifies a ":" seperated list of git object directories which
272 can be used to search for git objects. New objects will not be
273 written to these directories.
274
275'GIT_DIR'::
276 If the 'GIT_DIR' environment variable is set then it specifies
277 a path to use instead of `./.git` for the base of the
278 repository.
279
280git Commits
281~~~~~~~~~~~
282'GIT_AUTHOR_NAME'::
283'GIT_AUTHOR_EMAIL'::
284'GIT_AUTHOR_DATE'::
285'GIT_COMMITTER_NAME'::
286'GIT_COMMITTER_EMAIL'::
287 see link:git-commit-tree.html[git-commit-tree]
288
289git Diffs
290~~~~~~~~~
291GIT_DIFF_OPTS::
292GIT_EXTERNAL_DIFF::
293 see the "generating patches" section in :
294 link:git-diff-cache.html[git-diff-cache];
295 link:git-diff-files.html[git-diff-files];
296 link:git-diff-tree.html[git-diff-tree]
2cf565c5
DG
297
298Author
299------
300Written by Linus Torvalds <torvalds@osdl.org>
301
302Documentation
303--------------
304Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
305
306GIT
307---
308Part of the link:git.html[git] suite
309