feat: Added matching-ref API (Issue #2155)

src/main/java/org/kohsuke/github/GHRef.java

@@ -126,6 +126,24 @@ static PagedIterable<GHRef> readMatching(GHRepository repository, String refType
         return repository.root().createRequest().withUrlPath(url).toIterable(GHRef[].class, item -> repository.root());
     }
 
+    /**
+     * Retrieves all refs that match the given prefix using the matching-refs endpoint.
+     *
+     * @param repository
+     *            the repository to read from
+     * @param refPrefix
+     *            the ref prefix to search for e.g. <code>heads/main</code> or <code>tags/v1</code>
+     * @return paged iterable of all refs matching the specified prefix
+     */
+    static PagedIterable<GHRef> readMatchingRefs(GHRepository repository, String refPrefix) {
+        if (refPrefix.startsWith("refs/")) {
+            refPrefix = refPrefix.replaceFirst("refs/", "");
+        }
+
+        String url = repository.getApiTailUrl(String.format("git/matching-refs/%s", refPrefix));
+        return repository.root().createRequest().withUrlPath(url).toIterable(GHRef[].class, item -> repository.root());
+    }
+
     private GHObject object;
 
     private String ref, url;

src/main/java/org/kohsuke/github/GHRepository.java

@@ -2800,6 +2800,18 @@ public Map<String, Long> listLanguages() throws IOException {
         return result;
     }
 
+    /**
+     * Retrieves all refs that match the given prefix using the matching-refs endpoint. This is useful to avoid fetching
+     * all available refs.
+     *
+     * @param refPrefix
+     *            the ref prefix to match e.g. <code>heads/main</code> or <code>tags/v1</code>
+     * @return paged iterable of all refs matching the specified prefix
+     */
+    public PagedIterable<GHRef> listMatchingRefs(String refPrefix) {
+        return GHRef.readMatchingRefs(this, refPrefix);
+    }
+
     /**
      * Lists up all the milestones in this repository.
      *

src/test/java/org/kohsuke/github/GHRepositoryTest.java

@@ -1009,6 +1009,35 @@ public void listLanguages() throws IOException {
         assertThat(languages.get("Java"), greaterThan(100000L));
     }
 
+    /**
+     * List matching refs.
+     *
+     * @throws Exception
+     *             the exception
+     */
+    @Test
+    public void listMatchingRefs() throws Exception {
+        GHRepository repo = getRepository();
+        List<GHRef> refs;
+
+        // Test listing refs matching a prefix
+        refs = repo.listMatchingRefs("heads").toList();
+        assertThat(refs, notNullValue());
+        assertThat(refs.size(), greaterThan(3));
+        assertThat(refs.get(0).getRef(), equalTo("refs/heads/changes"));
+
+        // Test with refs/ prefix
+        List<GHRef> refsWithPrefix = repo.listMatchingRefs("refs/heads").toList();
+        assertThat(refsWithPrefix.size(), equalTo(refs.size()));
+        assertThat(refsWithPrefix.get(0).getRef(), equalTo(refs.get(0).getRef()));
+
+        // Test with a more specific prefix
+        refs = repo.listMatchingRefs("heads/gh").toList();
+        assertThat(refs, notNullValue());
+        assertThat(refs.size(), equalTo(1));
+        assertThat(refs.get(0).getRef(), equalTo("refs/heads/gh-pages"));
+    }
+
     /**
      * List refs.
      *

src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/listMatchingRefs/__files/1-user.json

@@ -0,0 +1,45 @@
+{
+  "login": "bitwiseman",
+  "id": 1958953,
+  "node_id": "MDQ6VXNlcjE5NTg5NTM=",
+  "avatar_url": "https://avatars3.githubusercontent.com/u/1958953?v=4",
+  "gravatar_id": "",
+  "url": "https://api.github.com/users/bitwiseman",
+  "html_url": "https://github.com/bitwiseman",
+  "followers_url": "https://api.github.com/users/bitwiseman/followers",
+  "following_url": "https://api.github.com/users/bitwiseman/following{/other_user}",
+  "gists_url": "https://api.github.com/users/bitwiseman/gists{/gist_id}",
+  "starred_url": "https://api.github.com/users/bitwiseman/starred{/owner}{/repo}",
+  "subscriptions_url": "https://api.github.com/users/bitwiseman/subscriptions",
+  "organizations_url": "https://api.github.com/users/bitwiseman/orgs",
+  "repos_url": "https://api.github.com/users/bitwiseman/repos",
+  "events_url": "https://api.github.com/users/bitwiseman/events{/privacy}",
+  "received_events_url": "https://api.github.com/users/bitwiseman/received_events",
+  "type": "User",
+  "site_admin": false,
+  "name": "Liam Newman",
+  "company": "Cloudbees, Inc.",
+  "blog": "",
+  "location": "Seattle, WA, USA",
+  "email": "[email protected]",
+  "hireable": null,
+  "bio": "https://twitter.com/bitwiseman",
+  "public_repos": 183,
+  "public_gists": 7,
+  "followers": 159,
+  "following": 9,
+  "created_at": "2012-07-11T20:38:33Z",
+  "updated_at": "2020-05-20T16:02:42Z",
+  "private_gists": 19,
+  "total_private_repos": 12,
+  "owned_private_repos": 0,
+  "disk_usage": 33697,
+  "collaborators": 0,
+  "two_factor_authentication": true,
+  "plan": {
+    "name": "free",
+    "space": 976562499,
+    "collaborators": 0,
+    "private_repos": 10000
+  }
+}

src/test/resources/org/kohsuke/github/GHRepositoryTest/wiremock/listMatchingRefs/__files/2-orgs_hub4j-test-org.json

@@ -0,0 +1,41 @@
+{
+  "login": "hub4j-test-org",
+  "id": 7544739,
+  "node_id": "MDEyOk9yZ2FuaXphdGlvbjc1NDQ3Mzk=",
+  "url": "https://api.github.com/orgs/hub4j-test-org",
+  "repos_url": "https://api.github.com/orgs/hub4j-test-org/repos",
+  "events_url": "https://api.github.com/orgs/hub4j-test-org/events",
+  "hooks_url": "https://api.github.com/orgs/hub4j-test-org/hooks",
+  "issues_url": "https://api.github.com/orgs/hub4j-test-org/issues",
+  "members_url": "https://api.github.com/orgs/hub4j-test-org/members{/member}",
+  "public_members_url": "https://api.github.com/orgs/hub4j-test-org/public_members{/member}",
+  "avatar_url": "https://avatars3.githubusercontent.com/u/7544739?v=4",
+  "description": null,
+  "is_verified": false,
+  "has_organization_projects": true,
+  "has_repository_projects": true,
+  "public_repos": 15,
+  "public_gists": 0,
+  "followers": 0,
+  "following": 0,
+  "html_url": "https://github.com/hub4j-test-org",
+  "created_at": "2014-05-10T19:39:11Z",
+  "updated_at": "2020-05-15T15:14:14Z",
+  "type": "Organization",
+  "total_private_repos": 0,
+  "owned_private_repos": 0,
+  "private_gists": 0,
+  "disk_usage": 148,
+  "collaborators": 0,
+  "billing_email": "[email protected]",
+  "default_repository_permission": "none",
+  "members_can_create_repositories": false,
+  "two_factor_requirement_enabled": false,
+  "plan": {
+    "name": "free",
+    "space": 976562499,
+    "private_repos": 10000,
+    "filled_seats": 17,
+    "seats": 3
+  }
+}