diff options
Diffstat (limited to 'third_party/git/Documentation/howto/using-signed-tag-in-pull-request.txt')
| -rw-r--r-- | third_party/git/Documentation/howto/using-signed-tag-in-pull-request.txt | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/third_party/git/Documentation/howto/using-signed-tag-in-pull-request.txt b/third_party/git/Documentation/howto/using-signed-tag-in-pull-request.txt deleted file mode 100644 index bbf040eda8..0000000000 --- a/third_party/git/Documentation/howto/using-signed-tag-in-pull-request.txt +++ /dev/null @@ -1,217 +0,0 @@ -From: Junio C Hamano <gitster@pobox.com> -Date: Tue, 17 Jan 2011 13:00:00 -0800 -Subject: Using signed tag in pull requests -Abstract: Beginning v1.7.9, a contributor can push a signed tag to her - publishing repository and ask her integrator to pull it. This assures the - integrator that the pulled history is authentic and allows others to - later validate it. -Content-type: text/asciidoc - -How to use a signed tag in pull requests -======================================== - -A typical distributed workflow using Git is for a contributor to fork a -project, build on it, publish the result to her public repository, and ask -the "upstream" person (often the owner of the project where she forked -from) to pull from her public repository. Requesting such a "pull" is made -easy by the `git request-pull` command. - -Earlier, a typical pull request may have started like this: - ------------- - The following changes since commit 406da78032179...: - - Froboz 3.2 (2011-09-30 14:20:57 -0700) - - are available in the Git repository at: - - example.com:/git/froboz.git for-xyzzy ------------- - -followed by a shortlog of the changes and a diffstat. - -The request was for a branch name (e.g. `for-xyzzy`) in the public -repository of the contributor, and even though it stated where the -contributor forked her work from, the message did not say anything about -the commit to expect at the tip of the for-xyzzy branch. If the site that -hosts the public repository of the contributor cannot be fully trusted, it -was unnecessarily hard to make sure what was pulled by the integrator was -genuinely what the contributor had produced for the project. Also there -was no easy way for third-party auditors to later verify the resulting -history. - -Starting from Git release v1.7.9, a contributor can add a signed tag to -the commit at the tip of the history and ask the integrator to pull that -signed tag. When the integrator runs `git pull`, the signed tag is -automatically verified to assure that the history is not tampered with. -In addition, the resulting merge commit records the content of the signed -tag, so that other people can verify that the branch merged by the -integrator was signed by the contributor, without fetching the signed tag -used to validate the pull request separately and keeping it in the refs -namespace. - -This document describes the workflow between the contributor and the -integrator, using Git v1.7.9 or later. - - -A contributor or a lieutenant ------------------------------ - -After preparing her work to be pulled, the contributor uses `git tag -s` -to create a signed tag: - ------------- - $ git checkout work - $ ... "git pull" from sublieutenants, "git commit" your own work ... - $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work ------------- - -Note that this example uses the `-m` option to create a signed tag with -just a one-liner message, but this is for illustration purposes only. It -is advisable to compose a well-written explanation of what the topic does -to justify why it is worthwhile for the integrator to pull it, as this -message will eventually become part of the final history after the -integrator responds to the pull request (as we will see later). - -Then she pushes the tag out to her public repository: - ------------- - $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy ------------- - -There is no need to push the `work` branch or anything else. - -Note that the above command line used a plus sign at the beginning of -`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same -contributor may want to reuse a signed tag with the same name after the -previous pull request has already been responded to. - -The contributor then prepares a message to request a "pull": - ------------- - $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt ------------- - -The arguments are: - -. the version of the integrator's commit the contributor based her work on; -. the URL of the repository, to which the contributor has pushed what she - wants to get pulled; and -. the name of the tag the contributor wants to get pulled (earlier, she could - write only a branch name here). - -The resulting msg.txt file begins like so: - ------------- - The following changes since commit 406da78032179...: - - Froboz 3.2 (2011-09-30 14:20:57 -0700) - - are available in the Git repository at: - - example.com:/git/froboz.git tags/frotz-for-xyzzy - - for you to fetch changes up to 703f05ad5835c...: - - Add tests and documentation for frotz (2011-12-02 10:02:52 -0800) - - ----------------------------------------------- - Completed frotz feature - ----------------------------------------------- ------------- - -followed by a shortlog of the changes and a diffstat. Comparing this with -the earlier illustration of the output from the traditional `git request-pull` -command, the reader should notice that: - -. The tip commit to expect is shown to the integrator; and -. The signed tag message is shown prominently between the dashed lines - before the shortlog. - -The latter is why the contributor would want to justify why pulling her -work is worthwhile when creating the signed tag. The contributor then -opens her favorite MUA, reads msg.txt, edits and sends it to her upstream -integrator. - - -Integrator ----------- - -After receiving such a pull request message, the integrator fetches and -integrates the tag named in the request, with: - ------------- - $ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy ------------- - -This operation will always open an editor to allow the integrator to fine -tune the commit log message when merging a signed tag. Also, pulling a -signed tag will always create a merge commit even when the integrator does -not have any new commit since the contributor's work forked (i.e. 'fast -forward'), so that the integrator can properly explain what the merge is -about and why it was made. - -In the editor, the integrator will see something like this: - ------------- - Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ - - Completed frotz feature - # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB - # gpg: Good signature from "Con Tributor <nitfol@example.com>" ------------- - -Notice that the message recorded in the signed tag "Completed frotz -feature" appears here, and again that is why it is important for the -contributor to explain her work well when creating the signed tag. - -As usual, the lines commented with `#` are stripped out. The resulting -commit records the signed tag used for this validation in a hidden field -so that it can later be used by others to audit the history. There is no -need for the integrator to keep a separate copy of the tag in his -repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the -above example), and there is no need to publish the tag to his public -repository, either. - -After the integrator responds to the pull request and her work becomes -part of the permanent history, the contributor can remove the tag from -her public repository, if she chooses, in order to keep the tag namespace -of her public repository clean, with: - ------------- - $ git push example.com:/git/froboz.git :frotz-for-xyzzy ------------- - - -Auditors --------- - -The `--show-signature` option can be given to `git log` or `git show` and -shows the verification status of the embedded signed tag in merge commits -created when the integrator responded to a pull request of a signed tag. - -A typical output from `git show --show-signature` may look like this: - ------------- - $ git show --show-signature - commit 02306ef6a3498a39118aef9df7975bdb50091585 - merged tag 'frotz-for-xyzzy' - gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB - gpg: Good signature from "Con Tributor <nitfol@example.com>" - Merge: 406da78 703f05a - Author: Inte Grator <xyzzy@example.com> - Date: Tue Jan 17 13:49:41 2012 -0800 - - Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ - - Completed frotz feature - - * tag 'frotz-for-xyzzy' (100 commits) - Add tests and documentation for frotz - ... ------------- - -There is no need for the auditor to explicitly fetch the contributor's -signature, or to even be aware of what tag(s) the contributor and integrator -used to communicate the signature. All the required information is recorded -as part of the merge commit. |