Git References
A Git reference (git ref
) is just a file that contains a Git commit SHA-1 hash.
When referring to a Git commit, you can use the Git reference, which is an
easy-to-remember name, rather than the hash. The Git reference can be rewritten
to point to a new commit. A branch is just a Git reference that stores the new Git
commit hash. These endpoints allow you to read and write references
to your Git database on GitHub.
See the Git Database API for more details.
- Get a single reference
- List matching references
- Create a reference
- Update a reference
- Delete a reference
Get a single reference
Returns a single reference from your Git database. The :ref
in the URL must be formatted as heads/<branch name>
for branches and tags/<tag name>
for tags. If the :ref
doesn't match an existing ref, a 404
is returned.
Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".
GET /repos/:owner/:repo/git/ref/:ref
Example
To get the reference for a branch named skunkworkz/featureA
, the endpoint route is:
GET /repos/octocat/Hello-World/git/ref/heads/skunkworkz/featureA
Response
Status: 200 OK
{
"ref": "refs/heads/featureA",
"node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
"object": {
"type": "commit",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
}
}
List matching references
Returns an array of references from your Git database that match the supplied name. The :ref
in the URL must be formatted as heads/<branch name>
for branches and tags/<tag name>
for tags. If the :ref
doesn't exist in the repository, but existing refs start with :ref
, they will be returned as an array.
When you use this endpoint without providing a :ref
, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads
and tags
.
Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".
GET /repos/:owner/:repo/git/matching-refs/:ref
Example
If you request matching references for a branch named feature
but the branch feature
doesn't exist, the response can still include other matching head refs that start with the word feature
, such as featureA
and featureB
.
GET /repos/octocat/Hello-World/git/matching-refs/heads/feature
Response
Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
<https://api.github.com/resource?page=5>; rel="last"
[
{
"ref": "refs/heads/feature-a",
"node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
"url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a",
"object": {
"type": "commit",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
}
},
{
"ref": "refs/heads/feature-b",
"node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
"url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b",
"object": {
"type": "commit",
"sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
}
}
]
Create a reference
Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.
POST /repos/:owner/:repo/git/refs
Parameters
Name | Type | Description |
---|---|---|
ref |
string |
Required. The name of the fully qualified reference (ie: refs/heads/master ). If it doesn't start with 'refs' and have at least two slashes, it will be rejected. |
sha |
string |
Required. The SHA1 value for this reference. |
Input
{
"ref": "refs/heads/featureA",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd"
}
Response
Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA
{
"ref": "refs/heads/featureA",
"node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
"object": {
"type": "commit",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
}
}
Update a reference
PATCH /repos/:owner/:repo/git/refs/:ref
Parameters
Name | Type | Description |
---|---|---|
sha |
string |
Required. The SHA1 value to set this reference to |
force |
boolean |
Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to false will make sure you're not overwriting work. Default: false
|
Input
{
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"force": true
}
Response
Status: 200 OK
{
"ref": "refs/heads/featureA",
"node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
"url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
"object": {
"type": "commit",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
}
}
Delete a reference
DELETE /repos/:owner/:repo/git/refs/:ref
Example deleting a branch
DELETE /repos/octocat/Hello-World/git/refs/heads/feature-a
Response
Status: 204 No Content
Example deleting a tag
DELETE /repos/octocat/Hello-World/git/refs/tags/v1.0
Response
Status: 204 No Content