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

Activity

1. muzimuzhi

   added

   bugSomething isn't workingSomething isn't working

   on May 7, 2025
2. cliAutomation

   added

   needs-triageneeds to be reviewedneeds to be reviewed

   on May 7, 2025
3. muzimuzhi

   changed the title [-]`gh pr list`: `--head` doesn't support the `<owner>:<branch>` syntax[/-] [+]`gh pr list`: no support for `--head <owner>:<branch>` syntax[/+] on May 7, 2025
4. babakks commented on May 8, 2025

   

   babakks

   on May 8, 2025

   Last edited by babakks

   Member

   More actions

   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
         }
       }
     }
   }
5. babakks

   added

   more-info-neededMore info needed from user/contributorMore info needed from user/contributor

   gh-prrelating to the gh pr commandrelating to the gh pr command

   and removed

   bugSomething isn't workingSomething isn't working

   needs-triageneeds to be reviewedneeds to be reviewed

   on May 8, 2025
6. muzimuzhi commented on May 9, 2025

   

   muzimuzhi

   on May 9, 2025

   ContributorAuthor

   More actions

   @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.
7. babakks

   removed

   more-info-neededMore info needed from user/contributorMore info needed from user/contributor

   on May 9, 2025
8. babakks commented on May 9, 2025

   

   babakks

   on May 9, 2025

   Member

   More actions

   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.
9. babakks

   closed this as completedon May 9, 2025
10. babakks commented on May 9, 2025

    

    babakks

    on May 9, 2025

    Last edited by babakks

    Member

    More actions

    @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.
11. babakks

    reopened this on May 9, 2025
12. babakks

    added

    enhancementa request to improve CLIa request to improve CLI

    coreThis issue is not accepting PRs from outside contributorsThis issue is not accepting PRs from outside contributors

    on May 9, 2025