Code

Accumulated documentation updates.
authorJunio C Hamano <junkio@cox.net>
Tue, 30 Aug 2005 00:21:06 +0000 (17:21 -0700)
committerJunio C Hamano <junkio@cox.net>
Tue, 30 Aug 2005 00:21:06 +0000 (17:21 -0700)
Signed-off-by: Junio C Hamano <junkio@cox.net>
Documentation/git-applymbox.txt
Documentation/git-applypatch.txt
Documentation/git-bisect-script.txt
Documentation/git-mailinfo.txt
Documentation/git-prune-script.txt
Documentation/git-repack-script.txt
Documentation/git-show-branch.txt
Documentation/git.txt

index acf0bf3d63df6742a236a29392962892fadb5841..3d813ec4cf67c039cd49b7e3e35941056e69b1a8 100644 (file)
@@ -3,26 +3,66 @@ git-applymbox(1)
 
 NAME
 ----
-git-applymbox - Some git command not yet documented.
+git-applymbox - Apply a series of patches in a mailbox
 
 
 SYNOPSIS
 --------
-'git-applymbox' [ --option ] <args>...
+'git-applymbox' [-u] [-k] [-q] ( -c .dotest/<num> | <mbox> ) [ <signoff> ]
 
 DESCRIPTION
 -----------
-Does something not yet documented.
+Splits mail messages in a mailbox into commit log message,
+authorship information and patches, and applies them to the
+current branch.
 
 
 OPTIONS
 -------
---option::
-       Some option not yet documented.
+-q::
+       Apply patches interactively.  The user will be given
+       opportunity to edit the log message and the patch before
+       attempting to apply patch in each e-mail message.
 
-<args>...::
-       Some argument not yet documented.
+-k::
+       Usually the program 'cleans up' the Subject: header line
+       to extract the title line for the commit log message,
+       among which (1) remove 'Re:' or 're:', (2) leading
+       whitespaces, (3) '[' up to ']', typically '[PATCH]', and
+       then prepends "[PATCH] ".  This flag forbids this
+       munging, and is most useful when used to read back 'git
+       format-patch --mbox' output.
 
+-u::
+       By default, the commit log message, author name and
+       author email are taken from the e-mail without any
+       charset conversion, after minimally decoding MIME
+       transfer encoding.  This flag causes the resulting
+       commit to be encoded in utf-8 by transliterating them.
+       Note that the patch is always used as is without charset
+       conversion, even with this flag.
+
+-c .dotest/<num>::
+       When the patch contained in an e-mail does not cleanly
+       apply, the command exits with an error message. The
+       patch and extracted message are found in .dotest/, and
+       you could re-run 'git applymbox' with '-c .dotest/<num>'
+       flag to restart the process after inspecting and fixing
+       them.
+
+<mbox>::
+       The name of the file that contains the e-mail messages
+       with patches.  This file should be in the UNIX mailbox
+       format.  See 'SubmittingPatches' document to learn about
+       the formatting convention for e-mail submission.
+
+<signoff>::
+       The name of the file that contains your "Signed-off-by"
+       line.  See 'SubmittingPatches' document to learn what
+       "Signed-off-by" line means.  You can also just say
+       'yes', 'true', 'me', or 'please' to use an automatically
+       generated "Signed-off-by" line based on your committer
+       identity.
 
 Author
 ------
index 55facd2c7a4c8e0c8a142ba3bc3d64902276ba84..14ce53aade7e0549fed75eb89c453c6556a6eacb 100644 (file)
@@ -3,25 +3,33 @@ git-applypatch(1)
 
 NAME
 ----
-git-applypatch - Some git command not yet documented.
+git-applypatch - Apply one patch extracted from an e-mail.
 
 
 SYNOPSIS
 --------
-'git-applypatch' [ --option ] <args>...
+'git-applypatch' <msg> <patch> <info> [<signoff>]
 
 DESCRIPTION
 -----------
