gh pr list: no support for --head <owner>:<branch> syntax

Describe the bug

gh pr list only supports the --head <branch> syntax but not --head <owner>:<branch>.

Meanwhile, gh pr create --head <owner>:<branch> is supported since v2.71.0 (added by #10513 in fixing #575).

Need to check other options which accept a branch name.

https://cli.github.com/manual/gh_pr_list
https://cli.github.com/manual/gh_pr_create

Affected version

gh version 2.72.0 (2025-04-30)
https://github.com/cli/cli/releases/tag/v2.72.0

Steps to reproduce the behavior

--head "typos" finds two closed PRs in latex3/latex repository.

$ GH_PAGER="" gh -R latex3/latex3 pr list --state all --head "typos"

Showing 2 of 2 pull requests in latex3/latex3 that match your search

ID     TITLE                                         BRANCH             CREATED AT
#1610  fix small typos                               mbertucci47:typos  about 6 months ago
#392   Typos in the intro to the l3tl documentation  EvanAad:typos      about 7 years ago

But when specific owner name is provided (`--head ":typos"), no PR is found.

$ GH_PAGER="" gh -R latex3/latex3 pr list --state all --head "mbertucci47:typos"
no pull requests match your search in latex3/latex3
$ GH_PAGER="" gh -R latex3/latex3 pr list --state all --head "EvanAad:typos"
no pull requests match your search in latex3/latex3

Logs

Adding GH_DEBUG=api, it seems the only useful info is that the <owner>:<branch> was correctly passed on to GraphQL variables

$ GH_DEBUG=api GH_PAGER="" gh -R latex3/latex3 pr list --state all --head "mbertucci47:typos"

[...] 
GraphQL variables: {"headBranch":"mbertucci47:typos","limit":30,"owner":"latex3","repo":"latex3","state":["OPEN","CLOSED","MERGED"]}
[...]

@muzimuzhi

Thanks for submitting this issue, @muzimuzhi! 🙏

This seems like a limit/restriction in our GraphQL API. Please note that pr create uses the createPullRequest mutation, while pr list uses the repository object's pullRequests fields. So, they're two different things. Both of these support a headRefName argument, but the behaviour is different (i.e. one supports <owner>:<branch> and one doesn't).

As you pointed out gh pass the headRefName argument with the provided --head option, if any. Anyway, I attached the query for pr list at the end, in case you wanted to investigate it more.

That said, filtering of <owner> can be done at the gh side after retrieving the PRs (i.e. stripping the <owner>: part, if any, calling the GQL API, and then applying a filter on the results). However, IMHO, gh shouldn't be involved in such a niche data processings, because, for one the GQL API could change in the future and support <owner>:<branch> format for filtering PRs. Also, as a client, gh behaviour should not be very different from the GH API.

The combination of --json and --jq is a powerful tool for such scenarios. For example, this command will find the URL of the PR corresponding to one a specific user:

GH_PAGER="" gh -R latex3/latex3 pr list --state all \
   --head "typos" \
   --json id,title,url,headRefName,headRepositoryOwner \
   --jq '.[] | select(.headRepositoryOwner.login == "mbertucci47") | .url'

@muzimuzhi, do you think the --json/--jq approach could help with your situation?

GQL query

Below is the query gh uses to fetch the list of pull requests (variables are populated based on your case). You can try this GQL query in the Explorer.

Variables:

{
  "headBranch": "typos",
  "limit": 30,
  "owner": "latex3",
  "repo": "latex3",
  "state": [
    "OPEN",
    "CLOSED",
    "MERGED"
  ]
}

query PullRequestList($owner: String!, $repo: String!, $limit: Int!, $endCursor: String, $baseBranch: String, $headBranch: String, $state: [PullRequestState!] = OPEN) {
  repository(owner: $owner, name: $repo) {
    pullRequests(  # << Here
      states: $state
      baseRefName: $baseBranch
      headRefName: $headBranch
      first: $limit
      after: $endCursor
      orderBy: {field: CREATED_AT, direction: DESC}
    ) {
      totalCount
      nodes {
        number
        title
        state
        url
        headRefName
        headRefOid
        headRepository {
          name
        }
        headRepositoryOwner {
          id
          login
          ... on User {
            name
          }
        }
        isCrossRepository
        isDraft
        createdAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

@muzimuzhi, do you think the --json/--jq approach could help with your situation?

Yes, that would be enough.

Perhaps the doc of gh pr list could be more explicit on the supported syntax of --head value.

Great!

However, I'm not sure about including this explicitly in the docs, mostly because it's not either stated in the API docs. I mean, what if it changes in the future?

But adding another example in the --help docs seems like a good idea. This at least shows how the --head option can be used:

EXAMPLES
  ...

  # List PRs with a specific head branch name
  $ gh pr list --head "typo"

I'll now close this issue as it seems completed, and create a new one for adding the --head usage example.

@muzimuzhi

@muzimuzhi After discussing this with @williammartin, we decided there's value in your request. So, I reopened this.

What's needed

To recap, pr list needs to do client side filtering when the provided --head value is of the form <owner>:<branch> (aka a qualifed ref).

The change could be a bit complex due to the way pr list works. That is, pr list uses one of two queries (repository.pullRequests and search) based on the provided options. For example, if the --author option is assigned, then a search takes place. Therefore, the support for --head <owner>:<branch> should be covered in both queries.

Acceptance Criteria

Normal listing

Given I have a cross-repository PR whose head branch is on my fork
When I run gh pr list -R <base-repo> --head <my-login>:<branch>
Then the PR is listed

Search listing

Given I have a cross-repository PR whose head branch is on my fork
When I run gh pr list -R <base-repo> --head <my-login>:<branch> --author <my-login>
Then the PR is listed

Note

The --author option is to force pr list to do a search query. So any other option that only works with the search should lead to the same result.

Docs

`--head` usage

When I run gh pr list --help
Then the usage of the --head option mentions both <branch> and <owner>:<branch> syntaxes are supported.

Example

When I run gh pr list --help
Then there are example usages for both --head <user>:<branch> and --head <branch> syntax.

Note

The example for --head <branch> is going to be added by #10957.

Navigation Menu

Repository navigation

`gh pr list`: no support for `--head <owner>:<branch>` syntax #10945

Describe the bug

Affected version

Steps to reproduce the behavior

Logs

GQL query

What's needed

Acceptance Criteria

Normal listing

Search listing

Docs

`--head` usage

Example

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

gh pr list: no support for --head <owner>:<branch> syntax #10945

Description

Describe the bug

Affected version

Steps to reproduce the behavior

Logs

Activity

babakks commented on May 8, 2025

GQL query

muzimuzhi commented on May 9, 2025

babakks commented on May 9, 2025

babakks commented on May 9, 2025

What's needed

Acceptance Criteria

Normal listing

Search listing

Docs

--head usage

Example

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`gh pr list`: no support for `--head <owner>:<branch>` syntax #10945

`--head` usage