1 git(7)
2 ======
3 v0.99.5, Aug 2005
5 NAME
6 ----
7 git - the stupid content tracker
10 SYNOPSIS
11 --------
12 'git-<command>' <args>
14 DESCRIPTION
15 -----------
17 This is reference information for the core git commands.
19 Before reading this cover to cover, you may want to take a look
20 at the link:tutorial.html[tutorial] document.
22 The <<Discussion>> section below contains much useful definition and
23 clarification info - read that first. And of the commands, I suggest
24 reading link:git-update-cache.html[git-update-cache] and
25 link:git-read-tree.html[git-read-tree] first - I wish I had!
27 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
28 document may be helpful after you finish the tutorial.
30 After you get the general feel from the tutorial and this
31 overview page, you may want to take a look at the
32 link:howto-index.html[howto] documents.
35 David Greaves <david@dgreaves.com>
36 08/05/05
38 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
39 reflect recent changes.
41 Commands Overview
42 -----------------
43 The git commands can helpfully be split into those that manipulate
44 the repository, the cache and the working fileset, those that
45 interrogate and compare them, and those that moves objects and
46 references between repositories.
48 In addition, git itself comes with a spartan set of porcelain
49 commands. They are usable but are not meant to compete with real
50 Porcelains.
52 There are also some ancillary programs that can be viewed as useful
53 aids for using the core commands but which are unlikely to be used by
54 SCMs layered over git.
56 Manipulation commands
57 ~~~~~~~~~~~~~~~~~~~~~
58 link:git-apply.html[git-apply]::
59 Reads a "diff -up1" or git generated patch file and
60 applies it to the working tree.
62 link:git-checkout-cache.html[git-checkout-cache]::
63 Copy files from the cache to the working directory
65 link:git-commit-tree.html[git-commit-tree]::
66 Creates a new commit object
68 link:git-hash-object.html[git-hash-object]::
69 Computes the object ID from a file.
71 link:git-init-db.html[git-init-db]::
72 Creates an empty git object database
74 link:git-merge-cache.html[git-merge-cache]::
75 Runs a merge for files needing merging
77 link:git-mktag.html[git-mktag]::
78 Creates a tag object
80 link:git-pack-objects.html[git-pack-objects]::
81 Creates a packed archive of objects.
83 link:git-prune-packed.html[git-prune-packed]::
84 Remove extra objects that are already in pack files.
86 link:git-read-tree.html[git-read-tree]::
87 Reads tree information into the directory cache
89 link:git-unpack-objects.html[git-unpack-objects]::
90 Unpacks objects out of a packed archive.
92 link:git-update-cache.html[git-update-cache]::
93 Modifies the index or directory cache
95 link:git-write-tree.html[git-write-tree]::
96 Creates a tree from the current cache
99 Interrogation commands
100 ~~~~~~~~~~~~~~~~~~~~~~
102 link:git-cat-file.html[git-cat-file]::
103 Provide content or type information for repository objects
105 link:git-diff-cache.html[git-diff-cache]::
106 Compares content and mode of blobs between the cache and repository
108 link:git-diff-files.html[git-diff-files]::
109 Compares files in the working tree and the cache
111 link:git-diff-stages.html[git-diff-stages]::
112 Compares two "merge stages" in the index file.
114 link:git-diff-tree.html[git-diff-tree]::
115 Compares the content and mode of blobs found via two tree objects
117 link:git-export.html[git-export]::
118 Exports each commit and a diff against each of its parents
120 link:git-fsck-cache.html[git-fsck-cache]::
121 Verifies the connectivity and validity of the objects in the database
123 link:git-ls-files.html[git-ls-files]::
124 Information about files in the cache/working directory
126 link:git-ls-tree.html[git-ls-tree]::
127 Displays a tree object in human readable form
129 link:git-merge-base.html[git-merge-base]::
130 Finds as good a common ancestor as possible for a merge
132 link:git-rev-list.html[git-rev-list]::
133 Lists commit objects in reverse chronological order
135 link:git-rev-tree.html[git-rev-tree]::
136 Provides the revision tree for one or more commits
138 link:git-show-index.html[git-show-index]::
139 Displays contents of a pack idx file.
141 link:git-tar-tree.html[git-tar-tree]::
142 Creates a tar archive of the files in the named tree
144 link:git-unpack-file.html[git-unpack-file]::
145 Creates a temporary file with a blob's contents
147 link:git-var.html[git-var]::
148 Displays a git logical variable
150 link:git-verify-pack.html[git-verify-pack]::
151 Validates packed GIT archive files
153 The interrogate commands may create files - and you can force them to
154 touch the working file set - but in general they don't
157 Synching repositories
158 ~~~~~~~~~~~~~~~~~~~~~
160 link:git-clone-pack.html[git-clone-pack]::
161 Clones a repository into the current repository (engine
162 for ssh and local transport)
164 link:git-fetch-pack.html[git-fetch-pack]::
165 Updates from a remote repository.
167 link:git-http-pull.html[git-http-pull]::
168 Downloads a remote GIT repository via HTTP
170 link:git-local-pull.html[git-local-pull]::
171 Duplicates another GIT repository on a local system
173 link:git-peek-remote.html[git-peek-remote]::
174 Lists references on a remote repository using upload-pack protocol.
176 link:git-receive-pack.html[git-receive-pack]::
177 Invoked by 'git-send-pack' to receive what is pushed to it.
179 link:git-send-pack.html[git-send-pack]::
180 Pushes to a remote repository, intelligently.
182 link:git-ssh-pull.html[git-ssh-pull]::
183 Pulls from a remote repository over ssh connection
185 link:git-ssh-push.html[git-ssh-push]::
186 Helper "server-side" program used by git-ssh-pull
188 link:git-update-server-info.html[git-update-server-info]::
189 Updates auxiliary information on a dumb server to help
190 clients discover references and packs on it.
192 link:git-upload-pack.html[git-upload-pack]::
193 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
194 what are asked for.
197 Porcelain-ish Commands
198 ----------------------
200 link:git-add-script.html[git-add-script]::
201 Add paths to the index file.
203 link:git-applymbox.html[git-applymbox]::
204 Apply patches from a mailbox.
206 link:git-bisect-script.html[git-bisect-script]::
207 Find the change that introduced a bug.
209 link:git-branch-script.html[git-branch-script]::
210 Create and Show branches.
212 link:git-cherry-pick-script.html[git-cherry-pick-script]::
213 Cherry-pick the effect of an existing commit.
215 link:git-clone-script.html[git-clone-script]::
216 Clones a repository into a new directory.
218 link:git-commit-script.html[git-commit-script]::
219 Record changes to the repository.
221 link:git-fetch-script.html[git-fetch-script]::
222 Download from a remote repository via various protocols.
224 link:git-log-script.html[git-log-script]::
225 Shows commit logs.
227 link:git-ls-remote-script.html[git-ls-remote-script]::
228 Shows references in a remote or local repository.
230 link:git-octopus-script.html[git-octopus-script]::
231 Merge more than two commits.
233 link:git-pull-script.html[git-pull-script]::
234 Fetch from and merge with a remote repository.
236 link:git-push-script.html[git-push-script]::
237 Update remote refs along with associated objects.
239 link:git-rebase-script.html[git-rebase-script]::
240 Rebase local commits to new upstream head.
242 link:git-rename-script.html[git-rename]::
243 Rename files and directories.
245 link:git-repack-script.html[git-repack-script]::
246 Pack unpacked objects in a repository.
248 link:git-resolve-script.html[git-resolve-script]::
249 Merge two commits.
251 link:git-revert-script.html[git-revert-script]::
252 Revert an existing commit.
254 link:git-shortlog.html[git-shortlog]::
255 Summarizes 'git log' output.
257 link:git-show-branch.html[git-show-branch]::
258 Show branches and their commits.
260 link:git-status-script.html[git-status-script]::
261 Shows the working tree status.
263 link:git-verify-tag-script.html[git-verify-tag-script]::
264 Check the GPG signature of tag.
266 link:git-whatchanged.html[git-whatchanged]::
267 Shows commit logs and differences they introduce.
270 Ancillary Commands
271 ------------------
272 Manipulators:
274 link:git-applypatch.html[git-applypatch]::
275 Apply one patch extracted from an e-mail.
277 link:git-convert-cache.html[git-convert-cache]::
278 Converts old-style GIT repository
280 link:git-cvsimport-script.html[git-cvsimport-script]::
281 Salvage your data out of another SCM people love to hate.
283 link:git-merge-one-file-script.html[git-merge-one-file-script]::
284 The standard helper program to use with "git-merge-cache"
286 link:git-prune-script.html[git-prune-script]::
287 Prunes all unreachable objects from the object database
289 link:git-relink-script.html[git-relink-script]::
290 Hardlink common objects in local repositories.
292 link:git-sh-setup-script.html[git-sh-setup-script]::
293 Common git shell script setup code.
295 link:git-tag-script.html[git-tag-script]::
296 An example script to create a tag object signed with GPG
299 Interrogators:
301 link:git-cherry.html[git-cherry]::
302 Find commits not merged upstream.
304 link:git-count-objects-script.html[git-count-objects-script]::
305 Count unpacked number of objects and their disk consumption.
307 link:git-diff-helper.html[git-diff-helper]::
308 Generates patch format output for git-diff-*
310 link:git-mailinfo.html[git-mailinfo]::
311 Extracts patch from a single e-mail message.
313 link:git-mailsplit.html[git-mailsplit]::
314 git-mailsplit.
316 link:git-patch-id.html[git-patch-id]::
317 Compute unique ID for a patch.
319 link:git-send-email-script.html[git-send-email]::
320 Send patch e-mails out of "format-patch --mbox" output.
323 Commands not yet documented
324 ---------------------------
326 link:git-build-rev-cache.html[git-build-rev-cache]::
327 git-build-rev-cache.
329 link:git-checkout-script.html[git-checkout-script]::
330 git-checkout-script.
332 link:git-clone-dumb-http.html[git-clone-dumb-http]::
333 git-clone-dumb-http.
335 link:git-daemon.html[git-daemon]::
336 git-daemon.
338 link:git-diff-script.html[git-diff-script]::
339 git-diff-script.
341 link:git-format-patch-script.html[git-format-patch-script]::
342 git-format-patch-script.
344 link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
345 git-get-tar-commit-id.
347 link:git-request-pull-script.html[git-request-pull-script]::
348 git-request-pull-script.
350 link:git-reset-script.html[git-reset-script]::
351 git-reset-script.
353 link:git-rev-parse.html[git-rev-parse]::
354 git-rev-parse.
356 link:git-show-rev-cache.html[git-show-rev-cache]::
357 git-show-rev-cache.
359 link:git-stripspace.html[git-stripspace]::
360 git-stripspace.
362 link:gitk.html[gitk]::
363 gitk.
366 Identifier Terminology
367 ----------------------
368 <object>::
369 Indicates the sha1 identifier for any type of object
371 <blob>::
372 Indicates a blob object sha1 identifier
374 <tree>::
375 Indicates a tree object sha1 identifier
377 <commit>::
378 Indicates a commit object sha1 identifier
380 <tree-ish>::
381 Indicates a tree, commit or tag object sha1 identifier. A
382 command that takes a <tree-ish> argument ultimately wants to
383 operate on a <tree> object but automatically dereferences
384 <commit> and <tag> objects that point at a <tree>.
386 <type>::
387 Indicates that an object type is required.
388 Currently one of: blob/tree/commit/tag
390 <file>::
391 Indicates a filename - always relative to the root of
392 the tree structure GIT_INDEX_FILE describes.
394 Symbolic Identifiers
395 --------------------
396 Any git command accepting any <object> can also use the following
397 symbolic notation:
399 HEAD::
400 indicates the head of the repository (ie the contents of
401 `$GIT_DIR/HEAD`)
402 <tag>::
403 a valid tag 'name'+
404 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
405 <head>::
406 a valid head 'name'+
407 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
408 <snap>::
409 a valid snapshot 'name'+
410 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
413 File/Directory Structure
414 ------------------------
415 The git-core manipulates the following areas in the directory:
417 .git/ The base (overridden with $GIT_DIR)
418 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
419 ??/ 'First 2 chars of object' directories.
420 pack/ Packed archives.
422 refs/ Directories containing symbolic names for objects
423 (each file contains the hex SHA1 + newline)
424 heads/ Commits which are heads of various sorts
425 tags/ Tags, by the tag name (or some local renaming of it)
426 */ Any other subdirectory of refs/ can be used to store
427 files similar to what are under refs/heads/.
428 HEAD Symlink to refs/heads/<current-branch-name>
430 Higher level SCMs may provide and manage additional information in the
431 GIT_DIR.
433 Terminology
434 -----------
435 Please see link:glossary.html[glossary] document.
438 Environment Variables
439 ---------------------
440 Various git commands use the following environment variables:
442 The git Repository
443 ~~~~~~~~~~~~~~~~~~
444 These environment variables apply to 'all' core git commands. Nb: it
445 is worth noting that they may be used/overridden by SCMS sitting above
446 git so take care if using Cogito etc
448 'GIT_INDEX_FILE'::
449 This environment allows the specification of an alternate
450 cache/index file. If not specified, the default of
451 `$GIT_DIR/index` is used.
453 'GIT_OBJECT_DIRECTORY'::
454 If the object storage directory is specified via this
455 environment variable then the sha1 directories are created
456 underneath - otherwise the default `$GIT_DIR/objects`
457 directory is used.
459 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
460 Due to the immutable nature of git objects, old objects can be
461 archived into shared, read-only directories. This variable
462 specifies a ":" separated list of git object directories which
463 can be used to search for git objects. New objects will not be
464 written to these directories.
466 'GIT_DIR'::
467 If the 'GIT_DIR' environment variable is set then it specifies
468 a path to use instead of `./.git` for the base of the
469 repository.
471 git Commits
472 ~~~~~~~~~~~
473 'GIT_AUTHOR_NAME'::
474 'GIT_AUTHOR_EMAIL'::
475 'GIT_AUTHOR_DATE'::
476 'GIT_COMMITTER_NAME'::
477 'GIT_COMMITTER_EMAIL'::
478 see link:git-commit-tree.html[git-commit-tree]
480 git Diffs
481 ~~~~~~~~~
482 'GIT_DIFF_OPTS'::
483 'GIT_EXTERNAL_DIFF'::
484 see the "generating patches" section in :
485 link:git-diff-cache.html[git-diff-cache];
486 link:git-diff-files.html[git-diff-files];
487 link:git-diff-tree.html[git-diff-tree]
489 Discussion[[Discussion]]
490 ------------------------
491 include::../README[]
493 Author
494 ------
495 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
497 Documentation
498 --------------
499 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
501 GIT
502 ---
503 Part of the link:git.html[git] suite