-Does something not yet documented.
+Takes three files <msg>, <patch>, and <info> prepared from an
+e-mail message by 'git-mailinfo', and creates a commit.  It is
+usually not necessary to use this command directly.
 
 
 OPTIONS
 -------
---option::
-       Some option not yet documented.
+<msg>::
+       Commit log message (sans the first line, which comes
+       from e-mail Subject stored in <info>).
 
-<args>...::
-       Some argument not yet documented.
+<patch>::
+       The patch to apply.
+
+<info>:
+       Author and subject information extracted from e-mail,
+       used on "author" line and as the first line of the
+       commit log message.
 
 
 Author
index 1f5e38626b60f369d4c622c946008d2e7c82f50b..1b0345199c8961e18592d81014402b584b138cba 100644 (file)
@@ -3,25 +3,69 @@ git-bisect-script(1)
 
 NAME
 ----
-git-bisect-script - Some git command not yet documented.
+git-bisect-script - Find the change that introduced a bug
 
 
 SYNOPSIS
 --------
-'git-bisect-script' [ --option ] <args>...
+'git bisect' start
+'git bisect' bad <rev>
+'git bisect' good <rev>
+'git bisect' reset [<branch>]
 
 DESCRIPTION
 -----------
-Does something not yet documented.
+This command uses 'git-rev-list --bisect' option to help drive
+the binary search process to find which change introduced a bug,
+given an old "good" commit object name and a later "bad" commit
+object name.
 
+The way you use it is:
 
-OPTIONS
--------
---option::
-       Some option not yet documented.
+------------------------------------------------
+git bisect start
+git bisect bad                 # Current version is bad
+git bisect good v2.6.13-rc2    # v2.6.13-rc2 was the last version
+                               # tested that was good
+------------------------------------------------
 
-<args>...::
-       Some argument not yet documented.
+When you give at least one bad and one good versions, it will
+bisect the revision tree and say something like:
+
+------------------------------------------------
+Bisecting: 675 revisions left to test after this
+------------------------------------------------
+
+and check out the state in the middle. Now, compile that kernel, and boot
+it. Now, let's say that this booted kernel works fine, then just do
+
+------------------------------------------------
+git bisect good                        # this one is good
+------------------------------------------------
+
+which will now say
+
+------------------------------------------------
+Bisecting: 337 revisions left to test after this
+------------------------------------------------
+
+and you continue along, compiling that one, testing it, and depending on
+whether it is good or bad, you say "git bisect good" or "git bisect bad",
+and ask for the next bisection.
+
+Until you have no more left, and you'll have been left with the first bad
+kernel rev in "refs/bisect/bad".
+
+Oh, and then after you want to reset to the original head, do a
+
+------------------------------------------------
+git bisect reset
+------------------------------------------------
+
+to get back to the master branch, instead of being in one of the bisection
+branches ("git bisect start" will do that for you too, actually: it will
+reset the bisection state, and before it does that it checks that you're
+not using some old bisection branch).
 
 
 Author
index b75f61c84ce07946cad2344502e0a823575d8c9c..eb3a3d1be7e6d45686408882ae16c5608faa8476 100644 (file)
@@ -3,30 +3,57 @@ git-mailinfo(1)
 
 NAME
 ----
-git-mailinfo - Some git command not yet documented.
+git-mailinfo - Extracts patch from a single e-mail message.
 
 
 SYNOPSIS
 --------
-'git-mailinfo' [ --option ] <args>...
+'git-mailinfo' [-k] [-u] <msg> <patch>
+
 
 DESCRIPTION
 -----------
-Does something not yet documented.
+Reading a single e-mail message from the standard input, and
+writes the commit log message in <msg> file, and the patches in
+<patch> file.  The author name, e-mail and e-mail subject are
+written out to the standard output to be used by git-applypatch
+to create a commit.  It is usually not necessary to use this
+command directly.
 
 
 OPTIONS
 -------
