{"thread":{"id":"29387","subject":"Using signed tag in pull requests","startedAt":"2012-01-17T22:53:01Z","lastAt":"2012-01-18T22:35:04Z","messageCount":10,"participants":["Junio C Hamano","Andrew Ardill","Marc Branchaud"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"182703","messageId":"7vehuyosaa.fsf@alter.siamese.dyndns.org","threadId":"29387","inReplyTo":null,"subject":"Using signed tag in pull requests","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-17T22:53:01Z","receivedAt":"2012-01-17T22:53:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"This document will appear in Documentation/howto of Git release v1.7.9; I\nam sending it out for an early review.\n\nThanks.\n\n-- >8 --\nUsing signed tag in pull requests\n=================================\n\nA typical distributed workflow using Git is for a contributor to fork a\nproject, build on it, publish the result to her public repository, and ask\nthe \"upstream\" person (often the owner of the project where she forked\nfrom) to pull from her public repository. Requesting such a \"pull\" is made\neasy by the `git request-pull` command.\n\nEarlier, a typical pull request may have started like this:\n\n------------\n The following changes since commit 406da78032179...:\n\n   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n\n are available in the git repository at:\n\n   example.com:/git/froboz.git for-xyzzy\n------------\n\nfollowed by a shortlog of the changes and a diffstat.\n\nThe request was for a branch name (e.g. `for-xyzzy`) in the public\nrepository of the contributor, and even though it stated where the\ncontributor forked her work from, the message did not say anything about\nthe commit to expect at the tip of the for-xyzzy branch. If the site that\nhosts the public repository of the contributor cannot be fully trusted, it\nwas unnecessarily hard to make sure what was pulled by the integrator was\ngenuinely what the contributor had produced for the project. Also there\nwas no easy way for third-party auditors to later verify the resulting\nhistory.\n\nStarting from Git release v1.7.9, a contributor can add a signed tag to\nthe commit at the tip of the history and ask the integrator to pull that\nsigned tag. When the integrator runs `git pull`, the signed tag is\nautomatically verified to assure that the history is not tampered with.\nIn addition, the resulting merge commit records the content of the signed\ntag, so that other people can verify that the branch merged by the\ncontributor was signed by the contributor, without fetching the signed tag\nused to validate the pull request separately and keeping it in the refs\nnamespace.\n\nThis document describes the workflow between the contributor and the\nintegrator, using Git v1.7.9 or later.\n\n\nA contributor or a lieutenant\n-----------------------------\n\nAfter preparing her work to be pulled, the contributor uses `git tag -s`\nto create a signed tag [*1*]:\n\n------------\n $ git checkout work\n $ ... \"git pull\" from sublieutenants, \"git commit\" your own work ...\n $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n------------\n\nand pushes the tag out to her publishing repository [*2*]. There is no\nneed to push the `work` branch or anything else:\n\n------------\n $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n------------\n\nThen the contributor prepares a message to request a \"pull\":\n\n------------\n $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt\n------------\n\nThe arguments are:\n\n. the version of the integrator's commit the contributor based her work on;\n. the URL of the repository, to which the contributor has pushed what she\n  wants to get pulled; and\n. the name of the tag the contributor wants to get pulled (earlier, she could\n  write only a branch name here).\n\nThe resulting msg.txt file begins like so:\n\n------------\n The following changes since commit 406da78032179...:\n\n   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n\n are available in the git repository at:\n\n   example.com:/git/froboz.git frotz-for-xyzzy\n\n for you to fetch changes up to 703f05ad5835c...:\n\n   Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)\n\n -----------------------------------------------\n Completed frotz feature\n -----------------------------------------------\n------------\n\nfollowed by a shortlog of the changes and a diffstat.  Comparing this with\nthe earlier illustration of the output from the traditional `git request-pull`\ncommand, the reader should notice that:\n\n. The tip commit to expect is shown to the integrator; and\n. The signed tag message is shown prominently between the dashed lines\n  before the shortlog.\n\nThe latter is why the contributor would want to justify why pulling her\nwork is worthwhile when creating the signed tag.  The contributor then\nopens her favorite MUA, reads msg.txt, edits and sends it to her upstream\nintegrator.\n\n\nIntegrator\n----------\n\nAfter receiving such a pull request message, the integrator fetches and\nintegrates the tag named in the request, with:\n\n------------\n $ git pull example.com:/git/froboz.git/ frotz-for-xyzzy\n------------\n\nThis operation will always open an editor to allow the integrator to fine\ntune the commit log message when merging a signed tag.  Also, pulling a\nsigned tag will always create a merge commit even when the integrator does\nnot have any new commits since the contributor's work forked (i.e. 'fast\nforward'), so that the integrator can properly explain what the merge is\nabout and why it was made.\n\nIn the editor, the integrator will see something like this:\n\n------------\n Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/\n\n Completed frotz feature\n # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB\n # gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n------------\n\nprovided if the signature in the signed tag verifies correctly. Notice\nthat the message recorded in the signed tag \"Completed frotz feature\"\nappears here, and again that is why it is important for the contributor\nto explain her work well when creating the signed tag.\n\nAs usual, the lines commented with `#` are stripped out. The resulting\ncommit records the signed tag used for this validation in a hidden field\nso that it can later be used by others to audit the history. There is no\nneed for the integrator to keep a separate copy of the tag in his\nrepository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above\nexample), and there is no need to publish the tag to his public\nrepository, either.\n\nAfter the integrator responds to the pull request and her work becomes\npart of the permanent history, the contributor can remove the tag from the\npublishing repository, if she chooses, in order to keep the tag namespace\nof her public repository clean, with:\n\n------------\n $ git push example.com:/git/froboz.git :frotz-for-xyzzy\n------------\n\n\nAuditors\n--------\n\nThe `--show-signature` option can be given to `git log` or `git show` and\nshows the verification status of the embedded signed tag in merge commits\ncreated when the integrator responded to a pull request of a signed tag.\n\nA typical output from `git show --show-signature` may look like this:\n\n------------\n $ git show --show-signature\n commit 02306ef6a3498a39118aef9df7975bdb50091585\n merged tag 'frotz-for-xyzzy'\n gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB\n gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n Merge: 406da78 703f05a\n Author: Inte Grator <xyzzy@example.com>\n Date:   Tue Jan 17 13:49:41 2012 -0800\n\n     Merge tag 'frotz-for-xyzzy'\n\n     Completed frotz feature\n\n     * tag 'frotz-for-xyzzy' (100 commits)\n       Add tests and documentation for frotz\n       ...\n------------\n\nThere is no need to fetch and keep a signed tag like `frotz-for-xyzzy`\nthat is used for frequent \"pull\" exchange in the long term just for such\nauditing purposes, as the signature is recorded as part of the merge\ncommit.\n\n\nFootnotes\n---------\n\n*1* This example uses the `-m` option to create a signed tag with just a\nsingle liner message, but this is for illustration purposes only. It is\nadvisable to compose a well-written explanation of what the topic does to\njustify why it is worthwhile for the integrator to pull it, as this\nmessage will eventually become part of the final history after the\nintegrator responds to the pull request.\n\n*2* The example uses plus at the beginning of `+frotz-for-xyzzy` to allow\nforcing the update of a tag, as the same contributor may want to reuse a\nsigned tag with the same name after the previous pull request has already\nbeen responded to.\n"},{"id":"182705","messageId":"7v62g9q55f.fsf@alter.siamese.dyndns.org","threadId":"29387","inReplyTo":"7vehuyosaa.fsf@alter.siamese.dyndns.org","subject":"[PATCH] pulling signed tag: add howto document","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-17T23:29:48Z","receivedAt":"2012-01-17T23:29:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"This time in a proper patch format...\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n * We may want to update Documentation/Makefile in such a way that we\n   do not have to manually maintain a subset of howto/ files that need to\n   be added to SP_ARTICLES list (i.e. asciidoc formatted). They are all\n   marked with \"Content-type: text/asciidoc\" so a trivial $(shell grep -l) \n   might be all it takes. Hint, hint...\n\n Documentation/Makefile                             |    5 +-\n .../howto/using-signed-tag-in-pull-request.txt     |  221 ++++++++++++++++++++\n 2 files changed, 225 insertions(+), 1 deletions(-)\n create mode 100644 Documentation/howto/using-signed-tag-in-pull-request.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 116f175..d40e211 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -20,7 +20,10 @@ ARTICLES += everyday\n ARTICLES += git-tools\n ARTICLES += git-bisect-lk2009\n # with their own formatting rules.\n-SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual\n+SP_ARTICLES = user-manual\n+SP_ARTICLES += howto/revert-branch-rebase\n+SP_ARTICLES += howto/using-merge-subtree\n+SP_ARTICLES += howto/using-signed-tag-in-pull-request\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n SP_ARTICLES += technical/api-index\ndiff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt\nnew file mode 100644\nindex 0000000..a057f9a\n--- /dev/null\n+++ b/Documentation/howto/using-signed-tag-in-pull-request.txt\n@@ -0,0 +1,221 @@\n+From: Junio C Hamano <gitster@pobox.com>\n+Date: Tue, 17 Jan 2011 13:00:00 -0800\n+Subject: Using signed tag in pull requests\n+Abstract: Beginning v1.7.9, a contributor can push a signed tag to her\n+ publishing repository and ask her integrator to pull it. This assures the\n+ integrator that the pulled history is authentic and allows others to\n+ later validate it.\n+Content-type: text/asciidoc\n+\n+Using signed tag in pull requests\n+=================================\n+\n+A typical distributed workflow using Git is for a contributor to fork a\n+project, build on it, publish the result to her public repository, and ask\n+the \"upstream\" person (often the owner of the project where she forked\n+from) to pull from her public repository. Requesting such a \"pull\" is made\n+easy by the `git request-pull` command.\n+\n+Earlier, a typical pull request may have started like this:\n+\n+------------\n+ The following changes since commit 406da78032179...:\n+\n+   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n+\n+ are available in the git repository at:\n+\n+   example.com:/git/froboz.git for-xyzzy\n+------------\n+\n+followed by a shortlog of the changes and a diffstat.\n+\n+The request was for a branch name (e.g. `for-xyzzy`) in the public\n+repository of the contributor, and even though it stated where the\n+contributor forked her work from, the message did not say anything about\n+the commit to expect at the tip of the for-xyzzy branch. If the site that\n+hosts the public repository of the contributor cannot be fully trusted, it\n+was unnecessarily hard to make sure what was pulled by the integrator was\n+genuinely what the contributor had produced for the project. Also there\n+was no easy way for third-party auditors to later verify the resulting\n+history.\n+\n+Starting from Git release v1.7.9, a contributor can add a signed tag to\n+the commit at the tip of the history and ask the integrator to pull that\n+signed tag. When the integrator runs `git pull`, the signed tag is\n+automatically verified to assure that the history is not tampered with.\n+In addition, the resulting merge commit records the content of the signed\n+tag, so that other people can verify that the branch merged by the\n+contributor was signed by the contributor, without fetching the signed tag\n+used to validate the pull request separately and keeping it in the refs\n+namespace.\n+\n+This document describes the workflow between the contributor and the\n+integrator, using Git v1.7.9 or later.\n+\n+\n+A contributor or a lieutenant\n+-----------------------------\n+\n+After preparing her work to be pulled, the contributor uses `git tag -s`\n+to create a signed tag [*1*]:\n+\n+------------\n+ $ git checkout work\n+ $ ... \"git pull\" from sublieutenants, \"git commit\" your own work ...\n+ $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n+------------\n+\n+and pushes the tag out to her publishing repository [*2*]. There is no\n+need to push the `work` branch or anything else:\n+\n+------------\n+ $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n+------------\n+\n+Then the contributor prepares a message to request a \"pull\":\n+\n+------------\n+ $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt\n+------------\n+\n+The arguments are:\n+\n+. the version of the integrator's commit the contributor based her work on;\n+. the URL of the repository, to which the contributor has pushed what she\n+  wants to get pulled; and\n+. the name of the tag the contributor wants to get pulled (earlier, she could\n+  write only a branch name here).\n+\n+The resulting msg.txt file begins like so:\n+\n+------------\n+ The following changes since commit 406da78032179...:\n+\n+   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n+\n+ are available in the git repository at:\n+\n+   example.com:/git/froboz.git frotz-for-xyzzy\n+\n+ for you to fetch changes up to 703f05ad5835c...:\n+\n+   Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)\n+\n+ -----------------------------------------------\n+ Completed frotz feature\n+ -----------------------------------------------\n+------------\n+\n+followed by a shortlog of the changes and a diffstat.  Comparing this with\n+the earlier illustration of the output from the traditional `git request-pull`\n+command, the reader should notice that:\n+\n+. The tip commit to expect is shown to the integrator; and\n+. The signed tag message is shown prominently between the dashed lines\n+  before the shortlog.\n+\n+The latter is why the contributor would want to justify why pulling her\n+work is worthwhile when creating the signed tag.  The contributor then\n+opens her favorite MUA, reads msg.txt, edits and sends it to her upstream\n+integrator.\n+\n+\n+Integrator\n+----------\n+\n+After receiving such a pull request message, the integrator fetches and\n+integrates the tag named in the request, with:\n+\n+------------\n+ $ git pull example.com:/git/froboz.git/ frotz-for-xyzzy\n+------------\n+\n+This operation will always open an editor to allow the integrator to fine\n+tune the commit log message when merging a signed tag.  Also, pulling a\n+signed tag will always create a merge commit even when the integrator does\n+not have any new commits since the contributor's work forked (i.e. 'fast\n+forward'), so that the integrator can properly explain what the merge is\n+about and why it was made.\n+\n+In the editor, the integrator will see something like this:\n+\n+------------\n+ Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/\n+\n+ Completed frotz feature\n+ # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB\n+ # gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n+------------\n+\n+provided if the signature in the signed tag verifies correctly. Notice\n+that the message recorded in the signed tag \"Completed frotz feature\"\n+appears here, and again that is why it is important for the contributor\n+to explain her work well when creating the signed tag.\n+\n+As usual, the lines commented with `#` are stripped out. The resulting\n+commit records the signed tag used for this validation in a hidden field\n+so that it can later be used by others to audit the history. There is no\n+need for the integrator to keep a separate copy of the tag in his\n+repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above\n+example), and there is no need to publish the tag to his public\n+repository, either.\n+\n+After the integrator responds to the pull request and her work becomes\n+part of the permanent history, the contributor can remove the tag from the\n+publishing repository, if she chooses, in order to keep the tag namespace\n+of her public repository clean, with:\n+\n+------------\n+ $ git push example.com:/git/froboz.git :frotz-for-xyzzy\n+------------\n+\n+\n+Auditors\n+--------\n+\n+The `--show-signature` option can be given to `git log` or `git show` and\n+shows the verification status of the embedded signed tag in merge commits\n+created when the integrator responded to a pull request of a signed tag.\n+\n+A typical output from `git show --show-signature` may look like this:\n+\n+------------\n+ $ git show --show-signature\n+ commit 02306ef6a3498a39118aef9df7975bdb50091585\n+ merged tag 'frotz-for-xyzzy'\n+ gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB\n+ gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n+ Merge: 406da78 703f05a\n+ Author: Inte Grator <xyzzy@example.com>\n+ Date:   Tue Jan 17 13:49:41 2012 -0800\n+\n+     Merge tag 'frotz-for-xyzzy'\n+\n+     Completed frotz feature\n+\n+     * tag 'frotz-for-xyzzy' (100 commits)\n+       Add tests and documentation for frotz\n+       ...\n+------------\n+\n+There is no need to fetch and keep a signed tag like `frotz-for-xyzzy`\n+that is used for frequent \"pull\" exchange in the long term just for such\n+auditing purposes, as the signature is recorded as part of the merge\n+commit.\n+\n+\n+Footnotes\n+---------\n+\n+*1* This example uses the `-m` option to create a signed tag with just a\n+single liner message, but this is for illustration purposes only. It is\n+advisable to compose a well-written explanation of what the topic does to\n+justify why it is worthwhile for the integrator to pull it, as this\n+message will eventually become part of the final history after the\n+integrator responds to the pull request.\n+\n+*2* The example uses plus at the beginning of `+frotz-for-xyzzy` to allow\n+forcing the update of a tag, as the same contributor may want to reuse a\n+signed tag with the same name after the previous pull request has already\n+been responded to.\n-- \n1.7.9.rc1.32.g0f516\n"},{"id":"182709","messageId":"CAH5451nSMcJ50fu2qtMkw4zPpx-Kg-k-jqCcpryu+pkC8JX8rw@mail.gmail.com","threadId":"29387","inReplyTo":"7vehuyosaa.fsf@alter.siamese.dyndns.org","subject":"Re: Using signed tag in pull requests","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-01-18T01:07:18Z","receivedAt":"2012-01-18T01:07:18Z","isPatch":false,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"Looks pretty good Junio, though one of the lines was a bit confusing:\n\nOn 18 January 2012 09:53, Junio C Hamano <gitster@pobox.com> wrote:\n\n> Starting from Git release v1.7.9, a contributor can add a signed tag to\n> the commit at the tip of the history and ask the integrator to pull that\n> signed tag. When the integrator runs `git pull`, the signed tag is\n> automatically verified to assure that the history is not tampered with.\n> In addition, the resulting merge commit records the content of the signed\n> tag, so that other people can verify that the branch merged by the\n> contributor was signed by the contributor, without fetching the signed tag\n\nI think you mean to say 'the branch merged by the integrator was signed\nby the contributor'. If you are talking about two separate contributors, or\nthe same contributor merging one of her own branches, the wording can\nlikely be improved.\n\n> used to validate the pull request separately and keeping it in the refs\n> namespace.\n\nOverall it was easy to understand and makes the whole workflow quite clear.\n\nRegards,\nAndrew Ardill\n"},{"id":"182713","messageId":"7vwr8pok7w.fsf@alter.siamese.dyndns.org","threadId":"29387","inReplyTo":"CAH5451nSMcJ50fu2qtMkw4zPpx-Kg-k-jqCcpryu+pkC8JX8rw@mail.gmail.com","subject":"Re: Using signed tag in pull requests","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-18T01:47:15Z","receivedAt":"2012-01-18T01:47:15Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andrew Ardill <andrew.ardill@gmail.com> writes:\n\n>> Starting from Git release v1.7.9, a contributor can add a signed tag to\n>> the commit at the tip of the history and ask the integrator to pull that\n>> signed tag. When the integrator runs `git pull`, the signed tag is\n>> automatically verified to assure that the history is not tampered with.\n>> In addition, the resulting merge commit records the content of the signed\n>> tag, so that other people can verify that the branch merged by the\n>> contributor was signed by the contributor, without fetching the signed tag\n>\n> I think you mean to say 'the branch merged by the integrator was signed\n> by the contributor'.\n\nDefinitely. I'll update my local copy.\n\nThanks for spotting this.\n"},{"id":"182716","messageId":"CAH5451mz7NpDyL9O708siBdgSC7eXZi=VWk5qd2Ghm0PmWZ9NQ@mail.gmail.com","threadId":"29387","inReplyTo":"7vwr8pok7w.fsf@alter.siamese.dyndns.org","subject":"Re: Using signed tag in pull requests","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-01-18T02:34:14Z","receivedAt":"2012-01-18T02:34:14Z","isPatch":false,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"On 18 January 2012 12:47, Junio C Hamano <gitster@pobox.com> wrote:\n> Andrew Ardill <andrew.ardill@gmail.com> writes:\n>\n>>> Starting from Git release v1.7.9, a contributor can add a signed tag to\n>>> the commit at the tip of the history and ask the integrator to pull that\n>>> signed tag. When the integrator runs `git pull`, the signed tag is\n>>> automatically verified to assure that the history is not tampered with.\n>>> In addition, the resulting merge commit records the content of the signed\n>>> tag, so that other people can verify that the branch merged by the\n>>> contributor was signed by the contributor, without fetching the signed tag\n>>\n>> I think you mean to say 'the branch merged by the integrator was signed\n>> by the contributor'.\n>\n> Definitely. I'll update my local copy.\n>\n> Thanks for spotting this.\n\nNo worries. That's the whole point right? :D\n"},{"id":"182726","messageId":"4F16E228.5050203@xiplink.com","threadId":"29387","inReplyTo":"7v62g9q55f.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] pulling signed tag: add howto document","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2012-01-18T15:15:52Z","receivedAt":"2012-01-18T15:15:52Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Overall a very understandable doc!  I've just a few linguistic comments:\n\nOn 12-01-17 06:29 PM, Junio C Hamano wrote:\n> This time in a proper patch format...\n> \n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n>  * We may want to update Documentation/Makefile in such a way that we\n>    do not have to manually maintain a subset of howto/ files that need to\n>    be added to SP_ARTICLES list (i.e. asciidoc formatted). They are all\n>    marked with \"Content-type: text/asciidoc\" so a trivial $(shell grep -l) \n>    might be all it takes. Hint, hint...\n> \n>  Documentation/Makefile                             |    5 +-\n>  .../howto/using-signed-tag-in-pull-request.txt     |  221 ++++++++++++++++++++\n>  2 files changed, 225 insertions(+), 1 deletions(-)\n>  create mode 100644 Documentation/howto/using-signed-tag-in-pull-request.txt\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 116f175..d40e211 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -20,7 +20,10 @@ ARTICLES += everyday\n>  ARTICLES += git-tools\n>  ARTICLES += git-bisect-lk2009\n>  # with their own formatting rules.\n> -SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual\n> +SP_ARTICLES = user-manual\n> +SP_ARTICLES += howto/revert-branch-rebase\n> +SP_ARTICLES += howto/using-merge-subtree\n> +SP_ARTICLES += howto/using-signed-tag-in-pull-request\n>  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n>  SP_ARTICLES += $(API_DOCS)\n>  SP_ARTICLES += technical/api-index\n> diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt\n> new file mode 100644\n> index 0000000..a057f9a\n> --- /dev/null\n> +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt\n> @@ -0,0 +1,221 @@\n> +From: Junio C Hamano <gitster@pobox.com>\n> +Date: Tue, 17 Jan 2011 13:00:00 -0800\n> +Subject: Using signed tag in pull requests\n> +Abstract: Beginning v1.7.9, a contributor can push a signed tag to her\n> + publishing repository and ask her integrator to pull it. This assures the\n> + integrator that the pulled history is authentic and allows others to\n> + later validate it.\n> +Content-type: text/asciidoc\n> +\n> +Using signed tag in pull requests\n> +=================================\n> +\n> +A typical distributed workflow using Git is for a contributor to fork a\n> +project, build on it, publish the result to her public repository, and ask\n> +the \"upstream\" person (often the owner of the project where she forked\n> +from) to pull from her public repository. Requesting such a \"pull\" is made\n> +easy by the `git request-pull` command.\n> +\n> +Earlier, a typical pull request may have started like this:\n> +\n> +------------\n> + The following changes since commit 406da78032179...:\n> +\n> +   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n> +\n> + are available in the git repository at:\n> +\n> +   example.com:/git/froboz.git for-xyzzy\n> +------------\n> +\n> +followed by a shortlog of the changes and a diffstat.\n> +\n> +The request was for a branch name (e.g. `for-xyzzy`) in the public\n> +repository of the contributor, and even though it stated where the\n> +contributor forked her work from, the message did not say anything about\n> +the commit to expect at the tip of the for-xyzzy branch. If the site that\n> +hosts the public repository of the contributor cannot be fully trusted, it\n> +was unnecessarily hard to make sure what was pulled by the integrator was\n> +genuinely what the contributor had produced for the project. Also there\n> +was no easy way for third-party auditors to later verify the resulting\n> +history.\n> +\n> +Starting from Git release v1.7.9, a contributor can add a signed tag to\n> +the commit at the tip of the history and ask the integrator to pull that\n> +signed tag. When the integrator runs `git pull`, the signed tag is\n> +automatically verified to assure that the history is not tampered with.\n> +In addition, the resulting merge commit records the content of the signed\n> +tag, so that other people can verify that the branch merged by the\n> +contributor was signed by the contributor, without fetching the signed tag\n> +used to validate the pull request separately and keeping it in the refs\n> +namespace.\n> +\n> +This document describes the workflow between the contributor and the\n> +integrator, using Git v1.7.9 or later.\n> +\n> +\n> +A contributor or a lieutenant\n> +-----------------------------\n> +\n> +After preparing her work to be pulled, the contributor uses `git tag -s`\n> +to create a signed tag [*1*]:\n\nGiven that the rest of the text refers to the gist of this footnote, I think\nit'd be better to put the note's text here instead of as a footnote.\n\n> +\n> +------------\n> + $ git checkout work\n> + $ ... \"git pull\" from sublieutenants, \"git commit\" your own work ...\n> + $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n> +------------\n> +\n> +and pushes the tag out to her publishing repository [*2*]. There is no\n\nThis footnote speaks of the example using a +, but the example does no such\nthing.\n\n> +need to push the `work` branch or anything else:\n> +\n> +------------\n> + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n> +------------\n> +\n> +Then the contributor prepares a message to request a \"pull\":\n> +\n> +------------\n> + $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt\n> +------------\n> +\n> +The arguments are:\n> +\n> +. the version of the integrator's commit the contributor based her work on;\n> +. the URL of the repository, to which the contributor has pushed what she\n> +  wants to get pulled; and\n> +. the name of the tag the contributor wants to get pulled (earlier, she could\n> +  write only a branch name here).\n> +\n> +The resulting msg.txt file begins like so:\n> +\n> +------------\n> + The following changes since commit 406da78032179...:\n> +\n> +   Froboz 3.2 (2011-09-30 14:20:57 -0700)\n> +\n> + are available in the git repository at:\n> +\n> +   example.com:/git/froboz.git frotz-for-xyzzy\n> +\n> + for you to fetch changes up to 703f05ad5835c...:\n> +\n> +   Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)\n> +\n> + -----------------------------------------------\n> + Completed frotz feature\n> + -----------------------------------------------\n> +------------\n> +\n> +followed by a shortlog of the changes and a diffstat.  Comparing this with\n> +the earlier illustration of the output from the traditional `git request-pull`\n> +command, the reader should notice that:\n> +\n> +. The tip commit to expect is shown to the integrator; and\n> +. The signed tag message is shown prominently between the dashed lines\n> +  before the shortlog.\n> +\n> +The latter is why the contributor would want to justify why pulling her\n> +work is worthwhile when creating the signed tag.  The contributor then\n> +opens her favorite MUA, reads msg.txt, edits and sends it to her upstream\n> +integrator.\n> +\n> +\n> +Integrator\n> +----------\n> +\n> +After receiving such a pull request message, the integrator fetches and\n> +integrates the tag named in the request, with:\n> +\n> +------------\n> + $ git pull example.com:/git/froboz.git/ frotz-for-xyzzy\n> +------------\n> +\n> +This operation will always open an editor to allow the integrator to fine\n> +tune the commit log message when merging a signed tag.  Also, pulling a\n> +signed tag will always create a merge commit even when the integrator does\n> +not have any new commits since the contributor's work forked (i.e. 'fast\n> +forward'), so that the integrator can properly explain what the merge is\n> +about and why it was made.\n> +\n> +In the editor, the integrator will see something like this:\n> +\n> +------------\n> + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/\n> +\n> + Completed frotz feature\n> + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB\n> + # gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n> +------------\n> +\n> +provided if the signature in the signed tag verifies correctly. Notice\n\ns/if //\n\n> +that the message recorded in the signed tag \"Completed frotz feature\"\n> +appears here, and again that is why it is important for the contributor\n> +to explain her work well when creating the signed tag.\n> +\n> +As usual, the lines commented with `#` are stripped out. The resulting\n> +commit records the signed tag used for this validation in a hidden field\n> +so that it can later be used by others to audit the history. There is no\n> +need for the integrator to keep a separate copy of the tag in his\n> +repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above\n\ns/list/list the/\n\n> +example), and there is no need to publish the tag to his public\n> +repository, either.\n> +\n> +After the integrator responds to the pull request and her work becomes\n> +part of the permanent history, the contributor can remove the tag from the\n> +publishing repository, if she chooses, in order to keep the tag namespace\n> +of her public repository clean, with:\n> +\n> +------------\n> + $ git push example.com:/git/froboz.git :frotz-for-xyzzy\n> +------------\n> +\n> +\n> +Auditors\n> +--------\n> +\n> +The `--show-signature` option can be given to `git log` or `git show` and\n> +shows the verification status of the embedded signed tag in merge commits\n> +created when the integrator responded to a pull request of a signed tag.\n> +\n> +A typical output from `git show --show-signature` may look like this:\n> +\n> +------------\n> + $ git show --show-signature\n> + commit 02306ef6a3498a39118aef9df7975bdb50091585\n> + merged tag 'frotz-for-xyzzy'\n> + gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB\n> + gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n> + Merge: 406da78 703f05a\n> + Author: Inte Grator <xyzzy@example.com>\n> + Date:   Tue Jan 17 13:49:41 2012 -0800\n> +\n> +     Merge tag 'frotz-for-xyzzy'\n> +\n> +     Completed frotz feature\n> +\n> +     * tag 'frotz-for-xyzzy' (100 commits)\n> +       Add tests and documentation for frotz\n> +       ...\n> +------------\n> +\n> +There is no need to fetch and keep a signed tag like `frotz-for-xyzzy`\n> +that is used for frequent \"pull\" exchange in the long term just for such\n> +auditing purposes, as the signature is recorded as part of the merge\n> +commit.\n\nI had trouble parsing this sentence.  I think part of the problem is that\nit's comparing the actual implementation to an earlier proposed design that\nwas rejected.  So it's trying to sell the reader on a feature of the\nimplemented design, but the reader doesn't care.\n\nHow about this instead:\n\nThere is no need for the auditor to explicitly fetch the contributor's\nsignature, or to even be aware of what tag(s) the contributor and integrator\nused to communicate the signature.  All the required information is recorded\nas part of the merge commit.\n\n> +\n> +\n> +Footnotes\n> +---------\n> +\n> +*1* This example uses the `-m` option to create a signed tag with just a\n> +single liner message, but this is for illustration purposes only. It is\n\ns/single liner/single-line/\n\n> +advisable to compose a well-written explanation of what the topic does to\n> +justify why it is worthwhile for the integrator to pull it, as this\n> +message will eventually become part of the final history after the\n> +integrator responds to the pull request.\n> +\n> +*2* The example uses plus at the beginning of `+frotz-for-xyzzy` to allow\n> +forcing the update of a tag, as the same contributor may want to reuse a\n> +signed tag with the same name after the previous pull request has already\n> +been responded to.\n\n\t\tM.\n"},{"id":"182739","messageId":"7v62g8n1tq.fsf@alter.siamese.dyndns.org","threadId":"29387","inReplyTo":"4F16E228.5050203@xiplink.com","subject":"Re: [PATCH] pulling signed tag: add howto document","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-18T21:22:09Z","receivedAt":"2012-01-18T21:22:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n>> +A contributor or a lieutenant\n>> +-----------------------------\n>> +\n>> +After preparing her work to be pulled, the contributor uses `git tag -s`\n>> +to create a signed tag [*1*]:\n>\n> Given that the rest of the text refers to the gist of this footnote, I think\n> it'd be better to put the note's text here instead of as a footnote.\n\nHmm, I'll try to see how well it reads after moving the text here. Thanks.\n\n>> +\n>> +------------\n>> + $ git checkout work\n>> + $ ... \"git pull\" from sublieutenants, \"git commit\" your own work ...\n>> + $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n>> +------------\n>> +\n>> +and pushes the tag out to her publishing repository [*2*]. There is no\n>\n> This footnote speaks of the example using a +, but the example does no such\n> thing.\n>\n>> +need to push the `work` branch or anything else:\n>> +\n>> +------------\n>> + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n>> +------------\n\nDo you not see the plus in front of +'frotz-for-xyzzy' above, or am I\nmissing something?\n\n>> +In the editor, the integrator will see something like this:\n>> +\n>> +------------\n>> + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/\n>> +\n>> + Completed frotz feature\n>> + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB\n>> + # gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n>> +------------\n>> +\n>> +provided if the signature in the signed tag verifies correctly. Notice\n>\n> s/if //\n\nNoted.\n\n>> +repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above\n>\n> s/list/list the/\n\nNoted.\n\n>> +There is no need to fetch and keep a signed tag like `frotz-for-xyzzy`\n>> +that is used for frequent \"pull\" exchange in the long term just for such\n>> +auditing purposes, as the signature is recorded as part of the merge\n>> +commit.\n>\n> I had trouble parsing this sentence.  I think part of the problem is that\n> it's comparing the actual implementation to an earlier proposed design that\n> was rejected.  So it's trying to sell the reader on a feature of the\n> implemented design, but the reader doesn't care.\n>\n> How about this instead:\n>\n> There is no need for the auditor to explicitly fetch the contributor's\n> signature, or to even be aware of what tag(s) the contributor and integrator\n> used to communicate the signature.  All the required information is recorded\n> as part of the merge commit.\n\nOk, that is much easier to read.\n\n>> +\n>> +\n>> +Footnotes\n>> +---------\n>> +\n>> +*1* This example uses the `-m` option to create a signed tag with just a\n>> +single liner message, but this is for illustration purposes only. It is\n>\n> s/single liner/single-line/\n\nNoted.\n\nThanks.\n"},{"id":"182740","messageId":"4F173C5D.7000802@xiplink.com","threadId":"29387","inReplyTo":"7v62g8n1tq.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] pulling signed tag: add howto document","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2012-01-18T21:40:45Z","receivedAt":"2012-01-18T21:40:45Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 12-01-18 04:22 PM, Junio C Hamano wrote:\n> Marc Branchaud <marcnarc@xiplink.com> writes:\n>>> +\n>>> +------------\n>>> + $ git checkout work\n>>> + $ ... \"git pull\" from sublieutenants, \"git commit\" your own work ...\n>>> + $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n>>> +------------\n>>> +\n>>> +and pushes the tag out to her publishing repository [*2*]. There is no\n>>\n>> This footnote speaks of the example using a +, but the example does no such\n>> thing.\n>>\n>>> +need to push the `work` branch or anything else:\n>>> +\n>>> +------------\n>>> + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n>>> +------------\n> \n> Do you not see the plus in front of +'frotz-for-xyzzy' above, or am I\n> missing something?\n\nOops, I was tripped up because the footnote is attached to a sentence that my\naddled mind associates with the previous \"git tag\" example.\n\nIt might be better to just move the footnote to the end of the next sentence.\n\n\t\tM.\n"},{"id":"182744","messageId":"7v1uqwmyt6.fsf@alter.siamese.dyndns.org","threadId":"29387","inReplyTo":"4F173C5D.7000802@xiplink.com","subject":"Re: [PATCH] pulling signed tag: add howto document","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-01-18T22:27:17Z","receivedAt":"2012-01-18T22:27:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n> It might be better to just move the footnote to the end of the next sentence.\n\nOk. How does this version look?  The highlights are:\n\n * remove footnotes and spell them out inline, like \"Note that...\"\n\n * \"a single liner\" -> \"a one-liner\"\n\n * \"publishing repository\" -> \"public repository\". I often use the former\n   when I want to differenciate a repository used to publish the work by a\n   single owner from a shared public repository, so technically the wording\n   could stay as-is, but I think it is clear that we mean publishing one\n   not a shared one from the context of this document.\n\n * Drop the attempt to say \"you would see these 'Good signature from...'\n   if and only if the signature verifies OK\" altogether. It is clear from\n   the example that the signature was good.\n\n * Replace the paragraph that explains there is no need to keep and\n   transfer signed tags for auditors with your version.\n\nThanks.\n\n .../howto/using-signed-tag-in-pull-request.txt     |   60 +++++++++----------\n 1 files changed, 28 insertions(+), 32 deletions(-)\n\ndiff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt\nindex efac088..a1351c5 100644\n--- a/Documentation/howto/using-signed-tag-in-pull-request.txt\n+++ b/Documentation/howto/using-signed-tag-in-pull-request.txt\n@@ -58,7 +58,7 @@ A contributor or a lieutenant\n -----------------------------\n \n After preparing her work to be pulled, the contributor uses `git tag -s`\n-to create a signed tag [*1*]:\n+to create a signed tag:\n \n ------------\n  $ git checkout work\n@@ -66,14 +66,27 @@ to create a signed tag [*1*]:\n  $ git tag -s -m \"Completed frotz feature\" frotz-for-xyzzy work\n ------------\n \n-and pushes the tag out to her publishing repository [*2*]. There is no\n-need to push the `work` branch or anything else:\n+Note that this example uses the `-m` option to create a signed tag with\n+just a one-liner message, but this is for illustration purposes only. It\n+is advisable to compose a well-written explanation of what the topic does\n+to justify why it is worthwhile for the integrator to pull it, as this\n+message will eventually become part of the final history after the\n+integrator responds to the pull request (as we will see later).\n+\n+Then she pushes the tag out to her public repository:\n \n ------------\n  $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy\n ------------\n \n-Then the contributor prepares a message to request a \"pull\":\n+There is no need to push the `work` branch or anything else.\n+\n+Note that the above command line used a plus sign at the beginning of\n+`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same\n+contributor may want to reuse a signed tag with the same name after the\n+previous pull request has already been responded to.\n+\n+The contributor then prepares a message to request a \"pull\":\n \n ------------\n  $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt\n@@ -148,22 +161,21 @@ In the editor, the integrator will see something like this:\n  # gpg: Good signature from \"Con Tributor <nitfol@example.com>\"\n ------------\n \n-provided if the signature in the signed tag verifies correctly. Notice\n-that the message recorded in the signed tag \"Completed frotz feature\"\n-appears here, and again that is why it is important for the contributor\n-to explain her work well when creating the signed tag.\n+Notice that the message recorded in the signed tag \"Completed frotz\n+feature\" appears here, and again that is why it is important for the\n+contributor to explain her work well when creating the signed tag.\n \n As usual, the lines commented with `#` are stripped out. The resulting\n commit records the signed tag used for this validation in a hidden field\n so that it can later be used by others to audit the history. There is no\n need for the integrator to keep a separate copy of the tag in his\n-repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above\n-example), and there is no need to publish the tag to his public\n+repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the\n+above example), and there is no need to publish the tag to his public\n repository, either.\n \n After the integrator responds to the pull request and her work becomes\n-part of the permanent history, the contributor can remove the tag from the\n-publishing repository, if she chooses, in order to keep the tag namespace\n+part of the permanent history, the contributor can remove the tag from\n+her public repository, if she chooses, in order to keep the tag namespace\n of her public repository clean, with:\n \n ------------\n@@ -199,23 +211,7 @@ A typical output from `git show --show-signature` may look like this:\n        ...\n ------------\n \n-There is no need to fetch and keep a signed tag like `frotz-for-xyzzy`\n-that is used for frequent \"pull\" exchange in the long term just for such\n-auditing purposes, as the signature is recorded as part of the merge\n-commit.\n-\n-\n-Footnotes\n----------\n-\n-*1* This example uses the `-m` option to create a signed tag with just a\n-single liner message, but this is for illustration purposes only. It is\n-advisable to compose a well-written explanation of what the topic does to\n-justify why it is worthwhile for the integrator to pull it, as this\n-message will eventually become part of the final history after the\n-integrator responds to the pull request.\n-\n-*2* The example uses plus at the beginning of `+frotz-for-xyzzy` to allow\n-forcing the update of a tag, as the same contributor may want to reuse a\n-signed tag with the same name after the previous pull request has already\n-been responded to.\n+There is no need for the auditor to explicitly fetch the contributor's\n+signature, or to even be aware of what tag(s) the contributor and integrator\n+used to communicate the signature.  All the required information is recorded\n+as part of the merge commit.\n"},{"id":"182745","messageId":"4F174918.7040604@xiplink.com","threadId":"29387","inReplyTo":"7v1uqwmyt6.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] pulling signed tag: add howto document","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2012-01-18T22:35:04Z","receivedAt":"2012-01-18T22:35:04Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 12-01-18 05:27 PM, Junio C Hamano wrote:\n> Marc Branchaud <marcnarc@xiplink.com> writes:\n> \n>> It might be better to just move the footnote to the end of the next sentence.\n> \n> Ok. How does this version look?  The highlights are:\n> \n>  * remove footnotes and spell them out inline, like \"Note that...\"\n> \n>  * \"a single liner\" -> \"a one-liner\"\n\nIMO \"one-liner\" should be \"one-line\", but toMAYto toMAHto...\n\nThe rest looks good.\n\n\t\tM.\n"}]}