Merge branch 'lt/request-pull'

Discard the accumulated "heuristics" to guess from which branch the
result wants to be pulled from and make sure what the end user
specified is not second-guessed by "git request-pull", to avoid
mistakes.

* lt/request-pull:
  request-pull: documentation updates
  request-pull: resurrect "pretty refname" feature
  request-pull: test updates
  request-pull: pick up tag message as before
  request-pull: allow "local:remote" to specify names on both ends
  request-pull: more strictly match local/remote branches

1 files changed, 49 insertions, 6 deletions

diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt
index b99681ce85..283577b0b6 100644
--- a/Documentation/git-request-pull.txt
+++ b/Documentation/git-request-pull.txt
@@ -13,22 +13,65 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Summarizes the changes between two commits to the standard output, and includes
-the given URL in the generated summary.
+Generate a request asking your upstream project to pull changes into
+their tree.  The request, printed to the standard output, summarizes
+the changes and indicates from where they can be pulled.
+
+The upstream project is expected to have the commit named by
+`<start>` and the output asks it to integrate the changes you made
+since that commit, up to the commit named by `<end>`, by visiting
+the repository named by `<url>`.
+
 
 OPTIONS
 -------
 -p::
-	Show patch text
+	Include patch text in the output.
 
 <start>::
-	Commit to start at.
+	Commit to start at.  This names a commit that is already in
+	the upstream history.
 
 <url>::
-	URL to include in the summary.
+	The repository URL to be pulled from.
 
 <end>::
-	Commit to end at; defaults to HEAD.
+	Commit to end at (defaults to HEAD).  This names the commit
+	at the tip of the history you are asking to be pulled.
++
+When the repository named by `<url>` has the commit at a tip of a
+ref that is different from the ref you have locally, you can use the
+`<local>:<remote>` syntax, to have its local name, a colon `:`, and
+its remote name.
+
+
+EXAMPLE
+-------
+
+Imagine that you built your work on your `master` branch on top of
+the `v1.0` release, and want it to be integrated to the project.
+First you push that change to your public repository for others to
+see:
+
+	git push https://git.ko.xz/project master
+
+Then, you run this command:
+
+	git request-pull v1.0 https://git.ko.xz/project master
+
+which will produce a request to the upstream, summarizing the
+changes between the `v1.0` release and your `master`, to pull it
+from your public repository.
+
+If you pushed your change to a branch whose name is different from
+the one you have locally, e.g.
+
+	git push https://git.ko.xz/project master:for-linus
+
+then you can ask that to be pulled with
+
+	git request-pull v1.0 https://git.ko.xz/project master:for-linus
+
 
 GIT
 ---