From 52a22d1e726f91b0ba4ea0afb7cfbfaaf624127b Mon Sep 17 00:00:00 2001 From: A Large Angry SCM Date: Fri, 26 Aug 2005 18:18:48 -0700 Subject: [PATCH] Subject: [PATCH] Add some documentation. Add some documentation. Text taken from the the commit messages and the command sources. --- Documentation/git-add-script.txt | 17 ++++++----------- Documentation/git-branch-script.txt | 19 ++++++++++--------- Documentation/git-cherry.txt | 22 +++++++++++++--------- Documentation/git-count-objects-script.txt | 18 ++++-------------- Documentation/git-patch-id.txt | 19 +++++++++---------- Documentation/git-rebase-script.txt | 17 +++++++---------- Documentation/git-relink-script.txt | 19 +++++++++---------- Documentation/git-revert-script.txt | 18 +++++++----------- Documentation/git-sh-setup-script.txt | 18 +++++++----------- Documentation/git-verify-tag-script.txt | 16 +++++----------- 10 files changed, 77 insertions(+), 106 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-add-script.txt b/Documentation/git-add-script.txt index 866d9c2d94..7ad2cfd880 100644 --- a/Documentation/git-add-script.txt +++ b/Documentation/git-add-script.txt @@ -3,26 +3,21 @@ git-add-script(1) NAME ---- -git-add-script - Some git command not yet documented. - +git-add-script - Add files to the cache. SYNOPSIS -------- -'git-add-script' [ --option ] ... +'git-add-script' []\+ DESCRIPTION ----------- -Does something not yet documented. - +A simple wrapper to git-update-cache to add files to the cache for people used +to do "cvs add". OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. - +:: + Files to add to the cache. Author ------ diff --git a/Documentation/git-branch-script.txt b/Documentation/git-branch-script.txt index fe9a041950..3ace8adc83 100644 --- a/Documentation/git-branch-script.txt +++ b/Documentation/git-branch-script.txt @@ -3,26 +3,27 @@ git-branch-script(1) NAME ---- -git-branch-script - Some git command not yet documented. - +git-branch-script - Create a new branch. SYNOPSIS -------- -'git-branch-script' [ --option ] ... +'git-branch-script' [ [start-point]] DESCRIPTION ----------- -Does something not yet documented. +If no argument is provided, show available branches and mark current +branch with star. Otherwise, create a new branch of name . +If a starting point is also specified, that will be where the branch is +created, otherwise it will be created at the current HEAD. OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. +:: + The name of the branch to create. +start-point:: + Where to make the branch; defaults to HEAD. Author ------ diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 14d0bd51cd..9ff7bc25c1 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -3,26 +3,30 @@ git-cherry(1) NAME ---- -git-cherry - Some git command not yet documented. - +git-cherry - Find commits not merged upstream. SYNOPSIS -------- -'git-cherry' [ --option ] ... +'git-cherry' [-v] [] DESCRIPTION ----------- -Does something not yet documented. - +Each commit between the fork-point and is examined, and compared against +the change each commit between the fork-point and introduces. +Commits already included in upstream are prefixed with '-' (meaning "drop from +my local pull"), while commits missing from upstream are prefixed with '+' +(meaning "add to the updated upstream"). OPTIONS ------- ---option:: - Some option not yet documented. +-v:: + Verbose. -...:: - Some argument not yet documented. +:: + Upstream branch to compare against. +:: + Working branch; defaults to HEAD. Author ------ diff --git a/Documentation/git-count-objects-script.txt b/Documentation/git-count-objects-script.txt index 2543617094..8a3cedfb5f 100644 --- a/Documentation/git-count-objects-script.txt +++ b/Documentation/git-count-objects-script.txt @@ -3,26 +3,16 @@ git-count-objects-script(1) NAME ---- -git-count-objects-script - Some git command not yet documented. - +git-count-objects-script - Reports on unpacked objects. SYNOPSIS -------- -'git-count-objects-script' [ --option ] ... +'git-count-objects-script' DESCRIPTION ----------- -Does something not yet documented. - - -OPTIONS -------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. - +This counts the number of unpacked object files and disk space consumed by +them, to help you decide when it is a good time to repack. Author ------ diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 9a4abd124d..b6fa2a8b39 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -3,26 +3,25 @@ git-patch-id(1) NAME ---- -git-patch-id - Some git command not yet documented. - +git-patch-id - Generate a patch ID. SYNOPSIS -------- -'git-patch-id' [ --option ] ... +'git-patch-id' < DESCRIPTION ----------- -Does something not yet documented. +A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with +whitespace and line numbers ignored. As such, it's "reasonably stable", but at +the same time also reasonably unique, ie two patches that have the same "patch +ID" are almost guaranteed to be the same thing. +IOW, you can use this thing to look for likely duplicate commits. OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. - +:: + The diff to create the ID of. Author ------ diff --git a/Documentation/git-rebase-script.txt b/Documentation/git-rebase-script.txt index ba7cbb777c..a9e4b21049 100644 --- a/Documentation/git-rebase-script.txt +++ b/Documentation/git-rebase-script.txt @@ -3,26 +3,23 @@ git-rebase-script(1) NAME ---- -git-rebase-script - Some git command not yet documented. - +git-rebase-script - Rebase local commits to new upstream head. SYNOPSIS -------- -'git-rebase-script' [ --option ] ... +'git-rebase-script' [] DESCRIPTION ----------- -Does something not yet documented. - +Rebases local commits to the new head of the upstream tree.' OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. +:: + Upstream branch to compare against. +:: + Working branch; defaults to HEAD. Author ------ diff --git a/Documentation/git-relink-script.txt b/Documentation/git-relink-script.txt index 4c2b435d1e..99c05d4512 100644 --- a/Documentation/git-relink-script.txt +++ b/Documentation/git-relink-script.txt @@ -3,26 +3,25 @@ git-relink-script(1) NAME ---- -git-relink-script - Some git command not yet documented. - +git-relink-script - Hardlink common objects in local repositories. SYNOPSIS -------- -'git-relink-script' [ --option ] ... +'git-relink-script' [--safe] []\* DESCRIPTION ----------- -Does something not yet documented. - +This will scan 2 or more object repositories and look for common objects, check +if they are hardlinked, and replace one with a hardlink to the other if not. OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. +--safe:: + Stops if two objects with the same hash exist but have different sizes. + Default is to warn and continue. +:: + Directories containing a .git/objects/ subdirectory. Author ------ diff --git a/Documentation/git-revert-script.txt b/Documentation/git-revert-script.txt index 8a532e6d09..727073e279 100644 --- a/Documentation/git-revert-script.txt +++ b/Documentation/git-revert-script.txt @@ -3,26 +3,22 @@ git-revert-script(1) NAME ---- -git-revert-script - Some git command not yet documented. - +git-revert-script - Revert an existing commit. SYNOPSIS -------- -'git-revert-script' [ --option ] ... +'git-revert-script' DESCRIPTION ----------- -Does something not yet documented. - +Given one existing commit, revert the change the patch introduces, and record a +new commit that records it. This requires your working tree to be clean (no +modifications from the HEAD commit). OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. - +:: + Commit to revert. Author ------ diff --git a/Documentation/git-sh-setup-script.txt b/Documentation/git-sh-setup-script.txt index 92addd71fe..5ac613a2c7 100644 --- a/Documentation/git-sh-setup-script.txt +++ b/Documentation/git-sh-setup-script.txt @@ -3,26 +3,22 @@ git-sh-setup-script(1) NAME ---- -git-sh-setup-script - Some git command not yet documented. - +git-sh-setup-script - Common git shell script setup code. SYNOPSIS -------- -'git-sh-setup-script' [ --option ] ... +'git-sh-setup-script' DESCRIPTION ----------- -Does something not yet documented. - -OPTIONS -------- ---option:: - Some option not yet documented. +Sets up the normal git environment variables and a few helper functions +(currently just "die()"), and returns ok if it all looks like a git archive. +So use it something like -...:: - Some argument not yet documented. + . git-sh-setup-script || die "Not a git archive" +to make the rest of the git scripts more careful and readable. Author ------ diff --git a/Documentation/git-verify-tag-script.txt b/Documentation/git-verify-tag-script.txt index 88a264681f..d5d747cd84 100644 --- a/Documentation/git-verify-tag-script.txt +++ b/Documentation/git-verify-tag-script.txt @@ -3,26 +3,20 @@ git-verify-tag-script(1) NAME ---- -git-verify-tag-script - Some git command not yet documented. - +git-verify-tag-script - Check the GPG signature of tag. SYNOPSIS -------- -'git-verify-tag-script' [ --option ] ... +'git-verify-tag-script' DESCRIPTION ----------- -Does something not yet documented. - +Validates the gpg signature created by git-tag-script. OPTIONS ------- ---option:: - Some option not yet documented. - -...:: - Some argument not yet documented. - +:: + SHA1 identifier of a git tag object. Author ------ -- cgit v1.2.3 From 905197de9f8f1a2ce619ac888ab7a2e1a67acb56 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 26 Aug 2005 21:33:46 -0700 Subject: Update the main documentation index. Gitzilla updated bunch of undocumented command pages, so move the entries in the main documentation index around to put them in proper category. Ordering within category will be fixed later. Signed-off-by: Junio C Hamano --- Documentation/git-add-script.txt | 4 +-- Documentation/git-rebase-script.txt | 2 +- Documentation/git.txt | 62 ++++++++++++++++++------------------- 3 files changed, 34 insertions(+), 34 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-add-script.txt b/Documentation/git-add-script.txt index 7ad2cfd880..300114358a 100644 --- a/Documentation/git-add-script.txt +++ b/Documentation/git-add-script.txt @@ -7,7 +7,7 @@ git-add-script - Add files to the cache. SYNOPSIS -------- -'git-add-script' []\+ +'git-add-script' ... DESCRIPTION ----------- @@ -16,7 +16,7 @@ to do "cvs add". OPTIONS ------- -:: +...:: Files to add to the cache. Author diff --git a/Documentation/git-rebase-script.txt b/Documentation/git-rebase-script.txt index a9e4b21049..8f14186f82 100644 --- a/Documentation/git-rebase-script.txt +++ b/Documentation/git-rebase-script.txt @@ -11,7 +11,7 @@ SYNOPSIS DESCRIPTION ----------- -Rebases local commits to the new head of the upstream tree.' +Rebases local commits to the new head of the upstream tree. OPTIONS ------- diff --git a/Documentation/git.txt b/Documentation/git.txt index d4ede094f8..f63cbdd372 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1,6 +1,6 @@ git(7) ====== -v0.99.4, Aug 2005 +v0.99.5, Aug 2005 NAME ---- @@ -195,6 +195,18 @@ link:git-update-server-info.html[git-update-server-info]:: Porcelain-ish Commands ---------------------- +link:git-revert-script.html[git-revert-script]:: + Revert 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-branch-script.html[git-branch-script]:: + Create and Show branches. + link:git-whatchanged.html[git-whatchanged]:: Shows commit logs and differences they introduce. @@ -237,11 +249,17 @@ link:git-rename-script.html[git-rename]:: link:git-ls-remote-script.html[git-ls-remote-script]:: Shows references in a remote or local repository. +link:git-verify-tag-script.html[git-verify-tag-script]:: + Check the GPG signature of tag. + Ancillary Commands ------------------ Manipulators: +link:git-relink-script.html[git-relink-script]:: + Hardlink common objects in local repositories. + link:git-apply-patch-script.html[git-apply-patch-script]:: Sample script to apply the diffs from git-diff-* @@ -263,6 +281,15 @@ link:git-cvsimport-script.html[git-cvsimport-script]:: Interrogators: +link:git-patch-id.html[git-patch-id]:: + Compute unique ID for a patch. + +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-* @@ -272,6 +299,9 @@ link:git-ssh-push.html[git-ssh-push]:: 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 --------------------------- @@ -288,30 +318,18 @@ link:git-mailinfo.html[git-mailinfo]:: link:git-mailsplit.html[git-mailsplit]:: git-mailsplit. -link:git-add-script.html[git-add-script]:: - git-add-script. - link:git-bisect-script.html[git-bisect-script]:: git-bisect-script. -link:git-branch-script.html[git-branch-script]:: - git-branch-script. - link:git-build-rev-cache.html[git-build-rev-cache]:: git-build-rev-cache. link:git-checkout-script.html[git-checkout-script]:: git-checkout-script. -link:git-cherry.html[git-cherry]:: - git-cherry. - link:git-clone-dumb-http.html[git-clone-dumb-http]:: git-clone-dumb-http. -link:git-count-objects-script.html[git-count-objects-script]:: - git-count-objects-script. - link:git-daemon.html[git-daemon]:: git-daemon. @@ -324,15 +342,6 @@ link:git-format-patch-script.html[git-format-patch-script]:: link:git-get-tar-commit-id.html[git-get-tar-commit-id]:: git-get-tar-commit-id. -link:git-patch-id.html[git-patch-id]:: - git-patch-id. - -link:git-rebase-script.html[git-rebase-script]:: - git-rebase-script. - -link:git-relink-script.html[git-relink-script]:: - git-relink-script. - link:git-request-pull-script.html[git-request-pull-script]:: git-request-pull-script. @@ -342,21 +351,12 @@ link:git-reset-script.html[git-reset-script]:: link:git-rev-parse.html[git-rev-parse]:: git-rev-parse. -link:git-revert-script.html[git-revert-script]:: - git-revert-script. - -link:git-sh-setup-script.html[git-sh-setup-script]:: - git-sh-setup-script. - link:git-show-rev-cache.html[git-show-rev-cache]:: git-show-rev-cache. link:git-stripspace.html[git-stripspace]:: git-stripspace. -link:git-verify-tag-script.html[git-verify-tag-script]:: - git-verify-tag-script. - link:gitk.html[gitk]:: gitk. -- cgit v1.2.3 From 7311d9f10476f9b478348dab597bcc3d8736f091 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 26 Aug 2005 22:35:45 -0700 Subject: Add how-to on using update-hook. Signed-off-by: Junio C Hamano --- Documentation/howto/rebuild-from-update-hook.txt | 83 ++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 Documentation/howto/rebuild-from-update-hook.txt (limited to 'Documentation') diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.txt new file mode 100644 index 0000000000..ebd025db85 --- /dev/null +++ b/Documentation/howto/rebuild-from-update-hook.txt @@ -0,0 +1,83 @@ +Subject: [HOWTO] Using post-update hook +Message-ID: <7vy86o6usx.fsf@assigned-by-dhcp.cox.net> +From: Junio C Hamano +Date: Fri, 26 Aug 2005 18:19:10 -0700 +Abstract: In this how-to article, JC talks about how he + uses the post-update hook to automate git documentation page + shown at http://www.kernel.org/pub/software/scm/git/docs/. + +The pages under http://www.kernel.org/pub/software/scm/git/docs/ +are built from Documentation/ directory of the git.git project +and needed to be kept up-to-date. The www.kernel.org/ servers +are mirrored and I was told that the origin of the mirror is on +the machine master.kernel.org, on which I was given an account +when I took over git maintainership from Linus. + +The directories relevant to this how-to are these two: + + /pub/scm/git/git.git/ The public git repository. + /pub/software/scm/git/docs/ The HTML documentation page. + +So I made a repository to generate the documentation under my +home directory over there. + + $ cd + $ mkdir doc-git && cd doc-git + $ git clone /pub/scm/git/git.git/ docgen + +What needs to happen is to update the $HOME/doc-git/docgen/ +working tree, build HTML docs there and install the result in +/pub/software/scm/git/docs/ directory. So I wrote a little +script: + + $ cat >dododoc.sh <<\EOF + #!/bin/sh + cd $HOME/doc-git/docgen || exit + + unset GIT_DIR + + git pull /pub/scm/git/git.git/ master && + cd Documentation && + make install-webdoc + EOF + +Initially I used to run this by hand whenever I push into the +public git repository. Then I did a cron job that ran twice a +day. The current round uses the post-update hook mechanism, +like this: + + $ cat >/pub/scm/git/git.git/hooks/post-update <<\EOF + #!/bin/sh + # + # An example hook script to prepare a packed repository for use over + # dumb transports. + # + # To enable this hook, make this file executable by "chmod +x post-update". + + case " $* " in + *' refs/heads/master '*) + echo $HOME/doc-git/dododoc.sh | at now + ;; + esac + exec git-update-server-info + EOF + $ chmod +x /pub/scm/git/git.git/hooks/post-update + +There are three things worth mentioning: + + - The update-hook is run after the repository accepts a "git + push", under my user privilege. It is given the full names + of refs that have been updated as arguments. My post-update + runs the dododoc.sh script only when the master head is + updated. + + - When update-hook is run, GIT_DIR is set to '.' by the calling + receive-pack. This is inherited by the dododoc.sh run via + the "at" command, and needs to be unset; otherwise, "git + pull" it does into $HOME/doc-git/docgen/ repository would not + work correctly. + + - This is still crude and does not protect against simultaneous + make invocations stomping on each other. I would need to add + some locking mechanism for this. + -- cgit v1.2.3