---option::
-       Some option not yet documented.
+-k::
+       Usually the program 'cleans up' the Subject: header line
+       to extract the title line for the commit log message,
+       among which (1) remove 'Re:' or 're:', (2) leading
+       whitespaces, (3) '[' up to ']', typically '[PATCH]', and
+       then prepends "[PATCH] ".  This flag forbids this
+       munging, and is most useful when used to read back 'git
+       format-patch --mbox' output.
+
+-u::
+       By default, the commit log message, author name and
+       author email are taken from the e-mail without any
+       charset conversion, after minimally decoding MIME
+       transfer encoding.  This flag causes the resulting
+       commit to be encoded in utf-8 by transliterating them.
+       Note that the patch is always used as is without charset
+       conversion, even with this flag.
 
-<args>...::
-       Some argument not yet documented.
+<msg>::
+       The commit log message extracted from e-mail, usually
+       except the title line which comes from e-mail Subject.
+
+<patch>::
+       The patch extracted from e-mail.
 
 
 Author
 ------
-Written by Linus Torvalds <torvalds@osdl.org>
+Written by Linus Torvalds <torvalds@osdl.org> and
+Junio C Hamano <junkio@cox.net>
+
 
 Documentation
 --------------
index e8305a6f3d7a7ef0972ca3142a14157c17fba1af..0f76e8fd0d3c4a3413e49710cf7f82448f10eec2 100644 (file)
@@ -1,6 +1,6 @@
 git-prune-script(1)
 ===================
-v0.1, May 2005
+v0.99.5, Aug 2005
 
 NAME
 ----
@@ -9,14 +9,24 @@ git-prune-script - Prunes all unreachable objects from the object database
 
 SYNOPSIS
 --------
-'git-prune-script'
+'git-prune-script' [-n]
 
 DESCRIPTION
 -----------
-This runs "git-fsck-cache --unreachable" program using the heads specified
-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.
+
+This runs `git-fsck-cache --unreachable` using the heads
+specified 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.  In addition, it
+prunes the unpacked objects that are also found in packs by
+running `git prune-packed`.
+
+OPTIONS
+-------
+
+-n::
+       Do not remove anything; just report what it would
+       remove.
 
 
 Author
index 497d0dfe80738154b643e327f718977d42e2981a..cd449bcc2d751d6064c0e82e34217cb472a91d15 100644 (file)
@@ -1,6 +1,6 @@
 git-repack-script(1)
 =====================
-v0.1, August 2005
+v0.99.5, August 2005
 
 NAME
 ----
@@ -10,17 +10,36 @@ objects into pack files.
 
 SYNOPSIS
 --------
-'git-repack-script'
+'git-repack-script' [-a] [-d]
 
 DESCRIPTION
 -----------
-This script is used to combine all objects that do not currently reside in a
-"pack", into a pack.
 
-A pack is a collection of objects, individually compressed, with delta
-compression applied, stored in a single file, with an associated index file.
+This script is used to combine all objects that do not currently
+reside in a "pack", into a pack.
+
+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.
+
+OPTIONS
+-------
+
+-a::
+       Instead of incrementally packing the unpacked objects,
+       pack everything available into a single pack.
+       Especially useful when packing a repository that is used
+       for a private development and there no need to worry
+       about people fetching via dumb protocols from it.  Use
+       with '-d'.
+
+-d::
+       After packing, if the newly created packs make some
+       existing packs redundant, remove the redundant packs.
 
-Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc.
 
 Author
 ------
index 71d5ba8fd78dfbbdefde52f3b1bae73a0e52e50b..5103c0c4f909a787e52c26cee4119212f1eb6c19 100644 (file)
@@ -1,6 +1,6 @@
 git-show-branch(1)
 ==================
-v0.99.4, Aug 2005
+v0.99.5, Aug 2005
 
 NAME
 ----
@@ -28,7 +28,8 @@ OPTIONS
 --more=<n>::
        Usually the command stops output upon showing the commit
        that is the common ancestor of all the branches.  This
-       flag tells the command to go <n> commits beyond that.
+       flag tells the command to go <n> more common commits
+       beyond that.
 
 --merge-base::
        Instead of showing the commit list, just act like the
