[PATCH] Fixlets on top of Nico's clean-up.
[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
113The interrogate commands may create files - and you can force them to
114touch the working file set - but in general they don't
115
116
204ee6a9
DG
117Ancilliary Commands
118-------------------
119Manipulators:
120
121link:git-apply-patch-script.html[git-apply-patch-script]::
122 Sample script to apply the diffs from git-diff-*
123
124link:git-convert-cache.html[git-convert-cache]::
125 Converts old-style GIT repository
126
127link:git-http-pull.html[git-http-pull]::
128 Downloads a remote GIT repository via HTTP
129
130link:git-local-pull.html[git-local-pull]::
131 Duplicates another GIT repository on a local system
132
133link:git-merge-one-file-script.html[git-merge-one-file-script]::
134 The standard helper program to use with "git-merge-cache"
135
136link:git-pull-script.html[git-pull-script]::
137 Script used by Linus to pull and merge a remote repository
138
139link:git-prune-script.html[git-prune-script]::
140 Prunes all unreachable objects from the object database
141
142link:git-resolve-script.html[git-resolve-script]::
143 Script used to merge two trees
144
145link:git-tag-script.html[git-tag-script]::
146 An example script to create a tag object signed with GPG
147
418aaf84 148link:git-ssh-pull.html[git-ssh-pull]::
204ee6a9
DG
149 Pulls from a remote repository over ssh connection
150
151Interogators:
152
99665af5 153link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
154 Generates patch format output for git-diff-*
155
418aaf84
JH
156link:git-ssh-push.html[git-ssh-push]::
157 Helper "server-side" program used by git-ssh-pull
204ee6a9
DG
158
159
160
6c84e2e0 161Identifier Terminology
2cf565c5
DG
162----------------------
163<object>::
6c84e2e0 164 Indicates the sha1 identifier for any type of object
2cf565c5
DG
165
166<blob>::
167 Indicates a blob object sha1 identifier
168
169<tree>::
170 Indicates a tree object sha1 identifier
171
172<commit>::
173 Indicates a commit object sha1 identifier
174
175<tree-ish>::
6c84e2e0
DG
176 Indicates a tree, commit or tag object sha1 identifier. A
177 command that takes a <tree-ish> argument ultimately wants to
178 operate on a <tree> object but automatically dereferences
179 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
180
181<type>::
182 Indicates that an object type is required.
183 Currently one of: blob/tree/commit/tag
184
185<file>::
186 Indicates a filename - always relative to the root of
187 the tree structure GIT_INDEX_FILE describes.
188
c1bdacf9
DG
189Symbolic Identifiers
190--------------------
6c84e2e0
DG
191Any git comand accepting any <object> can also use the following
192symbolic notation:
c1bdacf9
DG
193
194HEAD::
6c84e2e0
DG
195 indicates the head of the repository (ie the contents of
196 `$GIT_DIR/HEAD`)
c1bdacf9
DG
197<tag>::
198 a valid tag 'name'+
199 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
200<head>::
201 a valid head 'name'+
202 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
203<snap>::
204 a valid snapshot 'name'+
205 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
206
207
208File/Directory Structure
209------------------------
210The git-core manipulates the following areas in the directory:
211
212 .git/ The base (overridden with $GIT_DIR)
213 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
214 ??/ 'First 2 chars of object' directories
215
216It can interrogate (but never updates) the following areas:
217
218 refs/ Directories containing symbolic names for objects
219 (each file contains the hex SHA1 + newline)
220 heads/ Commits which are heads of various sorts
221 tags/ Tags, by the tag name (or some local renaming of it)
222 snap/ ????
223 ... Everything else isn't shared
224 HEAD Symlink to refs/heads/<something>
225
226Higher level SCMs may provide and manage additional information in the
227GIT_DIR.
228
2cf565c5
DG
229Terminology
230-----------
6c84e2e0 231Each line contains terms which you may see used interchangeably
2cf565c5
DG
232
233 object database, .git directory
234 directory cache, index
235 id, sha1, sha1-id, sha1 hash
236 type, tag
2cf565c5
DG
237
238
239Environment Variables
240---------------------
241Various git commands use the following environment variables:
242
c1bdacf9
DG
243The git Repository
244~~~~~~~~~~~~~~~~~~
245These environment variables apply to 'all' core git commands. Nb: it
246is worth noting that they may be used/overridden by SCMS sitting above
247git so take care if using Cogito etc
248
249'GIT_INDEX_FILE'::
250 This environment allows the specification of an alternate
251 cache/index file. If not specified, the default of
252 `$GIT_DIR/index` is used.
253
254'GIT_OBJECT_DIRECTORY'::
255 If the object storage directory is specified via this
256 environment variable then the sha1 directories are created
257 underneath - otherwise the default `$GIT_DIR/objects`
258 directory is used.
259
260'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
261 Due to the immutable nature of git objects, old objects can be
262 archived into shared, read-only directories. This variable
263 specifies a ":" seperated list of git object directories which
264 can be used to search for git objects. New objects will not be
265 written to these directories.
266
267'GIT_DIR'::
268 If the 'GIT_DIR' environment variable is set then it specifies
269 a path to use instead of `./.git` for the base of the
270 repository.
271
272git Commits
273~~~~~~~~~~~
274'GIT_AUTHOR_NAME'::
275'GIT_AUTHOR_EMAIL'::
276'GIT_AUTHOR_DATE'::
277'GIT_COMMITTER_NAME'::
278'GIT_COMMITTER_EMAIL'::
279 see link:git-commit-tree.html[git-commit-tree]
280
281git Diffs
282~~~~~~~~~
d81ed1b5
JH
283'GIT_DIFF_OPTS'::
284'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
285 see the "generating patches" section in :
286 link:git-diff-cache.html[git-diff-cache];
287 link:git-diff-files.html[git-diff-files];
288 link:git-diff-tree.html[git-diff-tree]
2cf565c5 289
6c84e2e0
DG
290Discussion
291----------
292include::../README[]
293
2cf565c5
DG
294Author
295------
6c84e2e0 296Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
297
298Documentation
299--------------
300Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
301
302GIT
303---
304Part of the link:git.html[git] suite
305