Skip to contentSkip to conversation

Added documentation for few missing options.

PATCH In review Jon Loeliger 2 participants 2 messages Jun 15, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Added documentation for few missing options.

More $ shell prompts in examples. Minor English grammar improvements. Added a few "See Also"s.
Use back-ticks on more command examples.

---

 Documentation/git-checkout-index.txt |   78 +++++++++++++++++++++-------------
 Documentation/git-init-db.txt        |   27 ++++++++++--
 Documentation/git-prune-packed.txt   |   11 +++--
 Documentation/git-read-tree.txt      |   74 ++++++++++++++++++--------------
 Documentation/git-update-index.txt   |   20 +++++++--
 Documentation/git-write-tree.txt     |   14 +++---
 6 files changed, 142 insertions(+), 82 deletions(-)

applies-to: 0e248e1eed0d5aedd0054cf273df03460047ebc9 4baf91676c2462796137e93917c75f2e14ebb877

Documentation/git-checkout-index.txt +48 -30
index 5bff486..97eef22 100644
@@ -45,53 +45,71 @@ OPTIONS
 
 The order of the flags used to matter, but not anymore.
 
-Just doing "git-checkout-index" does nothing. You probably meant
-"git-checkout-index -a". And if you want to force it, you want
-"git-checkout-index -f -a".
+Just doing `git-checkout-index` does nothing. You probably meant
+`git-checkout-index -a`. And if you want to force it, you want
+`git-checkout-index -f -a`.
 
 Intuitiveness is not the goal here. Repeatability is. The reason for
-the "no arguments means no work" thing is that from scripts you are
-supposed to be able to do things like:
+the "no arguments means no work" behavior is that from scripts you are
+supposed to be able to do:
 
-	find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
+$ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
 
 which will force all existing `*.h` files to be replaced with their
 cached copies. If an empty command line implied "all", then this would
 force-refresh everything in the index, which was not the point.
 
-To update and refresh only the files already checked out:
-
-        git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
-
-Oh, and the "--" is just a good idea when you know the rest will be
-filenames. Just so that you wouldn't have a filename of "-a" causing
-problems (not possible in the above example, but get used to it in
-scripting!).
-
-The prefix ability basically makes it trivial to use
-git-checkout-index as an "export as tree" function. Just read the
-desired tree into the index, and do a
-
-        git-checkout-index --prefix=git-export-dir/ -a
-
-and git-checkout-index will "export" the index into the specified
+The `--` is just a good idea when you know the rest will be filenames;
+it will prevent problems with a filename of, for example,  `-a`.
+Using `--` is probably a good policy in scripts.
+
+
+EXAMPLES
+--------
+To update and refresh only the files already checked out::
++
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
+
+Using `git-checkout-index` to "export an entire tree"::
+	The prefix ability basically makes it trivial to use
+	`git-checkout-index` as an "export as tree" function.
+	Just read the desired tree into the index, and do:
++
+----------------
+$ git-checkout-index --prefix=git-export-dir/ -a
+----------------
++
+`git-checkout-index` will "export" the index into the specified
 directory.
++
+The final "/" is important. The exported name is literally just
+prefixed with the specified string.  Contrast this with the
+following example.
+
+Export files with a prefix::
++
+----------------
+$ git-checkout-index --prefix=.merged- Makefile
+----------------
++
+This will check out the currently cached copy of `Makefile`
+into the file `.merged-Makefile`.
 
-NOTE The final "/" is important. The exported name is literally just
-prefixed with the specified string, so you can also do something like
-
-    git-checkout-index --prefix=.merged- Makefile
-
-to check out the currently cached copy of `Makefile` into the file
-`.merged-Makefile`
 
 Author
 ------
 Written by Linus Torvalds <[email protected]>
 
+
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <[email protected]>.
+Documentation by David Greaves,
+Junio C Hamano and the git-list <[email protected]>.
+
 
 GIT
 ---
Documentation/git-init-db.txt +23 -4
index ef1826a..4486f0c 100644
@@ -8,7 +8,14 @@ git-init-db - Creates an empty git repos
 
 SYNOPSIS
 --------
-'git-init-db'
+'git-init-db' [--template=<template_directory>]
+
+
+OPTIONS
+-------
+--template=<template_directory>::
+	Provide the directory in from which templates will be used.
+
 
 DESCRIPTION
 -----------
@@ -16,14 +23,26 @@ This simply creates an empty git reposit
 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