index 221889bc75f47e35cf20b58df33b4f01c0c6698c..befe3e52cd8e0bfa5cbcd10005f42b816006af1e 100644 (file)
@@ -52,49 +52,50 @@ SCMs layered over git.
 
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
+link:git-apply.html[git-apply]::
+       Reads a "diff -up1" or git generated patch file and
+       applies it to the working tree.
+
 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-hash-object.html[git-hash-object]::
+       Computes the object ID from a file.
+
 link:git-init-db.html[git-init-db]::
        Creates an empty git object database
 
-link:git-merge-base.html[git-merge-base]::
-       Finds as good a common ancestor as possible for a merge
+link:git-merge-cache.html[git-merge-cache]::
+       Runs a merge for files needing merging
 
 link:git-mktag.html[git-mktag]::
        Creates a tag object
 
+link:git-pack-objects.html[git-pack-objects]::
+       Creates a packed archive of objects.
+
+link:git-prune-packed.html[git-prune-packed]::
+       Remove extra objects that are already in pack files.
+
 link:git-read-tree.html[git-read-tree]::
        Reads tree information into the directory cache
 
+link:git-unpack-objects.html[git-unpack-objects]::
+       Unpacks objects out of a packed archive.
+
 link:git-update-cache.html[git-update-cache]::
        Modifies the index or directory cache
 
-link:git-hash-object.html[git-hash-object]::
-       Computes the object ID from a file.
-
 link:git-write-tree.html[git-write-tree]::
        Creates a tree from the current cache
 
-link:git-pack-objects.html[git-pack-objects]::
-       Creates a packed archive of objects.
-
-link:git-unpack-objects.html[git-unpack-objects]::
-       Unpacks objects out of a packed archive.
-
-link:git-prune-packed.html[git-prune-packed]::
-       Remove extra objects that are already in pack files.
-
-link:git-apply.html[git-apply]::
-       Reads a "diff -up1" or git generated patch file and
-       applies it to the working tree.
-
 
 Interrogation commands
 ~~~~~~~~~~~~~~~~~~~~~~
+
 link:git-cat-file.html[git-cat-file]::
        Provide content or type information for repository objects
 
@@ -104,12 +105,12 @@ link:git-diff-cache.html[git-diff-cache]::
 link:git-diff-files.html[git-diff-files]::
        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
-
 link:git-diff-stages.html[git-diff-stages]::
        Compares two "merge stages" in the index file.
 
+link:git-diff-tree.html[git-diff-tree]::
+       Compares the content and mode of blobs found via two tree objects
+
 link:git-export.html[git-export]::
        Exports each commit and a diff against each of its parents
 
@@ -122,8 +123,8 @@ link:git-ls-files.html[git-ls-files]::
 link:git-ls-tree.html[git-ls-tree]::
        Displays a tree object in human readable form
 
-link:git-merge-cache.html[git-merge-cache]::
-       Runs a merge for files needing merging
+link:git-merge-base.html[git-merge-base]::
+       Finds as good a common ancestor as possible for a merge
 
 link:git-rev-list.html[git-rev-list]::
        Lists commit objects in reverse chronological order
@@ -131,6 +132,9 @@ 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-show-index.html[git-show-index]::
+       Displays contents of a pack idx file.
+
 link:git-tar-tree.html[git-tar-tree]::
        Creates a tar archive of the files in the named tree
 
@@ -140,9 +144,6 @@ link:git-unpack-file.html[git-unpack-file]::
 link:git-var.html[git-var]::
        Displays a git logical variable
 
-link:git-show-index.html[git-show-index]::
-       Displays contents of a pack idx file.
-
 link:git-verify-pack.html[git-verify-pack]::
        Validates packed GIT archive files
 
@@ -153,174 +154,172 @@ touch the working file set - but in general they don't
 Synching repositories
 ~~~~~~~~~~~~~~~~~~~~~
 
-link:git-clone-script.html[git-clone-script]::
-       Clones a repository into the current repository (user interface)
-
 link:git-clone-pack.html[git-clone-pack]::
        Clones a repository into the current repository (engine
        for ssh and local transport)
 
