Prepare Git Pull Request Notes with git-request-pull

git request-pull writes a pull request message: the changes, the repository, the exact end commit, no push and no repository changes.

Allow about ten minutes for a normal branch. You need Git 2.43.0 or a compatible 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 others can pull from; and an optional end, the tip of your work. Omit end and 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: usually a release tag, a base branch tip, or the commit your topic branch grew from. Do not use the first commit of your topic branch unless that is genuinely what 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 the named release is an ancestor of your current tip. That check only concerns your local history: it does not prove the upstream maintainer has the same tag, so use a start name or object the receiving project actually 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 ones you meant to send.

3. Put the committed work where it can be pulled

The request tells the recipient where to fetch the commits, so that location must hold the end commit when they follow it. 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 against 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 check the destination first if an older request still matters. If a command fails, the file may be empty or incomplete, so regenerate it after fixing the cause.

5. Map different local and remote branch names

The final argument can use local:remote syntax. Handy 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>

The name before the colon identifies the local ref used to resolve the end of the range; the name after the colon identifies the remote ref the recipient should fetch. Recheck both names before sending the output. A common distraction is pasting 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 only 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 somewhere the recipient cannot fetch the repository. The -p option only changes the output; 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>

Unexpected files in that output mean the range is wrong. Inspect the graph with git log --graph --oneline --decorate v2.4.0..feature/example and pick the correct start or end. If the output points to a branch 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 you send it upstream.