X-Git-Url: https://git.verplant.org/?a=blobdiff_plain;f=Documentation%2Fgit.txt;h=e14102127958d98b1bf37a8d7560320249495ad7;hb=ab1630a3ed31d6ec5ae83769c78ed542fe3c4a28;hp=83d9ca6d9a38dfc4d8dc9fa27c629b11830cb249;hpb=2cf565c53c88c557eedd7e5629437b3c6fe74329;p=git.git diff --git a/Documentation/git.txt b/Documentation/git.txt index 83d9ca6d..e1410212 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1,6 +1,6 @@ -git(1) +git(7) ====== -v0.1, May 2005 +v0.99.6, Sep 2005 NAME ---- @@ -16,9 +16,21 @@ DESCRIPTION This is reference information for the core git commands. -The link:README[] contains much useful definition and clarification -info - read that first. And of the commands, I suggest reading -'git-update-cache' and 'git-read-tree' first - I wish I had! +Before reading this cover to cover, you may want to take a look +at the link:tutorial.html[tutorial] document. + +The <> section below contains much useful definition and +clarification info - read that first. And of the commands, I suggest +reading gitlink:git-update-index[1] and +gitlink:git-read-tree[1] first - I wish I had! + +If you are migrating from CVS, link:cvs-migration.html[cvs migration] +document may be helpful after you finish the tutorial. + +After you get the general feel from the tutorial and this +overview page, you may want to take a look at the +link:howto-index.html[howto] documents. + David Greaves 08/05/05 @@ -29,130 +41,370 @@ reflect recent changes. Commands Overview ----------------- The git commands can helpfully be split into those that manipulate -the repository, the cache and the working fileset and those that -interrogate and compare them. +the repository, the cache and the working fileset, those that +interrogate and compare them, and those that moves objects and +references between repositories. + +In addition, git itself comes with a spartan set of porcelain +commands. They are usable but are not meant to compete with real +Porcelains. + +There are also some ancillary programs that can be viewed as useful +aids for using the core commands but which are unlikely to be used by +SCMs layered over git. Manipulation commands ~~~~~~~~~~~~~~~~~~~~~ -link:git-apply-patch-script.html[git-apply-patch-script]:: - Sample script to apply the diffs from git-diff-* +gitlink:git-apply[1]:: + Reads a "diff -up1" or git generated patch file and + applies it to the working tree. -link:git-checkout-cache.html[git-checkout-cache]:: +gitlink:git-checkout-index[1]:: Copy files from the cache to the working directory + Previously this command was known as git-checkout-cache. -link:git-commit-tree.html[git-commit-tree]:: +gitlink:git-commit-tree[1]:: Creates a new commit object -link:git-convert-cache.html[git-convert-cache]:: - Converts old-style GIT repository - -link:git-http-pull.html[git-http-pull]:: - Downloads a remote GIT repository via HTTP +gitlink:git-hash-object[1]:: + Computes the object ID from a file. -link:git-init-db.html[git-init-db]:: +gitlink:git-init-db[1]:: Creates an empty git object database -link:git-local-pull.html[git-local-pull]:: - Duplicates another GIT repository on a local system - -link:git-merge-base.html[git-merge-base]:: - Finds as good a common ancestor as possible for a merge - -link:git-merge-one-file-script.html[git-merge-one-file-script]:: - The standard helper program to use with "git-merge-cache" +gitlink:git-merge-index[1]:: + Runs a merge for files needing merging + Previously this command was known as git-merge-cache. -link:git-mktag.html[git-mktag]:: +gitlink:git-mktag[1]:: Creates a tag object -link:git-prune-script.html[git-prune-script]:: - Prunes all unreachable objects from the object database +gitlink:git-pack-objects[1]:: + Creates a packed archive of objects. -link:git-pull-script.html[git-pull-script]:: - Script used by Linus to pull and merge a remote repository +gitlink:git-prune-packed[1]:: + Remove extra objects that are already in pack files. -link:git-read-tree.html[git-read-tree]:: +gitlink:git-read-tree[1]:: Reads tree information into the directory cache -link:git-resolve-script.html[git-resolve-script]:: - Script used to merge two trees +gitlink:git-unpack-objects[1]:: + Unpacks objects out of a packed archive. -link:git-rpull.html[git-rpull]:: - Pulls from a remote repository over ssh connection - -link:git-tag-script.html[git-tag-script]:: - An example script to create a tag object signed with GPG - -link:git-update-cache.html[git-update-cache]:: +gitlink:git-update-index[1]:: Modifies the index or directory cache + Previously this command was known as git-update-cache. -link:git-write-blob.html[git-write-blob]:: - Creates a blob from a file - -link:git-write-tree.html[git-write-tree]:: +gitlink:git-write-tree[1]:: Creates a tree from the current cache + Interrogation commands ~~~~~~~~~~~~~~~~~~~~~~ -link:git-cat-file.html[git-cat-file]:: - Provide content or type information for repository objects -link:git-check-files.html[git-check-files]:: - Verify a list of files are up-to-date +gitlink:git-cat-file[1]:: + Provide content or type information for repository objects -link:git-diff-cache.html[git-diff-cache]:: +gitlink:git-diff-index[1]:: Compares content and mode of blobs between the cache and repository + Previously this command was known as git-diff-cache. -link:git-diff-files.html[git-diff-files]:: +gitlink:git-diff-files[1]:: Compares files in the working tree and the cache -link:git-diff-tree.html[git-diff-tree]:: - Compares the content and mode of blobs found via two tree objects +gitlink:git-diff-stages[1]:: + Compares two "merge stages" in the index file. -link:git-diff-tree-helper.html[git-diff-tree-helper]:: - Generates patch format output for git-diff-* - -link:git-export.html[git-export]:: - Exports each commit and a diff against each of its parents +gitlink:git-diff-tree[1]:: + Compares the content and mode of blobs found via two tree objects -link:git-fsck-cache.html[git-fsck-cache]:: +gitlink:git-fsck-objects[1]:: Verifies the connectivity and validity of the objects in the database + Previously this command was known as git-fsck-cache. -link:git-ls-files.html[git-ls-files]:: +gitlink:git-ls-files[1]:: Information about files in the cache/working directory -link:git-ls-tree.html[git-ls-tree]:: +gitlink:git-ls-tree[1]:: Displays a tree object in human readable form -link:git-merge-cache.html[git-merge-cache]:: - Runs a merge for files needing merging +gitlink:git-merge-base[1]:: + Finds as good a common ancestor as possible for a merge -link:git-rev-list.html[git-rev-list]:: +gitlink:git-rev-list[1]:: Lists commit objects in reverse chronological order -link:git-rev-tree.html[git-rev-tree]:: - Provides the revision tree for one or more commits +gitlink:git-show-index[1]:: + Displays contents of a pack idx file. -link:git-rpush.html[git-rpush]:: - Helper "server-side" program used by git-rpull - -link:git-tar-tree.html[git-tar-tree]:: +gitlink:git-tar-tree[1]:: Creates a tar archive of the files in the named tree -link:git-unpack-file.html[git-unpack-file]:: +gitlink:git-unpack-file[1]:: Creates a temporary file with a blob's contents +gitlink:git-var[1]:: + Displays a git logical variable + +gitlink:git-verify-pack[1]:: + Validates packed GIT archive files + The interrogate commands may create files - and you can force them to touch the working file set - but in general they don't -Terminology ------------ -see README for description +Synching repositories +~~~~~~~~~~~~~~~~~~~~~ + +gitlink:git-clone-pack[1]:: + Clones a repository into the current repository (engine + for ssh and local transport) + +gitlink:git-fetch-pack[1]:: + Updates from a remote repository. + +gitlink:git-http-fetch[1]:: + Downloads a remote GIT repository via HTTP + Previously this command was known as git-http-pull. + +gitlink:git-local-fetch[1]:: + Duplicates another GIT repository on a local system + Previously this command was known as git-local-pull. + +gitlink:git-peek-remote[1]:: + Lists references on a remote repository using upload-pack protocol. + +gitlink:git-receive-pack[1]:: + Invoked by 'git-send-pack' to receive what is pushed to it. + +gitlink:git-send-pack[1]:: + Pushes to a remote repository, intelligently. + +gitlink:git-ssh-fetch[1]:: + Pulls from a remote repository over ssh connection + Previously this command was known as git-ssh-pull. + +gitlink:git-ssh-upload[1]:: + Helper "server-side" program used by git-ssh-fetch + Previously this command was known as git-ssh-push. -Identifier terminology +gitlink:git-update-server-info[1]:: + Updates auxiliary information on a dumb server to help + clients discover references and packs on it. + +gitlink:git-upload-pack[1]:: + Invoked by 'git-clone-pack' and 'git-fetch-pack' to push + what are asked for. + + +Porcelain-ish Commands +---------------------- + +gitlink:git-add[1]:: + Add paths to the index file. + Previously this command was known as git-add-script. + +gitlink:git-applymbox[1]:: + Apply patches from a mailbox. + +gitlink:git-bisect[1]:: + Find the change that introduced a bug. + Previously this command was known as git-bisect-script. + +gitlink:git-branch[1]:: + Create and Show branches. + Previously this command was known as git-branch-script. + +gitlink:git-checkout[1]:: + Checkout and switch to a branch. + Previously this command was known as git-checkout-script. + +gitlink:git-cherry-pick[1]:: + Cherry-pick the effect of an existing commit. + Previously this command was known as git-cherry-pick-script. + +gitlink:git-clone[1]:: + Clones a repository into a new directory. + Previously this command was known as git-clone-script. + +gitlink:git-commit[1]:: + Record changes to the repository. + Previously this command was known as git-commit-script. + +gitlink:git-diff[1]:: + Show changes between commits, commit and working tree, etc. + Previously this command was known as git-diff-script. + +gitlink:git-fetch[1]:: + Download from a remote repository via various protocols. + Previously this command was known as git-fetch-script. + +gitlink:git-format-patch[1]:: + Prepare patches for e-mail submission. + Previously this command was known as git-format-patch-script. + +gitlink:git-grep[1]:: + Print lines matching a pattern + +gitlink:git-log[1]:: + Shows commit logs. + Previously this command was known as git-log-script. + +gitlink:git-ls-remote[1]:: + Shows references in a remote or local repository. + Previously this command was known as git-ls-remote-script. + +gitlink:git-merge[1]:: + Grand unified merge driver. + +gitlink:git-octopus[1]:: + Merge more than two commits. + Previously this command was known as git-octopus-script. + +gitlink:git-pull[1]:: + Fetch from and merge with a remote repository. + Previously this command was known as git-pull-script. + +gitlink:git-push[1]:: + Update remote refs along with associated objects. + Previously this command was known as git-push-script. + +gitlink:git-rebase[1]:: + Rebase local commits to new upstream head. + Previously this command was known as git-rebase-script. + +gitlink:git-rename[1]:: + Rename files and directories. + Previously this command was known as git-rename-script. + +gitlink:git-repack[1]:: + Pack unpacked objects in a repository. + Previously this command was known as git-repack-script. + +gitlink:git-reset[1]:: + Reset current HEAD to the specified state. + Previously this command was known as git-reset-script. + +gitlink:git-resolve[1]:: + Merge two commits. + Previously this command was known as git-resolve-script. + +gitlink:git-revert[1]:: + Revert an existing commit. + Previously this command was known as git-revert-script. + +gitlink:git-shortlog[1]:: + Summarizes 'git log' output. + +gitlink:git-show-branch[1]:: + Show branches and their commits. + +gitlink:git-status[1]:: + Shows the working tree status. + Previously this command was known as git-status-script. + +gitlink:git-verify-tag[1]:: + Check the GPG signature of tag. + Previously this command was known as git-verify-tag-script. + +gitlink:git-whatchanged[1]:: + Shows commit logs and differences they introduce. + + +Ancillary Commands +------------------ +Manipulators: + +gitlink:git-applypatch[1]:: + Apply one patch extracted from an e-mail. + +gitlink:git-archimport[1]:: + Import an arch repository into git. + Previously this command was known as git-archimport-script. + +gitlink:git-convert-objects[1]:: + Converts old-style GIT repository + Previously this command was known as git-convert-cache. + +gitlink:git-cvsimport[1]:: + Salvage your data out of another SCM people love to hate. + Previously this command was known as git-cvsimport-script. + +gitlink:git-merge-one-file[1]:: + The standard helper program to use with "git-merge-index" + Previously this command was known as git-merge-one-file-script. + +gitlink:git-prune[1]:: + Prunes all unreachable objects from the object database + Previously this command was known as git-prune-script. + +gitlink:git-relink[1]:: + Hardlink common objects in local repositories. + Previously this command was known as git-relink-script. + +gitlink:git-sh-setup[1]:: + Common git shell script setup code. + Previously this command was known as git-sh-setup-script. + +gitlink:git-tag[1]:: + An example script to create a tag object signed with GPG + Previously this command was known as git-tag-script. + + +Interrogators: + +gitlink:git-cherry[1]:: + Find commits not merged upstream. + +gitlink:git-count-objects[1]:: + Count unpacked number of objects and their disk consumption. + Previously this command was known as git-count-objects-script. + +gitlink:git-daemon[1]:: + A really simple server for GIT repositories. + +gitlink:git-get-tar-commit-id[1]:: + Extract commit ID from an archive created using git-tar-tree. + +gitlink:git-mailinfo[1]:: + Extracts patch from a single e-mail message. + +gitlink:git-mailsplit[1]:: + git-mailsplit. + +gitlink:git-patch-id[1]:: + Compute unique ID for a patch. + +gitlink:git-parse-remote[1]:: + Routines to help parsing $GIT_DIR/remotes/ + Previously this command was known as git-parse-remote-script. + +gitlink:git-request-pull[1]:: + git-request-pull. + Previously this command was known as git-request-pull-script. + +gitlink:git-rev-parse[1]:: + Pick out and massage parameters. + +gitlink:git-send-email[1]:: + Send patch e-mails out of "format-patch --mbox" output. + Previously this command was known as git-send-email-script. + +gitlink:git-stripspace[1]:: + Filter out empty lines. + + +Commands not yet documented +--------------------------- + +gitlink:gitk[1]:: + gitk. + + +Identifier Terminology ---------------------- :: - Indicates any object sha1 identifier + Indicates the sha1 identifier for any type of object :: Indicates a blob object sha1 identifier @@ -164,11 +416,10 @@ Identifier terminology Indicates a commit object sha1 identifier :: - Indicates a tree, commit or tag object sha1 identifier. - A command that takes a argument ultimately - wants to operate on a object but automatically - dereferences and that points at a - . + Indicates a tree, commit or tag object sha1 identifier. A + command that takes a argument ultimately wants to + operate on a object but automatically dereferences + and objects that point at a . :: Indicates that an object type is required. @@ -178,41 +429,97 @@ Identifier terminology Indicates a filename - always relative to the root of the tree structure GIT_INDEX_FILE describes. +Symbolic Identifiers +-------------------- +Any git command accepting any can also use the following +symbolic notation: + +HEAD:: + indicates the head of the repository (ie the contents of + `$GIT_DIR/HEAD`) +:: + a valid tag 'name'+ + (ie the contents of `$GIT_DIR/refs/tags/`) +:: + a valid head 'name'+ + (ie the contents of `$GIT_DIR/refs/heads/`) +:: + a valid snapshot 'name'+ + (ie the contents of `$GIT_DIR/refs/snap/`) + + +File/Directory Structure +------------------------ + +Please see link:repository-layout.html[repository layout] document. + +Higher level SCMs may provide and manage additional information in the +GIT_DIR. + + Terminology ----------- -Each line contains terms used interchangeably - - object database, .git directory - directory cache, index - id, sha1, sha1-id, sha1 hash - type, tag - blob, blob object - tree, tree object - commit, commit object - parent - root object - changeset +Please see link:glossary.html[glossary] document. Environment Variables --------------------- Various git commands use the following environment variables: -- 'GIT_AUTHOR_NAME' -- 'GIT_AUTHOR_EMAIL' -- 'GIT_AUTHOR_DATE' -- 'GIT_COMMITTER_NAME' -- 'GIT_COMMITTER_EMAIL' -- 'GIT_DIFF_OPTS' -- 'GIT_EXTERNAL_DIFF' -- 'GIT_INDEX_FILE' -- 'GIT_OBJECT_DIRECTORY' -- 'GIT_ALTERNATE_OBJECT_DIRECTORIES' - +The git Repository +~~~~~~~~~~~~~~~~~~ +These environment variables apply to 'all' core git commands. Nb: it +is worth noting that they may be used/overridden by SCMS sitting above +git so take care if using Cogito etc + +'GIT_INDEX_FILE':: + This environment allows the specification of an alternate + cache/index file. If not specified, the default of + `$GIT_DIR/index` is used. + +'GIT_OBJECT_DIRECTORY':: + If the object storage directory is specified via this + environment variable then the sha1 directories are created + underneath - otherwise the default `$GIT_DIR/objects` + directory is used. + +'GIT_ALTERNATE_OBJECT_DIRECTORIES':: + Due to the immutable nature of git objects, old objects can be + archived into shared, read-only directories. This variable + specifies a ":" separated list of git object directories which + can be used to search for git objects. New objects will not be + written to these directories. + +'GIT_DIR':: + If the 'GIT_DIR' environment variable is set then it specifies + a path to use instead of `./.git` for the base of the + repository. + +git Commits +~~~~~~~~~~~ +'GIT_AUTHOR_NAME':: +'GIT_AUTHOR_EMAIL':: +'GIT_AUTHOR_DATE':: +'GIT_COMMITTER_NAME':: +'GIT_COMMITTER_EMAIL':: + see gitlink:git-commit-tree[1] + +git Diffs +~~~~~~~~~ +'GIT_DIFF_OPTS':: +'GIT_EXTERNAL_DIFF':: + see the "generating patches" section in : + gitlink:git-diff-index[1]; + gitlink:git-diff-files[1]; + gitlink:git-diff-tree[1] + +Discussion[[Discussion]] +------------------------ +include::../README[] Author ------ -Written by Linus Torvalds +Written by Linus Torvalds and the git-list . Documentation -------------- @@ -220,5 +527,5 @@ Documentation by David Greaves, Junio C Hamano and the git-list