Skip to content

References

Jump to bottom Edit New page
Nick Kallen edited this page Aug 22, 2013 · 4 revisions

Get all references

GET /repos/:repo/refs
Response
[
  {
    "name": "refs/remotes/origin/master",
    "url": "/repos/gitdb/refs/remotes/origin/master"
  },
  {
    "name": "refs/heads/master",
    "url": "/repos/gitdb/refs/heads/master"
  },
  {
    "name": "refs/remotes/origin/HEAD",
    "url": "/repos/gitdb/refs/remotes/origin/HEAD"
  }
]

Get a reference

GET /repos/:repo/refs/:ref
Response

The data at this endpoint is much richer than for listing all references, since the data for a reference is one random access in storage.

{
  "name": "refs/heads/master",
  "type": 1,
  "object": {
    "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7"
  },
  "url": "/repos/gitdb/refs/heads/master",
  "commits_url": "/repos/gitdb/refs/heads/master/commits",
  "tree_url": "/repos/gitdb/refs/heads/master/tree/",
  "repo": {
    "url": "/repos/gitdb",
    "refs_url": "/repos/gitdb/refs"
  }
}

Get the history of a reference

Analogous to git log. Note that it is one random access to storage for each entry, plus a topological sort, so this resource is typically both IO and CPU intensive.

GET /repos/:repo/refs/heads/:ref/commits
Response
[
  {
    "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "message": "Better web navigation\n",
    "author": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "committer": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "tree": {
      "sha": "93fb384f1f8bfac23a2fbef7f4c40a345a0fd312"
    },
    "parents": [
      {
        "sha": "a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
        "url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b"
      }
    ],
    "url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "tree_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  },
  {
    "sha": "a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
    "message": "Urls provided in json\n",
    "author": {
      "date": "2013-08-20T14:07:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "committer": {
      "date": "2013-08-20T14:07:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "tree": {
      "sha": "73720a4c31acc9563d65483614b46901315646c1"
    },
    "parents": [
      {
        "sha": "47c45a658a6a6ff3a3d6b78cd30d8dc05eb49045",
        "url": "/repos/gitdb/commits/47c45a658a6a6ff3a3d6b78cd30d8dc05eb49045"
      }
    ],
    "url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
    "tree_url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  }
]

Make a commit to a reference

POST /repos/:repo/refs/:ref/commits
Parameters
parents

Array of the SHAs of the commits that were the parents of this commit.

message

String of the commit message

tree

Array of hashes representing changes to the file-sysetm relative to the parent commit. Supported encodings for the content include ascii, utf8, and base64.

"tree": [
  {
    "path": "README.md",
    "content": "Get on the bus, Gus",
    "encoding": "utf8",
    "filemode": 33188
  },
  {
    "path": "lib/foo.coffee",
    "content": "Make a new plan, Stan",
    "encoding": "utf8",
    "filemode": 33188
  }
]
author

Hash representing author of the code in the commit.

  "author": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  }
committer

Same format as author; represents the user who performed the commit.

Example Input
{
  "message": "a new commit",
  "parents": ["73720a4c31acc9563d65483614b46901315646c1"],
  "author": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  },
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  },
  "tree": [
    {
      "path": "README.md",
      "content": "Get on the bus, Gus",
      "encoding": "utf8",
      "filemode": 33188
    },
    {
      "path": "lib/foo.coffee",
      "content": "Make a new plan, Stan",
      "encoding": "utf8",
      "filemode": 33188
    }
  ]
}
Response
201 CREATED
Location: /repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b

{
  "sha": "a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
  "message": "Urls provided in json\n",
  "author": {
    "date": "2013-08-20T14:07:42.000Z",
    "name": "Nick Kallen",
    "email": "socialmediamaster9000@gmail.com"
  },
  "committer": {
    "date": "2013-08-20T14:07:42.000Z",
    "name": "Nick Kallen",
    "email": "socialmediamaster9000@gmail.com"
  },
  "tree": {
    "sha": "73720a4c31acc9563d65483614b46901315646c1"
  },
  "parents": [
    {
      "sha": "47c45a658a6a6ff3a3d6b78cd30d8dc05eb49045",
      "url": "/repos/gitdb/commits/47c45a658a6a6ff3a3d6b78cd30d8dc05eb49045"
    }
  ],
  "url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
  "tree_url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b/tree/",
  "repo": {
    "url": "/repos/gitdb",
    "refs_url": "/repos/gitdb/refs"
  }
}

Get a tree, relative to a reference

A tree represents the state of the file system. A given element in the tree might be a tree itself (i.e., a directory) or a blob (i.e., a file in a directory) -- the response look different for these different types.

