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