+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'
+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_DIR/objects` directory is used.
 
-"git-init-db" won't hurt an existing repository.
+`git-init-db` won't hurt an existing repository.
+
+
+EXAMPLES
+--------
+
+Start a new git repository for an existing code base::
++
+----------------
+$ cd /path/to/my/codebase
+$ git-init-db
+----------------
+
 
 
 Author
Documentation/git-prune-packed.txt +7 -4
index 8d96a91..37c53a9 100644
@@ -9,19 +9,22 @@ residing in a pack file.
 
 SYNOPSIS
 --------
-'git-prune-packed'
+'git-prune-packed' [-n]
+
 
 DESCRIPTION
 -----------
-This program search the GIT_OBJECT_DIR for all objects that currently exist in
-a pack file as well as the independent object directories.
+This program search the `$GIT_OBJECT_DIR` for all objects that currently
+exist in a pack file as well as the independent object directories.
 
 All such extra objects are removed.
 
 A pack is a collection of objects, individually compressed, with delta
 compression applied, stored in a single file, with an associated index file.
 
-Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc.
+Packs are used to reduce the load on mirror systems, backup engines,
+disk storage, etc.
+
 
 OPTIONS
 -------
Documentation/git-read-tree.txt +41 -33

166 lines not on this page · raw message

Documentation/git-update-index.txt +15 -5
index fdcb8be..e4678cd 100644
@@ -123,7 +123,9 @@ merging.
 
 To pretend you have a file with mode and sha1 at path, say:
 
-   $ git-update-index --cacheinfo mode sha1 path
+----------------
+$ git-update-index --cacheinfo mode sha1 path
+----------------
 
 '--info-only' is used to register files without placing them in the object
 database.  This is useful for status-only repositories.
@@ -138,7 +140,9 @@ Examples
 --------
 To update and refresh only the files already checked out:
 
-   git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
 
 
 Configuration
@@ -146,12 +150,18 @@ Configuration
 
 The command honors `core.filemode` configuration variable.  If
 your repository is on an filesystem whose executable bits are
-unreliable, this should be set to 'false'.  This causes the
-command to ignore differences in file modes recorded in the
-index and the file mode on the filesystem if they differ only on
+unreliable, this should be set to 'false' (see gitlink:git-repo-config[1]).
+This causes the command to ignore differences in file modes recorded
+in the index and the file mode on the filesystem if they differ only on
 executable bit.   On such an unfortunate filesystem, you may
 need to use `git-update-index --chmod=`.
 
+
+See Also
+--------
+gitlink:git-repo-config[1]
+
+
 Author
 ------
 Written by Linus Torvalds <[email protected]>
Documentation/git-write-tree.txt +8 -6
index abee05f..77e12cb 100644
@@ -14,19 +14,21 @@ DESCRIPTION
 -----------
 Creates a tree object using the current index.
 
-The index must be merged.
+The index must be in a fully merged state.
 
-Conceptually, "git-write-tree" sync()s the current index contents
+Conceptually, `git-write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a "git-update-index" phase before you did the
-"git-write-tree".
+now, you need to have done a `git-update-index` phase before you did the
+`git-write-tree`.
+
 
 OPTIONS
 -------
 --missing-ok::
-	Normally "git-write-tree" ensures that the objects referenced by the
-	directory exist in the object database.  This option disables this check.
+	Normally `git-write-tree` ensures that the objects referenced by the
+	directory exist in the object database.  This option disables this
+	check.
 
 Author
 ------

---
0.99.9j

#1 lore raw
Quoted 6 lines · Jon Loeliger

More $ shell prompts in examples. Minor English grammar improvements. Added a few "See Also"s.
Use back-ticks on more command examples.

Thanks. You deserve to add your own name to the Documentation section ;-).

Mostly note to myself...

Documentation/git-checkout-index.txt OPTIONS · line 75

Quoted 7 lines
Documentation/git-checkout-index.txt +7 -0
+EXAMPLES
+--------
+To update and refresh only the files already checked out::
++
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------

These days, "git-checkout-index -n -u -f -a" may a preferred equivalent of the above.

Documentation/git-init-db.txt git-init-db - Creates an empty git repos · line 17

Quoted 4 lines
Documentation/git-init-db.txt +4 -0
+OPTIONS
+-------
+--template=<template_directory>::
+	Provide the directory in from which templates will be used.

? "use templates stored in the named directory" ?

Documentation/git-read-tree.txt populated. Here is an outline of how th · line 229

Quoted 11 lines
Documentation/git-read-tree.txt +2 -2
@@ -220,8 +222,8 @@ populated.  Here is an outline of how th
     matching "stage1" entry if it exists too.  .. all the normal
     trivial rules ..
 
-You would normally use "git-merge-index" with supplied
-"git-merge-one-file" to do this last step.  The script
+You would normally use `git-merge-index` with supplied
+`git-merge-one-file` to do this last step.  The script
 does not touch the files in the work tree, and the entire merge
 happens in the index file.  In other words, there is no need to
 worry about what is in the working directory, since it is never

The above paragraph is way out of date, as of beginning of June 2005. The current merge-one-file does smudge the working tree during the merge. I'll rewrite it.