+link:git-fetch-pack.html[git-fetch-pack]::
+       Updates from a remote 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-ssh-pull.html[git-ssh-pull]::
-       Pulls from a remote repository over ssh connection
-
-link:git-send-pack.html[git-send-pack]::
-       Pushes to a remote repository, intelligently.
+link:git-peek-remote.html[git-peek-remote]::
+       Lists references on a remote repository using upload-pack protocol.
 
 link:git-receive-pack.html[git-receive-pack]::
        Invoked by 'git-send-pack' to receive what is pushed to it.
 
-link:git-clone-pack.html[git-clone-pack]::
-       Clones from a remote repository.
-
-link:git-fetch-pack.html[git-fetch-pack]::
-       Updates from a remote repository.
+link:git-send-pack.html[git-send-pack]::
+       Pushes to a remote repository, intelligently.
 
-link:git-peek-remote.html[git-peek-remote]::
-       Lists references on a remote repository using upload-pack protocol.
+link:git-ssh-pull.html[git-ssh-pull]::
+       Pulls from a remote repository over ssh connection
 
-link:git-upload-pack.html[git-upload-pack]::
-       Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
-       what are asked for.
+link:git-ssh-push.html[git-ssh-push]::
+       Helper "server-side" program used by git-ssh-pull
 
 link:git-update-server-info.html[git-update-server-info]::
        Updates auxiliary information on a dumb server to help
        clients discover references and packs on it.
 
+link:git-upload-pack.html[git-upload-pack]::
+       Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
+       what are asked for.
+
 
 Porcelain-ish Commands
 ----------------------
-link:git-revert-script.html[git-revert-script]::
-       Revert an existing commit.
-
-link:git-cherry-pick-script.html[git-cherry-pick-script]::
-       Cherry-pick the effect of an existing commit.
-
-link:git-rebase-script.html[git-rebase-script]::
-       Rebase local commits to new upstream head.
 
 link:git-add-script.html[git-add-script]::
        Add paths to the index file.
 
+link:git-applymbox.html[git-applymbox]::
+       Apply patches from a mailbox.
+
+link:git-bisect-script.html[git-bisect-script]::
+       Find the change that introduced a bug.
+
 link:git-branch-script.html[git-branch-script]::
        Create and Show branches.
 
-link:git-whatchanged.html[git-whatchanged]::
-       Shows commit logs and differences they introduce.
-
-link:git-log-script.html[git-log-script]::
-       Shows commit logs.
+link:git-cherry-pick-script.html[git-cherry-pick-script]::
+       Cherry-pick the effect of an existing commit.
 
-link:git-shortlog.html[git-shortlog]::
-       Summarizes 'git log' output.
+link:git-clone-script.html[git-clone-script]::
+       Clones a repository into a new directory.
 
-link:git-status-script.html[git-status-script]::
-       Shows the working tree status.
+link:git-commit-script.html[git-commit-script]::
+       Record changes to the repository.
 
 link:git-fetch-script.html[git-fetch-script]::
        Download from a remote repository via various protocols.
 
-link:git-pull-script.html[git-pull-script]::
-       Fetch from and merge with a remote repository.
+link:git-log-script.html[git-log-script]::
+       Shows commit logs.
 
-link:git-resolve-script.html[git-resolve-script]::
-       Merge two commits.
+link:git-ls-remote-script.html[git-ls-remote-script]::
+       Shows references in a remote or local repository.
 
 link:git-octopus-script.html[git-octopus-script]::
        Merge more than two commits.
 
+link:git-pull-script.html[git-pull-script]::
+       Fetch from and merge with a remote repository.
+
 link:git-push-script.html[git-push-script]::
        Update remote refs along with associated objects.
 
-link:git-commit-script.html[git-commit-script]::
-       Record changes to the repository.
+link:git-rebase-script.html[git-rebase-script]::
+       Rebase local commits to new upstream head.
 
