[PATCH 3/4] split core-git.txt and update

Update git environment variable docs
Update first section of command docs (Manipulation commands section)

Signed-off-by: David Greaves <david@dgreaves.com>

diff --git a/Documentation/git-check-files.txt b/Documentation/git-check-files.txt
index c56f22f92da826c592c49fa51eecdfaf7696a37f..61460980226633bf9bcf70e2a1a1d8c8af0749eb 100644 (file)
--- a/Documentation/git-check-files.txt
+++ b/Documentation/git-check-files.txt
@@ -31,7 +31,9 @@ preparing to update file <file> not uptodate in cache::
 Exits with a status code indicating success if all files are
 up-to-date.
 
 Exits with a status code indicating success if all files are
 up-to-date.
 

-see also: link:git-update-cache.html[git-update-cache]
+See Also
+--------
+link:git-update-cache.html[git-update-cache]

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 5552050ac1dded1e20660264763c20f237c42233..c0dc1f46c5b398cf7a1719462157b5ffeee14345 100644 (file)
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -64,7 +64,14 @@ A commit comment is read from stdin (max 999 chars). If a changelog
 entry is not provided via '<' redirection, "git-commit-tree" will just wait
 for one to be entered and terminated with ^D
 
 entry is not provided via '<' redirection, "git-commit-tree" will just wait
 for one to be entered and terminated with ^D
 

-see also: link:git-write-tree.html[git-write-tree]
+Diagnostics
+-----------
+You don't exist. Go away!::
+    The passwd(5) gecos field couldn't be read
+
+See Also
+--------
+link:git-write-tree.html[git-write-tree]

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-diff-tree-helper.txt b/Documentation/git-diff-tree-helper.txt
index d44858df51dc1573fdbef042a7c7cc8aa9b5f01d..58f27172a9e23bf43f3bae6eb184e72425715b84 100644 (file)
--- a/Documentation/git-diff-tree-helper.txt
+++ b/Documentation/git-diff-tree-helper.txt
@@ -30,7 +30,9 @@ OPTIONS
 +
 would show a diff to bring the working file back to what is in the <tree>.
 
 +
 would show a diff to bring the working file back to what is in the <tree>.
 

-See also the section on generating patches in link:git-diff-cache.html[git-diff-cache]
+See Also
+--------
+The section on generating patches in link:git-diff-cache.html[git-diff-cache]

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt
index febc8c811dd27e5e45789dab4ff67d373f00f6d3..99f96f7d4f67f07ed7ce6bcdcccdba795a80a93d 100644 (file)
--- a/Documentation/git-init-db.txt
+++ b/Documentation/git-init-db.txt
@@ -16,6 +16,9 @@ DESCRIPTION
 This simply creates an empty git object database - basically a `.git`
 directory and `.git/object/??/` directories.
 
 This simply creates an empty git object database - basically a `.git`
 directory and `.git/object/??/` directories.
 

+If the 'GIT_DIR' environment variable is set then it specifies a path
+to use instead of `./.git` for the base of the repository.
+

 If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY'
 environment variable then the sha1 directories are created underneath -
 otherwise the default `.git/objects` directory is used.
 If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY'
 environment variable then the sha1 directories are created underneath -
 otherwise the default `.git/objects` directory is used.

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 2face87ae5ff5e7822682e0cfb64011ea296352d..14ca6953176cf5577a0323db6cd23a43805522a5 100644 (file)
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -83,7 +83,9 @@ the dircache records up to three such pairs; one from tree O in stage
 the user (or Cogito) to see what should eventually be recorded at the
 path. (see read-cache for more information on state)
 
 the user (or Cogito) to see what should eventually be recorded at the
 path. (see read-cache for more information on state)
 

-see also: link:read-cache.html[read-cache]
+See Also
+--------
+link:read-cache.html[read-cache]

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index 320f5a1efb3ecd8443e01da714bdb6470d85838c..708f4ef8dad1b41628a1afcc1bc75a1bae89fa4e 100644 (file)
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -9,12 +9,29 @@ git-mktag - Creates a tag object
 
 SYNOPSIS
 --------
 
 SYNOPSIS
 --------

-'git-mktag'
+'git-mktag' < signature_file

 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------

-Reads a tag contents from its standard input and creates a tag object.
-The input must be a well formed tag object.
+Reads a tag contents on standard input and creates a tag object
+that can also be used to sign other objects.
+
+The output is the new tag's <object> identifier.
+
+Tag Format
+----------
+A tag signature file has a very simple fixed format: three lines of
+
+  object <sha1>
+  type <typename>
+  tag <tagname>
+
+followed by some 'optional' free-form signature that git itself
+doesn't care about, but that can be verified with gpg or similar.
+
+The size of the full object is artificially limited to 8kB.  (Just
+because I'm a lazy bastard, and if you can't fit a signature in that
+size, you're doing something wrong)

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index df2e36775c822ff7812e2a7f53ada54a462bc78e..cbde13dba998d3c7239a258b134e2ba54641e590 100644 (file)
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Reads the tree information given by <tree> into the directory cache,
 DESCRIPTION
 -----------
 Reads the tree information given by <tree> into the directory cache,

-but does not actually _update_ any of the files it "caches". (see:
+but does not actually *update* any of the files it "caches". (see:

 git-checkout-cache)
 
 Optionally, it can merge a tree into the cache or perform a 3-way
 git-checkout-cache)
 
 Optionally, it can merge a tree into the cache or perform a 3-way


@@ -133,7 +133,9 @@ the index file, which is a temporary thing anyway. There is no need to
 worry about what is in the working directory, since it is never shown
 and never used.
 
 worry about what is in the working directory, since it is never shown
 and never used.
 

-see also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]
+See Also
+--------
+link:git-write-tree.html[git-write-tree]; link:git-ls-files.html[git-ls-files]

 
 
 Author
 
 
 Author

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 66b68b89d58a6110489d354c04dd900d9be5fc1e..a02ed6f42696bd274a631ab33640a35bbc3e350f 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -190,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


@@ -210,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
 ------