projects / git.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge with http://members.cox.net/junkio/git-jc.git
[git.git] / Documentation / git.txt
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 83d9ca6..a02ed6f 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -32,56 +32,30 @@ 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 and those that
 interrogate and compare them.
 
+There are also some ancilliary 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
 ~~~~~~~~~~~~~~~~~~~~~
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
-link:git-apply-patch-script.html[git-apply-patch-script]::
-       Sample script to apply the diffs from git-diff-*
-
 link:git-checkout-cache.html[git-checkout-cache]::
        Copy files from the cache to the working directory
 
 link:git-commit-tree.html[git-commit-tree]::
        Creates a new commit object
 
 link:git-checkout-cache.html[git-checkout-cache]::
        Copy files from the cache to the working directory
 
 link:git-commit-tree.html[git-commit-tree]::
        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
-
 link:git-init-db.html[git-init-db]::
        Creates an empty git object database
 
 link:git-init-db.html[git-init-db]::
        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-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"
-
 link:git-mktag.html[git-mktag]::
        Creates a tag object
 
 link:git-mktag.html[git-mktag]::
        Creates a tag object
 
-link:git-prune-script.html[git-prune-script]::
-       Prunes all unreachable objects from the object database
-
-link:git-pull-script.html[git-pull-script]::
-       Script used by Linus to pull and merge a remote repository
-
 link:git-read-tree.html[git-read-tree]::
        Reads tree information into the directory cache
 
 link:git-read-tree.html[git-read-tree]::
        Reads tree information into the directory cache
 
-link:git-resolve-script.html[git-resolve-script]::
-       Script used to merge two trees
-
-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]::
        Modifies the index or directory cache
 
 link:git-update-cache.html[git-update-cache]::
        Modifies the index or directory cache
 
@@ -108,9 +82,6 @@ link:git-diff-files.html[git-diff-files]::
 link:git-diff-tree.html[git-diff-tree]::
        Compares the content and mode of blobs found via two tree objects
 
 link:git-diff-tree.html[git-diff-tree]::
        Compares the content and mode of blobs found via two tree objects
 
-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
 
 link:git-export.html[git-export]::
        Exports each commit and a diff against each of its parents
 
@@ -132,9 +103,6 @@ link:git-rev-list.html[git-rev-list]::
 link:git-rev-tree.html[git-rev-tree]::
        Provides the revision tree for one or more commits
 
 link:git-rev-tree.html[git-rev-tree]::
        Provides the revision tree for one or more commits
 
-link:git-rpush.html[git-rpush]::
-       Helper "server-side" program used by git-rpull
-
 link:git-tar-tree.html[git-tar-tree]::
        Creates a tar archive of the files in the named tree
 
 link:git-tar-tree.html[git-tar-tree]::
        Creates a tar archive of the files in the named tree
 
@@ -145,6 +113,50 @@ The interrogate commands may create files - and you can force them to
 touch the working file set - but in general they don't
 
 
 touch the working file set - but in general they don't
 
 
+Ancilliary Commands
+-------------------
+Manipulators:
+
+link:git-apply-patch-script.html[git-apply-patch-script]::
+       Sample script to apply the diffs from git-diff-*
+
+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
+
+link:git-local-pull.html[git-local-pull]::
+       Duplicates another GIT repository on a local system
+
+link:git-merge-one-file-script.html[git-merge-one-file-script]::
+       The standard helper program to use with "git-merge-cache"
+
+link:git-pull-script.html[git-pull-script]::
+       Script used by Linus to pull and merge a remote repository
+
+link:git-prune-script.html[git-prune-script]::
+       Prunes all unreachable objects from the object database
+
+link:git-resolve-script.html[git-resolve-script]::
+       Script used to merge two trees
+
+link:git-tag-script.html[git-tag-script]::
+       An example script to create a tag object signed with GPG
+
+link:git-rpull.html[git-rpull]::
+       Pulls from a remote repository over ssh connection
+
+Interogators:
+
+link:git-diff-tree-helper.html[git-diff-tree-helper]::
+       Generates patch format output for git-diff-*
+
+link:git-rpush.html[git-rpush]::
+       Helper "server-side" program used by git-rpull
+
+
+
 Terminology
 -----------
 see README for description
 Terminology
 -----------
 see README for description
@@ -178,6 +190,44 @@ Identifier terminology
        Indicates a filename - always relative to the root of
        the tree structure GIT_INDEX_FILE describes.
 
        Indicates a filename - always relative to the root of
        the tree structure GIT_INDEX_FILE describes.
 
+Symbolic Identifiers
+--------------------
+Any git comand accepting any <object> can also use the following symbolic notation:
+
+HEAD::
+       indicates the head of the repository (ie the contents of `$GIT_DIR/HEAD`)
+<tag>::
+       a valid tag 'name'+
+       (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
+<head>::
+       a valid head 'name'+
+       (ie the contents of `$GIT_DIR/refs/heads/<head>`)
+<snap>::
+       a valid snapshot 'name'+
+       (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
+
+
+File/Directory Structure
+------------------------
+The git-core manipulates the following areas in the directory:
+
+ .git/        The base (overridden with $GIT_DIR)
+   objects/    The object base (overridden with $GIT_OBJECT_DIRECTORY)
+     ??/       'First 2 chars of object' directories
+
+It can interrogate (but never updates) the following areas:
+
+   refs/       Directories containing symbolic names for objects
+              (each file contains the hex SHA1 + newline)
+     heads/    Commits which are heads of various sorts
+     tags/     Tags, by the tag name (or some local renaming of it)
+     snap/     ????
+   ...         Everything else isn't shared
+   HEAD        Symlink to refs/heads/<something>
+
+Higher level SCMs may provide and manage additional information in the
+GIT_DIR.
+
 Terminology
 -----------
 Each line contains terms used interchangeably
 Terminology
 -----------
 Each line contains terms used interchangeably
@@ -198,17 +248,52 @@ Environment Variables
 ---------------------
 Various git commands use the following 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 ":" seperated 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 link:git-commit-tree.html[git-commit-tree]
+
+git Diffs
+~~~~~~~~~
+GIT_DIFF_OPTS::
+GIT_EXTERNAL_DIFF::
+       see the "generating patches" section in :
+       link:git-diff-cache.html[git-diff-cache];
+       link:git-diff-files.html[git-diff-files];
+       link:git-diff-tree.html[git-diff-tree]
 
 Author
 ------
 
 Author
 ------
The core git plumbing