[PATCH] git-peek-remote: show tags and heads from a remote repository.
[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
aed022ab
EB
114link:git-var.html[git-var]::
115 Displays a git logical variable
116
f9253394
JH
117link:git-verify-pack.html[git-verify-pack]::
118 Validates packed GIT archive files
119
2cf565c5
DG
120The interrogate commands may create files - and you can force them to
121touch the working file set - but in general they don't
122
123
0c04094b
JH
124Synching repositories
125~~~~~~~~~~~~~~~~~~~~~
126
6ec311da
JH
127link:git-clone-script.html[git-clone-script]::
128 Clones a repository into the current repository (user interface)
129
130link:git-clone-pack.html[git-clone-pack]::
131 Clones a repository into the current repository (engine
132 for ssh and local transport)
133
0c04094b 134link:git-fetch-script.html[git-pull-script]::
2f2de9b4
JH
135 Pull from a repote repository via various protocols
136 (user interface).
137
0c04094b
JH
138link:git-pull-script.html[git-pull-script]::
139 Fetch from and merge with a repote repository via
140 various protocols (user interface).
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
163link:git-upload-pack.html[git-upload-pack]::
164 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
165 what are asked for.
166
167
168Ancilliary Commands
169-------------------
170Manipulators:
171
172link:git-apply-patch-script.html[git-apply-patch-script]::
173 Sample script to apply the diffs from git-diff-*
174
175link:git-convert-cache.html[git-convert-cache]::
176 Converts old-style GIT repository
177
204ee6a9
DG
178link:git-merge-one-file-script.html[git-merge-one-file-script]::
179 The standard helper program to use with "git-merge-cache"
180
204ee6a9
DG
181link:git-prune-script.html[git-prune-script]::
182 Prunes all unreachable objects from the object database
183
184link:git-resolve-script.html[git-resolve-script]::
185 Script used to merge two trees
186
187link:git-tag-script.html[git-tag-script]::
188 An example script to create a tag object signed with GPG
189
204ee6a9
DG
190
191Interogators:
192
99665af5 193link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
194 Generates patch format output for git-diff-*
195
418aaf84
JH
196link:git-ssh-push.html[git-ssh-push]::
197 Helper "server-side" program used by git-ssh-pull
204ee6a9
DG
198
199
200
6c84e2e0 201Identifier Terminology
2cf565c5
DG
202----------------------
203<object>::
6c84e2e0 204 Indicates the sha1 identifier for any type of object
2cf565c5
DG
205
206<blob>::
207 Indicates a blob object sha1 identifier
208
209<tree>::
210 Indicates a tree object sha1 identifier
211
212<commit>::
213 Indicates a commit object sha1 identifier
214
215<tree-ish>::
6c84e2e0
DG
216 Indicates a tree, commit or tag object sha1 identifier. A
217 command that takes a <tree-ish> argument ultimately wants to
218 operate on a <tree> object but automatically dereferences
219 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
220
221<type>::
222 Indicates that an object type is required.
223 Currently one of: blob/tree/commit/tag
224
225<file>::
226 Indicates a filename - always relative to the root of
227 the tree structure GIT_INDEX_FILE describes.
228
c1bdacf9
DG
229Symbolic Identifiers
230--------------------
6c84e2e0
DG
231Any git comand accepting any <object> can also use the following
232symbolic notation:
c1bdacf9
DG
233
234HEAD::
6c84e2e0
DG
235 indicates the head of the repository (ie the contents of
236 `$GIT_DIR/HEAD`)
c1bdacf9
DG
237<tag>::
238 a valid tag 'name'+
239 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
240<head>::
241 a valid head 'name'+
242 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
243<snap>::
244 a valid snapshot 'name'+
245 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
246
247
248File/Directory Structure
249------------------------
250The git-core manipulates the following areas in the directory:
251
252 .git/ The base (overridden with $GIT_DIR)
253 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
2f2de9b4
JH
254 ??/ 'First 2 chars of object' directories.
255 pack/ Packed archives.
c1bdacf9
DG
256
257 refs/ Directories containing symbolic names for objects
258 (each file contains the hex SHA1 + newline)
259 heads/ Commits which are heads of various sorts
260 tags/ Tags, by the tag name (or some local renaming of it)
2f2de9b4
JH
261 */ Any other subdirectory of refs/ can be used to store
262 files similar to what are under refs/heads/.
263 HEAD Symlink to refs/heads/<current-branch-name>
c1bdacf9
DG
264
265Higher level SCMs may provide and manage additional information in the
266GIT_DIR.
267
2cf565c5
DG
268Terminology
269-----------
6c84e2e0 270Each line contains terms which you may see used interchangeably
2cf565c5
DG
271
272 object database, .git directory
273 directory cache, index
274 id, sha1, sha1-id, sha1 hash
275 type, tag
2cf565c5
DG
276
277
278Environment Variables
279---------------------
280Various git commands use the following environment variables:
281
c1bdacf9
DG
282The git Repository
283~~~~~~~~~~~~~~~~~~
284These environment variables apply to 'all' core git commands. Nb: it
285is worth noting that they may be used/overridden by SCMS sitting above
286git so take care if using Cogito etc
287
288'GIT_INDEX_FILE'::
289 This environment allows the specification of an alternate
290 cache/index file. If not specified, the default of
291 `$GIT_DIR/index` is used.
292
293'GIT_OBJECT_DIRECTORY'::
294 If the object storage directory is specified via this
295 environment variable then the sha1 directories are created
296 underneath - otherwise the default `$GIT_DIR/objects`
297 directory is used.
298
299'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
300 Due to the immutable nature of git objects, old objects can be
301 archived into shared, read-only directories. This variable
302 specifies a ":" seperated list of git object directories which
303 can be used to search for git objects. New objects will not be
304 written to these directories.
305
306'GIT_DIR'::
307 If the 'GIT_DIR' environment variable is set then it specifies
308 a path to use instead of `./.git` for the base of the
309 repository.
310
311git Commits
312~~~~~~~~~~~
313'GIT_AUTHOR_NAME'::
314'GIT_AUTHOR_EMAIL'::
315'GIT_AUTHOR_DATE'::
316'GIT_COMMITTER_NAME'::
317'GIT_COMMITTER_EMAIL'::
318 see link:git-commit-tree.html[git-commit-tree]
319
320git Diffs
321~~~~~~~~~
d81ed1b5
JH
322'GIT_DIFF_OPTS'::
323'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
324 see the "generating patches" section in :
325 link:git-diff-cache.html[git-diff-cache];
326 link:git-diff-files.html[git-diff-files];
327 link:git-diff-tree.html[git-diff-tree]
2cf565c5 328
6c84e2e0
DG
329Discussion
330----------
331include::../README[]
332
2cf565c5
DG
333Author
334------
6c84e2e0 335Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
336
337Documentation
338--------------
339Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
340
341GIT
342---
343Part of the link:git.html[git] suite
344