From: Johannes Schindelin Date: Fri, 5 Aug 2005 15:05:02 +0000 (+0200) Subject: [PATCH] Assorted documentation patches X-Git-Tag: v0.99.4~22 X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=2c6e4771959dbe8116f39587d912f1215c06cd0d;p=git.git [PATCH] Assorted documentation patches [jc: Johannes spent time and effort to see how consistent our use of terminilogy is, and as a byproduct made these corrections not related to the terminology unification. I really appreciate it.] Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index d6ce0354..9298d79e 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -62,7 +62,7 @@ customization also applies to "git-diff-helper". 1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, these commands internally invoke "diff" like this: - diff -L a/ -L a/ -pu + diff -L a/ -L b/ -pu + For added files, `/dev/null` is used for . For removed files, `/dev/null` is used for @@ -101,7 +101,7 @@ For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 parameter, . -Git specific extention to diff format +Git specific extension to diff format ------------------------------------- What -p option produces is slightly different from the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 58b9c46c..b28496e5 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -5,9 +5,9 @@ Synonym for "-p". -r:: - Look recursivelly in subdirectories; this flag does not + Look recursively in subdirectories; this flag does not mean anything to commands other than "git-diff-tree"; - other commands always looks at all the subdirectories. + other diff commands always look at all the subdirectories. -z:: \0 line termination on output diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt index b4635934..a353d126 100644 --- a/Documentation/git-diff-cache.txt +++ b/Documentation/git-diff-cache.txt @@ -50,13 +50,13 @@ Cached Mode ----------- If '--cached' is specified, it allows you to ask: - show me the differences between HEAD and the current index + show me the differences between HEAD and the current cache contents (the ones I'd write with a "git-write-tree") -For example, let's say that you have worked on your index file, and are -ready to commit. You want to see eactly *what* you are going to commit is -without having to write a new tree object and compare it that way, and to -do that, you just do +For example, let's say that you have worked on your working directory, updated +some files in the cache and are ready to commit. You want to see eactly +*what* you are going to commit is without having to write a new tree +object and compare it that way, and to do that, you just do git-diff-cache --cached $(cat .git/HEAD) diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index b2095cb0..5ccf0ba1 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -86,7 +86,7 @@ Or if you are searching for what changed in just `kernel/sched.c`, just do and it will ignore all differences to other files. The pattern is always the prefix, and is matched exactly. There are no -wildcards. Even stricter, it has to match complete path comonent. +wildcards. Even stricter, it has to match a complete path component. I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` so it can be used to name subdirectories. diff --git a/Documentation/git-fsck-cache.txt b/Documentation/git-fsck-cache.txt index aaec2de0..13f19653 100644 --- a/Documentation/git-fsck-cache.txt +++ b/Documentation/git-fsck-cache.txt @@ -39,17 +39,17 @@ OPTIONS --standalone:: Limit checks to the contents of GIT_OBJECT_DIRECTORY - (.git/objects), making sure that it is consistent and + ($GIT_DIR/objects), making sure that it is consistent and complete without referring to objects found in alternate object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, - nor packed GIT archives found in .git/objects/pack; + nor packed GIT archives found in $GIT_DIR/objects/pack; cannot be used with --full. --full:: Check not just objects in GIT_OBJECT_DIRECTORY - (.git/objects), but also the ones found in alternate + ($GIT_DIR/objects), but also the ones found in alternate object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES, - and in packed GIT archives found in .git/objects/pack + and in packed GIT archives found in $GIT_DIR/objects/pack and corresponding pack subdirectories in alternate object pools; cannot be used with --standalone. @@ -69,11 +69,7 @@ that aren't readable from any of the specified head nodes. So for example - git-fsck-cache --unreachable $(cat .git/HEAD) - -or, for Cogito users: - - git-fsck-cache --unreachable $(cat .git/refs/heads/*) + git-fsck-cache --unreachable $(cat .git/HEAD .git/refs/heads/*) will do quite a _lot_ of verification on the tree. There are a few extra validity tests to be added (make sure that tree objects are @@ -122,18 +118,18 @@ sha1 mismatch :: The database has an object who's sha1 doesn't match the database value. This indicates a serious data integrity problem. - (note: this error occured during early git development when - the database format changed.) Environment Variables --------------------- GIT_OBJECT_DIRECTORY:: - used to specify the object database root (usually .git/objects) + used to specify the object database root (usually $GIT_DIR/objects) GIT_INDEX_FILE:: - used to specify the cache + used to specify the index file of the cache +GIT_ALTERNATE_OBJECT_DIRECTORIES: + used to specify additional object database roots (usually unset) Author ------ diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 8790d19b..a77adab1 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -21,6 +21,14 @@ This is used by "git-cvsimport-script" to update the cache without modifying files in the work tree. When is not specified, it defaults to "blob". +OPTIONS +------- + +-t :: + Specify the type (default: "blob"). + +-w:: + Actually write the object into the object database. Author ------ diff --git a/Documentation/git-http-pull.txt b/Documentation/git-http-pull.txt index 431ef7ca..edc5cebf 100644 --- a/Documentation/git-http-pull.txt +++ b/Documentation/git-http-pull.txt @@ -23,8 +23,9 @@ Downloads a remote GIT repository via HTTP. Get all the objects. -v:: Report what is downloaded. --w:: - Writes the commit-id into the filename under $GIT_DIR/refs/ on + +-w :: + Writes the commit-id into the filename under $GIT_DIR/refs/ on the local end after the transfer is complete. Author diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 99f96f7d..fb8b5225 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -4,7 +4,7 @@ v0.1, May 2005 NAME ---- -git-init-db - Creates an empty git object database +git-init-db - Creates an empty git repository SYNOPSIS @@ -13,15 +13,16 @@ SYNOPSIS DESCRIPTION ----------- -This simply creates an empty git object database - basically a `.git` -directory and `.git/object/??/` directories. +This simply creates an empty git repository - basically a `.git` directory +and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories, +and links `.git/HEAD` symbolically to `.git/refs/heads/master`. 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. +otherwise the default `$GIT_DIR/objects` directory is used. "git-init-db" won't hurt an existing repository. diff --git a/Documentation/git-local-pull.txt b/Documentation/git-local-pull.txt index cb953340..4651e815 100644 --- a/Documentation/git-local-pull.txt +++ b/Documentation/git-local-pull.txt @@ -25,8 +25,9 @@ OPTIONS Get all the objects. -v:: Report what is downloaded. --w:: - Writes the commit-id into the filename under $GIT_DIR/refs/ on + +-w :: + Writes the commit-id into the filename under $GIT_DIR/refs/ on the local end after the transfer is complete. Author diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index d2072194..d05827f6 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -87,7 +87,7 @@ detailed information on unmerged paths. For an unmerged path, instead of recording a single mode/SHA1 pair, the dircache records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3. This information can be used by -the user (or Cogito) to see what should eventually be recorded at the +the user (or the porcelain) to see what should eventually be recorded at the path. (see read-cache for more information on state) @@ -130,7 +130,7 @@ time. They are built and ordered in the following way: are popped off when leaving the directory. Each pattern in the pattern list specifies "a match pattern" and -optionally the fate;n either a file that matches the pattern is +optionally the fate; either a file that matches the pattern is considered excluded or included. A filename is matched against the patterns in the three lists; the --exclude-from list is checked first, then the --exclude-per-directory list, and then diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 958b56d8..fdb215ec 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -19,7 +19,7 @@ in the current working directory. OPTIONS ------- :: - Id of a tree. + Id of a tree-ish. -d:: show only the named tree entry itself, not its children @@ -31,7 +31,7 @@ OPTIONS \0 line termination on output paths:: - When paths are given, shows them. Otherwise implicitly + When paths are given, show them. Otherwise implicitly uses the root level of the tree as the sole path argument. diff --git a/Documentation/git-merge-cache.txt b/Documentation/git-merge-cache.txt index f1fbb5dd..bd3c9ca7 100644 --- a/Documentation/git-merge-cache.txt +++ b/Documentation/git-merge-cache.txt @@ -21,7 +21,7 @@ files are passed as arguments 5, 6 and 7. OPTIONS ------- --:: - Interpret all future arguments as filenames. + Interpret all following arguments as filenames. -a:: Run merge against all files in the cache that need merging. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index ae6e88d4..96281831 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -29,7 +29,7 @@ one-object" format; this is typically done by the smart-pull commands when a pack is created on-the-fly for efficient network transport by their peers. -Placing both in pack subdirectory of $GIT_OBJECT_DIRECTORY (or +Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) enables GIT to read from such an archive. diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index ab783c10..90075403 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -4,7 +4,7 @@ v0.1, July 2005 NAME ---- -git-peek-remote - Lists the references on a remote repository. +git-peek-remote - Lists the references in a remote repository. SYNOPSIS @@ -20,14 +20,14 @@ OPTIONS ------- --exec=:: Use this to specify the path to 'git-upload-pack' on the - remote side, if is not found on your $PATH. - Installations of sshd ignores the user's environment + remote side, if it is not found on your $PATH. Some + installations of sshd ignores the user's environment setup scripts for login shells (e.g. .bash_profile) and your privately installed GIT may not be found on the system default $PATH. Another workaround suggested is to set up your $PATH in ".bashrc", but this flag is for people who do not want to pay the overhead for non-interactive - shells by having a lean .bashrc file (they set most of + shells, but prefer having a lean .bashrc file (they set most of the things up in .bash_profile). :: diff --git a/Documentation/git-prune-script.txt b/Documentation/git-prune-script.txt index 537b7905..e8305a6f 100644 --- a/Documentation/git-prune-script.txt +++ b/Documentation/git-prune-script.txt @@ -14,8 +14,9 @@ SYNOPSIS DESCRIPTION ----------- This runs "git-fsck-cache --unreachable" program using the heads specified -on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is -specified), and prunes all unreachable objects from the object database. +on the command line (or `$GIT_DIR/refs/heads/\*` and `$GIT_DIR/refs/tags/\*` +if none is specified), and prunes all unreachable objects from the object +database. Author diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 7665946f..e1be6cc0 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -41,7 +41,7 @@ OPTIONS Merging ------- -If '-m' is specified, "git-read-tree" can performs 3 kinds of +If '-m' is specified, "git-read-tree" can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a fast-forward merge with 2 trees, or a 3-way merge if 3 trees are provided. @@ -51,9 +51,9 @@ Single Tree Merge ~~~~~~~~~~~~~~~~~ If only 1 tree is specified, git-read-tree operates as if the user did not specify '-m', except that if the original cache has an entry for a -given pathname; and the contents of the path matches with the tree +given pathname, and the contents of the path matches with the tree being read, the stat info from the cache is used. (In other words, the -cache's stat()s take precedence over the merged tree's) +cache's stat()s take precedence over the merged tree's). That means that if you do a "git-read-tree -m " followed by a "git-checkout-cache -f -u -a", the "git-checkout-cache" only checks out @@ -184,7 +184,7 @@ populated. Here is an outline of how the algorithm works: automatically collapse to "merged" state by git-read-tree. - a file that has _any_ difference what-so-ever in the three trees - will stay as separate entries in the index. It's up to "script + will stay as separate entries in the index. It's up to "porcelain policy" to determine how to remove the non-0 stages, and insert a merged version. diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index dc8d0fa9..9323dddf 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- Creates a tar archive containing the tree structure for the named tree. -When is specified it is added as a leading path as the files in the +When is specified it is added as a leading path to the files in the generated tar archive. git-tar-tree behaves differently when given a tree ID versus when given diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 4f65acbc..830f3980 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -16,7 +16,7 @@ DESCRIPTION A dumb server that does not do on-the-fly pack generations can have some auxiliary information files in $GIT_DIR/info and $GIT_OBJECT_DIRECTORY/info directories to help clients discover -what references and packs the server has and make an optimized +what references and packs the server has and make optimized pull decisions. This command generates such auxiliary files. diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index 3b6a66fe..3cf8c934 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -4,7 +4,7 @@ v0.1, May 2005 NAME ---- -git-write-tree - Creates a tree from the current cache +git-write-tree - Creates a tree object from the current cache SYNOPSIS