Imported Upstream version 2.0.1

[platform/upstream/git.git] / Documentation / git-request-pull.txt

diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt
index b99681c..283577b 100644 (file)
--- 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
 ---