-link:git-show-branch.html[git-show-branch]::
-       Show branches and their commits.
+link:git-rename-script.html[git-rename]::
+       Rename files and directories.
 
 link:git-repack-script.html[git-repack-script]::
        Pack unpacked objects in a repository.
 
-link:git-rename-script.html[git-rename]::
-       Rename files and directories.
+link:git-resolve-script.html[git-resolve-script]::
+       Merge two commits.
 
-link:git-ls-remote-script.html[git-ls-remote-script]::
-       Shows references in a remote or local repository.
+link:git-revert-script.html[git-revert-script]::
+       Revert an existing commit.
+
+link:git-shortlog.html[git-shortlog]::
+       Summarizes 'git log' output.
+
+link:git-show-branch.html[git-show-branch]::
+       Show branches and their commits.
+
+link:git-status-script.html[git-status-script]::
+       Shows the working tree status.
 
 link:git-verify-tag-script.html[git-verify-tag-script]::
        Check the GPG signature of tag.
 
+link:git-whatchanged.html[git-whatchanged]::
+       Shows commit logs and differences they introduce.
+
 
 Ancillary Commands
 ------------------
 Manipulators:
 
-link:git-relink-script.html[git-relink-script]::
-       Hardlink common objects in local repositories.
+link:git-applypatch.html[git-applypatch]::
+       Apply one patch extracted from an e-mail.
 
 link:git-convert-cache.html[git-convert-cache]::
        Converts old-style GIT repository
 
+link:git-cvsimport-script.html[git-cvsimport-script]::
+       Salvage your data out of another SCM people love to hate.
+
 link:git-merge-one-file-script.html[git-merge-one-file-script]::
        The standard helper program to use with "git-merge-cache"
 
 link:git-prune-script.html[git-prune-script]::
        Prunes all unreachable objects from the object database
 
+link:git-relink-script.html[git-relink-script]::
+       Hardlink common objects in local repositories.
+
+link:git-sh-setup-script.html[git-sh-setup-script]::
+       Common git shell script setup code.
+
 link:git-tag-script.html[git-tag-script]::
        An example script to create a tag object signed with GPG
 
-link:git-cvsimport-script.html[git-cvsimport-script]::
-       Salvage your data out of another SCM people love to hate.
-
 
 Interrogators:
 
-link:git-patch-id.html[git-patch-id]::
-       Compute unique ID for a patch.
+link:git-cherry.html[git-cherry]::
+       Find commits not merged upstream.
 
 link:git-count-objects-script.html[git-count-objects-script]::
        Count unpacked number of objects and their disk consumption.
 
-link:git-cherry.html[git-cherry]::
-       Find commits not merged upstream.
-
 link:git-diff-helper.html[git-diff-helper]::
        Generates patch format output for git-diff-*
 
-link:git-ssh-push.html[git-ssh-push]::
-       Helper "server-side" program used by git-ssh-pull
+link:git-mailinfo.html[git-mailinfo]::
+       Extracts patch from a single e-mail message.
+
+link:git-mailsplit.html[git-mailsplit]::
+       git-mailsplit.
+
+link:git-patch-id.html[git-patch-id]::
+       Compute unique ID for a patch.
 
 link:git-send-email-script.html[git-send-email]::
        Send patch e-mails out of "format-patch --mbox" output.
 
-link:git-sh-setup-script.html[git-sh-setup-script]::
-       Common git shell script setup code.
-
 
 Commands not yet documented
 ---------------------------
 
-link:git-applymbox.html[git-applymbox]::
-       git-applymbox.
-
-link:git-applypatch.html[git-applypatch]::
-       git-applypatch.
-
-link:git-mailinfo.html[git-mailinfo]::
-       git-mailinfo.
-
-link:git-mailsplit.html[git-mailsplit]::
-       git-mailsplit.
-
-link:git-bisect-script.html[git-bisect-script]::
-       git-bisect-script.
-
 link:git-build-rev-cache.html[git-build-rev-cache]::
        git-build-rev-cache.