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