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