Prepare Git Pull Request Notes with git-request-pull

You will finish with a pull request message that names the changes to integrate, the repository to fetch them from, and the exact end commit. The command prints the request to standard output. It does not push your branch or change the repository.

Allow about ten minutes for a normal branch. You need Git 2.43.0 or a compatible Git installation, a local repository, a commit already known to the upstream project, and a public repository URL containing your work. The examples use the syntax documented by the installed Git 2.43.0 package.

1. Check the installed command

Run this from the repository that contains your work:

$ git --version
git version 2.43.0
$ git request-pull -h
usage: git request-pull [options] start url [end]

    -p                    show patch text as well

The command has three positional parts: start, the upstream commit where the requested range begins; url, the repository that others can pull from; and an optional end, the tip of your work. If you omit end, Git uses HEAD.

$ git status --short --branch
## feature/example...origin/main
$ git log --oneline --decorate -5
<recent commits appear here>

The status output is repository-specific. A clean working tree is not required by this command, but committing the work first makes the request reproducible and easier to review.

2. Identify the upstream starting commit

The start commit must already be in the upstream history. It is usually a release tag, a base branch tip, or the commit from which you created your topic branch. Do not use the first commit of your topic branch unless that is genuinely the commit the upstream project already has.

$ git show --no-patch --oneline v2.4.0
<the upstream release commit>
$ git merge-base --is-ancestor v2.4.0 HEAD
$ printf 'ancestor check: %s\n' "$?"
ancestor check: 0

A zero status from merge-base --is-ancestor confirms that the named release is an ancestor of your current tip. That check concerns your local history. It does not prove that the upstream maintainer has the same tag, so use a start name or object that the receiving project recognises.

If the check fails, stop and inspect the branch history. A pull request generated from the wrong base can describe unrelated changes or omit the changes you meant to send.

3. Put the committed work where it can be pulled

The request tells the recipient where to fetch the commits. That location must contain the end commit when the recipient follows the request. Push the branch to a repository you control, checking the URL and remote branch first:

$ git remote -v
origin  https://git.example.invalid/alice/project.git (fetch)
origin  https://git.example.invalid/alice/project.git (push)
$ git log --oneline origin/feature/example..HEAD
<commits that will be made available>
$ git push https://git.example.invalid/alice/project.git HEAD:feature/example
<push progress and a successful status>

Replace the example host, project and branch with real values. The explicit refspec makes the destination branch visible: local HEAD is sent to remote feature/example. If the push is rejected, fix the remote state and verify the resulting commit before generating the request.

4. Generate the request for the ordinary case

Use the upstream base, the repository URL, and the remote branch containing your work:

$ git request-pull v2.4.0 https://git.example.invalid/alice/project.git feature/example
The following changes since commit <start commit>:

  <commit subject>
  <another commit subject>

are available in the Git repository at:

  https://git.example.invalid/alice/project.git feature/example

for you to fetch changes up to <end commit>:

  <end commit> <commit subject>

----------------------------------------------------------------
<diffstat and commit summary>

The exact subjects, object IDs, dates and diffstat come from your repository, so do not compare those lines literally with this example. Check that the output names the intended start, URL, branch and end commit. Redirect it to a file if you want to edit or attach it:

$ git request-pull v2.4.0 https://git.example.invalid/alice/project.git feature/example > pull-request.txt
$ sed -n '1,80p' pull-request.txt
<the generated request is displayed>

Redirection replaces an existing pull-request.txt. Choose a new filename or inspect the destination first if an older request matters. If a command fails, the file may be empty or incomplete; regenerate it after correcting the cause.

5. Map different local and remote branch names

The final argument may use local:remote syntax. This is useful when your local branch is called topic but the pushed branch is called for-review:

$ git push https://git.example.invalid/alice/project.git topic:for-review
$ git request-pull v2.4.0 https://git.example.invalid/alice/project.git topic:for-review
<request referring to the repository's for-review ref>

Here, the name before the colon identifies the local ref used to resolve the end of the range, while the name after the colon identifies the remote ref that the recipient should fetch. Recheck both names before sending the output. A common distraction is to paste only the local branch name after a push that used a different remote name.

6. Include the patch only when the recipient needs it

By default, the command prints an overview. Add -p when the receiving workflow explicitly wants the patch text in the generated request:

$ git request-pull -p v2.4.0 https://git.example.invalid/alice/project.git feature/example > pull-request-with-patch.txt
$ grep -n '^diff --git ' pull-request-with-patch.txt
<one or more matching diff lines>

A patch can be large. Use the plain overview for a normal maintainer request unless the project asks for an inline patch or you are working in a channel where the recipient cannot fetch the repository. The -p option changes the output only; it does not alter commits or the remote.

7. Diagnose a request that looks wrong

If the command rejects a name, check that the start commit and end ref exist locally:

$ git rev-parse --verify v2.4.0^{commit}
<start object ID>
$ git rev-parse --verify feature/example^{commit}
<end object ID>
$ git diff --stat v2.4.0..feature/example
<expected changed-file summary>

If the output contains unexpected files, the range is wrong. Inspect the graph with git log --graph --oneline --decorate v2.4.0..feature/example and choose the correct start or end. If the output points to a branch that the recipient cannot fetch, push that exact ref and rerun the command.

Do not treat a successful exit status as approval of the content. Git can generate a syntactically valid request for the wrong repository, branch or commit. Read the output as a final review step before sending it upstream.