GET /repos/:repo/refs/:ref/tree/*
Response for a tree
{
  "name": "",
  "path": "",
  "type": "tree",
  "filemode": 16384,
  "commit_relative_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/",
  "ref_relative_url": "/repos/gitdb/refs/heads/master/tree/",
  "url": "/repos/gitdb/trees/93fb384f1f8bfac23a2fbef7f4c40a345a0fd312/",
  "tree": {
    "sha": "93fb384f1f8bfac23a2fbef7f4c40a345a0fd312",
    "url": "/repos/gitdb/trees/93fb384f1f8bfac23a2fbef7f4c40a345a0fd312/",
    "entries": [
      {
        "name": ".gitignore",
        "path": ".gitignore",
        "type": "blob",
        "filemode": 33188,
        "commit_relative_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/.gitignore",
        "ref_relative_url": "/repos/gitdb/refs/heads/master/tree/.gitignore",
        "url": "/repos/gitdb/blobs/3a1651fa759ca2e1717993b8bb75f951a732ee43"
      },
      {
        "name": "README.md",
        "path": "README.md",
        "type": "blob",
        "filemode": 33188,
        "commit_relative_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/README.md",
        "ref_relative_url": "/repos/gitdb/refs/heads/master/tree/README.md",
        "url": "/repos/gitdb/blobs/5c5ac45d9513562cc96e8e7021a8064009451ed8"
      }
    ]
  },
  "commit": {
    "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "message": "Better web navigation\n",
    "author": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "committer": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "tree": {
      "sha": "93fb384f1f8bfac23a2fbef7f4c40a345a0fd312"
    },
    "parents": [
      {
        "sha": "a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
        "url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b"
      }
    ],
    "url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "tree_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  },
  "ref": {
    "name": "refs/heads/master",
    "type": 1,
    "object": {
      "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7"
    },
    "url": "/repos/gitdb/refs/heads/master",
    "commits_url": "/repos/gitdb/refs/heads/master/commits",
    "tree_url": "/repos/gitdb/refs/heads/master/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  },
  "repo": {
    "url": "/repos/gitdb",
    "refs_url": "/repos/gitdb/refs"
  }
}
Response for a blob

Since blobs can be any arbitrary binary data, the input and responses for the blob API is returned encoded. Currently all data is base64 encoded, but for future compatibility, please use the encoding field when decoding data. Note that the media type application/vnd.gitdb.raw is also supported for blobs.

{
  "name": "README.md",
  "path": "README.md",
  "type": "blob",
  "filemode": 33188,
  "commit_relative_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/README.md",
  "ref_relative_url": "/repos/gitdb/refs/heads/master/tree/README.md",
  "url": "/repos/gitdb/blobs/5c5ac45d9513562cc96e8e7021a8064009451ed8",
  "blob": {
    "filemode": 33188,
    "encoding": "base64",
    "size": 1276,
    "content": "KipHaXREQioqIGlzIGFuIEh...",
    "sha": "5c5ac45d9513562cc96e8e7021a8064009451ed8",
    "url": "/repos/gitdb/blobs/5c5ac45d9513562cc96e8e7021a8064009451ed8"
  },
  "commit": {
    "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "message": "Better web navigation\n",
    "author": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "committer": {
      "date": "2013-08-20T15:54:42.000Z",
      "name": "Nick Kallen",
      "email": "socialmediamaster9000@gmail.com"
    },
    "tree": {
      "sha": "93fb384f1f8bfac23a2fbef7f4c40a345a0fd312"
    },
    "parents": [
      {
        "sha": "a3ba5a6e314ed63571e01677463164cb7a8a1e9b",
        "url": "/repos/gitdb/commits/a3ba5a6e314ed63571e01677463164cb7a8a1e9b"
      }
    ],
    "url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7",
    "tree_url": "/repos/gitdb/commits/38f8d228f43f53bc42a77d5821aece4f09e66ca7/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  },
  "ref": {
    "name": "refs/heads/master",
    "type": 1,
    "object": {
      "sha": "38f8d228f43f53bc42a77d5821aece4f09e66ca7"
    },
    "url": "/repos/gitdb/refs/heads/master",
    "commits_url": "/repos/gitdb/refs/heads/master/commits",
    "tree_url": "/repos/gitdb/refs/heads/master/tree/",
    "repo": {
      "url": "/repos/gitdb",
      "refs_url": "/repos/gitdb/refs"
    }
  },
  "repo": {
    "url": "/repos/gitdb",
    "refs_url": "/repos/gitdb/refs"
  }
}

Create or update a file on a reference

This method creates or updates a blob (file) in a repository, creates a new commit, and updates the head pointer of the ref. This is a more surgical version of POST /repos/:repo/refs/:ref/commits.

PUT /repos/:repo/refs/:ref/tree/*
Parameters
previous_sha

The sha of the previous version of the blob. The sha must match the current version of the blob on the ref, otherwise the server will return an HTTP 412 error code.

message

String of the commit message

author

Hash representing author of the code in the commit.

  "author": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  }
committer

Same format as author; represents the user who performed the commit.

filemode

Indicates whether the file is binary or not. Valid values are 33188 (not binary) and 33261 (binary).

content

An encoded string representation of the file.

encoding

Supported encodings for the content include ascii, utf8, and base64.

Example Input
{
  "message": "a new commit",
  "previous_sha": "73720a4c31acc9563d65483614b46901315646c1",
  "author": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  },
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2008-07-09T16:13:30+12:00"
  },
  "content": "Get on the bus, Gus",
  "encoding": "utf8",
  "filemode": 33188
}
Response
Add a custom footer
Add a custom sidebar
Clone this wiki locally