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