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