From f85a41916163097c3c307ac45d1a935564c52bf0 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 29 Aug 2005 17:21:06 -0700 Subject: [PATCH] Accumulated documentation updates. Signed-off-by: Junio C Hamano --- Documentation/git-applymbox.txt | 54 +++++++- Documentation/git-applypatch.txt | 22 ++- Documentation/git-bisect-script.txt | 62 +++++++-- Documentation/git-mailinfo.txt | 43 ++++-- Documentation/git-prune-script.txt | 22 ++- Documentation/git-repack-script.txt | 33 ++++- Documentation/git-show-branch.txt | 5 +- Documentation/git.txt | 205 ++++++++++++++-------------- 8 files changed, 297 insertions(+), 149 deletions(-) diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt index acf0bf3d6..3d813ec4c 100644 --- a/Documentation/git-applymbox.txt +++ b/Documentation/git-applymbox.txt @@ -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 ] ... +'git-applymbox' [-u] [-k] [-q] ( -c .dotest/ | ) [ ] 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. -...:: - 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/:: + 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/' + flag to restart the process after inspecting and fixing + them. + +:: + 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. + +:: + 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 ------ diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt index 55facd2c7..14ce53aad 100644 --- a/Documentation/git-applypatch.txt +++ b/Documentation/git-applypatch.txt @@ -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 ] ... +'git-applypatch' [] DESCRIPTION ----------- -Does something not yet documented. +Takes three files , , and 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. +:: + Commit log message (sans the first line, which comes + from e-mail Subject stored in ). -...:: - Some argument not yet documented. +:: + The patch to apply. + +: + Author and subject information extracted from e-mail, + used on "author" line and as the first line of the + commit log message. Author diff --git a/Documentation/git-bisect-script.txt b/Documentation/git-bisect-script.txt index 1f5e38626..1b0345199 100644 --- a/Documentation/git-bisect-script.txt +++ b/Documentation/git-bisect-script.txt @@ -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 ] ... +'git bisect' start +'git bisect' bad +'git bisect' good +'git bisect' reset [] 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 +------------------------------------------------ -...:: - 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 diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index b75f61c84..eb3a3d1be 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -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 ] ... +'git-mailinfo' [-k] [-u] + DESCRIPTION ----------- -Does something not yet documented. +Reading a single e-mail message from the standard input, and +writes the commit log message in file, and the patches in + 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. -...:: - Some argument not yet documented. +:: + The commit log message extracted from e-mail, usually + except the title line which comes from e-mail Subject. + +:: + The patch extracted from e-mail. Author ------ -Written by Linus Torvalds +Written by Linus Torvalds and +Junio C Hamano + Documentation -------------- diff --git a/Documentation/git-prune-script.txt b/Documentation/git-prune-script.txt index e8305a6f3..0f76e8fd0 100644 --- a/Documentation/git-prune-script.txt +++ b/Documentation/git-prune-script.txt @@ -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 diff --git a/Documentation/git-repack-script.txt b/Documentation/git-repack-script.txt index 497d0dfe8..cd449bcc2 100644 --- a/Documentation/git-repack-script.txt +++ b/Documentation/git-repack-script.txt @@ -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 ------ diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 71d5ba8fd..5103c0c4f 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -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=:: 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 commits beyond that. + flag tells the command to go more common commits + beyond that. --merge-base:: Instead of showing the commit list, just act like the diff --git a/Documentation/git.txt b/Documentation/git.txt index 221889bc7..befe3e52c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -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. -- 2.26.2