Commit

A commit is a change in a version control repository (a Git commit, a Subversion revision, or a Mercurial changeset). Please note that as WebDAV, Maven, and Ivy don't support versioning, a dummy commit ID will have to be specified for most of the operations. In Helix TeamHub APIs, commits are the way to access Repository contents. They provide a way to:

  • Browse the commits and commit history of a repository.
  • Browse the metadata and contents of a commit.
  • Access the actual files in a repository.
  • Search repository for content and files (git only).

Commits can be created using the respective version control systems. Currently Helix TeamHub API supports creating commits only for git repositories.

Note

Forward slash characters in both :repository_id and :commit_id must be encoded with %2F

Attributes

id

The identifier of the commit (for example, a Git commit hash).

  • Type: string

timestamp

The time and date of the original commit, in ISO-8601 format (as reported by the version control system). Note that this is derived from the local time on the committer's device.

  • Type: timestamp

author

The name of the author of the commit (as reported by the version control system).

  • Type: string

email

The email of the author of the commit (as reported by the version control system).

  • Type: string

description

The commit message (as reported by the version control system).

  • Type: string

Request Parameters

parent

The parent commit SHA-1 value or reference, for example "caed70ef" or "master".

  • Type: string
  • Required: true

modified

An array of objects describing the changes made.

  • Type: array of object
  • Required: true if deleted is not provided, false otherwise
[
  {
    "path": "README.md",
    "content": "### Hello World"
  },
  {
    "encoding": "base64",
    "path": "norris.png",
    "content": "data:image/png;base64,..."
  }
]

deleted

An array of strings describing the removed files and/or directories.

  • Type: array of string
  • Required: true if modified is not provided, false otherwise
["foo.js", "bar", "baz.html"]

Child Objects

A commit's child objects can be accessed as subresources (see Operations), or (partly) expanded while requesting commit objects to minimize the amount of requests.

account

expand=account

This requires a valid commit email or author and will return a Helix TeamHub User or Collaborator if a matching one is found, otherwise an empty string. The mapping is primarily done using the commit email and secondarily by the commit author.

changeset

expand=changeset

A list of changed files with their respective individual changes.

tree

expand=tree

A directory structure (including metadata) of the repository at the time of this commit. Directories, files and Git submodules are represented in the same format (as "tree nodes").

Operations

GET /projects/:project_id/repositories/:repository_id/commits

Lists the newest commits for the given repository, with optional limit and offset parameters, as a metadata-results object.

POST /projects/:project_id/repositories/:repository_id/commits

Creates a new commit. Content of the modified files can be UTF-8 (default) or base64 encoded with optional data header. Description for the commit is optional and a default message is generated when it is omitted. The endpoint also accepts multipart/form-data content-type, which can be needed when dealing with larger files. Currently only git repositories are supported.

Example Request

curl -X POST \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "master",
    "description": "Edited some files",
    "modified": [
      {
        "path": "lib/apps.js",
        "content": "console.log(42);"
      },
      {
        "encoding": "base64",
        "path": "run.js",
        "content": "Zm9vKCk7"
      },
      {
        "encoding": "base64",
        "path": "dot.png",
        "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
      }
    ],
    "deleted": ["foo.js"]
  }' \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/commits

Example Request with multipart/form-data

curl -X POST \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  -F "parent=master" \
  -F "modified[][path]=README.md" \
  -F "modified[][content]=@README.md" \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/commits

Example Response

{
  "api_status": 201,
  "api_timestamp": "2013-10-21T08:31:15Z",
  "id": "42cc6d9a9bad6758d6b8357e47f662c236a9c59c",
  "author": "Chuck Norris",
  "email": "chuck@norris.com",
  "description": "Edited some files",
  "timestamp": "2013-10-21T08:31:15Z"
}

GET /projects/:project_id/repositories/:repository_id/commits/:id

Shows an individual commit object.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/luotsi/commits/c57164ed653ec49665ff91b906ca41101bcc3486

Example Response

{
    "api_status": 200,
    "api_timestamp": "2012-10-25T13:51:07Z",
    "id": "c57164ed653ec49665ff91b906ca41101bcc3486",
    "author": "Anssi Syrjäsalo",
    "email": "anssi.syrjasalo@eficode.com",
    "description": "User short_name cannot be 'count'",
    "timestamp": "2012-10-24T15:41:55Z"
}

GET /projects/:project_id/repositories/:repository_id/commits/:id/changesets

Returns changes made in a commit. The changes are limited to at maximum of 150 files, 50 000 lines, or a total of 1 MB of diff content. Individual file diffs are limited to 50 KB of diff content.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/luotsi/commits/831c9809309e640a5191a639a7f002012f2a842c/changesets

Example Response

[
    {
        "api_status": 200,
        "api_timestamp": "2012-10-25T14:03:03Z",
        "path": "spec/models/project_spec.rb",
        "file_type": "text",
        "additions": 1,
        "deletions": 1,
        "action": "modified",
        "truncated": false,
        "diff": [
            {
                "type": "range",
                "content": "@@ -67,7 +67,7 @@ describe Api::V1::Project do",
                "old_start_line": "67",
                "new_start_line": "67"
            },
            {
                "type": "unchanged",
                "content": " "
            },
            {
                "type": "unchanged",
                "content": "         it \"should be listed\" do"
            },
            {
                "type": "unchanged",
                "content": "           serialized = @api_model.new(@project, { list: 'users' }).to_api"
            },
            {
                "type": "deleted",
                "content": "-          serialized[:users].should == [ @user.short_name, @user2.short_name ]"
            },
            {
                "type": "added",
                "content": "+          serialized[:users].should =~ [ @user.short_name, @user2.short_name ]"
            },
            {
                "type": "unchanged",
                "content": "         end"
            },
            {
                "type": "unchanged",
                "content": " "
            },
            {
                "type": "unchanged",
                "content": "         it \"should be included\" do"
            }
        ]
    }
]

GET /projects/:project_id/repositories/:repository_id/commits/:id/tree(/:path)

Returns one level of file hierarchy and metadata specified by the path. Latest commit for each node can be expanded with expand=commit.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/luotsi/commits/master/tree/lib

Example Response

{
    "api_status": 200,
    "api_timestamp": "2012-10-25T13:54:56Z",
    "id": "25f79cbd94c83535c6119aab43b32f9b1c79f39c",
    "type": "directory",
    "name": "lib",
    "path": "lib",
    "mime": "",
    "size": 0,
    "file_url": "",
    "children": [
        {
            "api_status": 200,
            "api_timestamp": "2012-10-25T13:54:56Z",
            "id": "baaa70dc339f33191ead4f17a9e82296b4f4d43b",
            "type": "directory",
            "name": "hth",
            "path": "lib/hth",
            "mime": "",
            "size": 0,
            "file_url": "",
            "children": []
        },
        {
            "api_status": 200,
            "api_timestamp": "2012-10-25T13:54:56Z",
            "id": "faa8489b72245fb662772dca55fced6a6e65b6dd",
            "type": "directory",
            "name": "devise",
            "path": "lib/devise",
            "mime": "",
            "size": 0,
            "file_url": "",
            "children": []
        },
        {
            "api_status": 200,
            "api_timestamp": "2012-10-25T13:54:56Z",
            "id": "882d9014f4335261bcf68c4d0596f7983d262d5b",
            "type": "directory",
            "name": "tasks",
            "path": "lib/tasks",
            "mime": "",
            "size": 0,
            "file_url": "",
            "children": []
        }
    ]
}

GET /projects/:project_id/repositories/:repository_id/commits/:id/files(/:path)

Returns the contents of a given file, delivered with the correct mime type (and possibly converted to a format as requested by the client e.g. contentType=html).

GET /projects/:project_id/repositories/:repository_id/commits/:id/history(/:path)

Returns all the parent commits for a specified commit, with optional limit and offset, as a metadata-results object.

GET /projects/:project_id/repositories/:repository_id/commits/:id/future(/:path)

Returns all the children commits for a specified commit, with optional limit and offset, as a metadata-results object.

GET /projects/:project_id/repositories/:repository_id/commits/:id/search

Searches repository content and paths for the search_term parameter. Optional search_target parameter can be used to limit the target of the search. Currently only git repositories are supported.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/luotsi/repositories/chef/commits/master/search?search_term=console&search_target=path,content

Example Response

{
  "content_matches": [
    {
      "path": "javascripts/lib.js",
      "count": 2
    },
    {
      "path": "apps/run.js",
      "count": 1
    }
  ],
  "path_matches": [
    "javascripts/console-fix.js",
    "app/assets/images/console.gif"
  ]
}

GET /projects/:project_id/repositories/:repository_id/compare/commits/:base...:head

Warning

This is an experimental API part and might be changed in the future.

Returns a range of commits from :base to :head. Both identifiers might be commit SHA1 identifiers or branch names. The output is similar to the /commits endpoint but narrowed to the given range borders. The endpoint is limited to return at maximum 200 commits.

Child objects are available within this result set through the optional expand parameter. Currently only git repositories are supported.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/my_project/repositories/my_repo/compare/commits/f473437413f44ca71d7c6b6ae0f68b32f7bafd7d...master

Example Response

{
  "metadata": {
    "more_results": false,
    "next_offset": 2,
    "count": 2
  },
  "results": [
    {
      "api_status": 200,
      "api_timestamp": "2015-02-16T13:16:30Z",
      "id": "5e251b94869ebcd0029b5e182f0e65010908cfa3",
      "author": "Bruce Wayne",
      "email": "bruce@waynecorp.com",
      "description": "Change to bar",
      "timestamp": "2015-02-06T07:04:13Z"
    },
    {
      "api_status": 200,
      "api_timestamp": "2015-02-16T13:16:30Z",
      "id": "f3d627d76bb76fdd2968f803151d5c5f6fe00de9",
      "author": "Bruce Wayne",
      "email": "bruce@waynecorp.com",
      "description": "Add foo",
      "timestamp": "2015-02-05T19:55:40Z"
    }
  ]
}

GET /projects/:project_id/repositories/:repository_id/compare/changesets/:base...:head

WARNING: This is an experimental API part and might be changed in the future.

Returns a range of changesets from :base to :head. Both identifiers might be commit SHA1 identifiers or branch names. The output is similar to the /changesets endpoint but narrowed to the given range borders. The same limits are applied as with /changesets endpoint. Currently only git repositories are supported.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/my_project/repositories/my_repo/compare/changesets/f473437413f44ca71d7c6b6ae0f68b32f7bafd7d...master

Example Response

[
  {
    "api_status": 200,
    "api_timestamp": "2015-02-16T14:24:39Z",
    "path": "foo.txt",
    "file_type": "text",
    "additions": 5,
    "deletions": 3,
    "action": "modified",
    "truncated": false,
    "diff": [
      {
        "type": "range",
        "content": "@@ -1,5 +1,7 @@",
        "old_start_line": "1",
        "new_start_line": "1"
      },
      {
        "type": "unchanged",
        "content": " Lorem ipsum."
      },
      {
        "type": "added",
        "content": "+Dolor sit amet."
      },
      {
        "type": "added",
        "content": "+Lorem ipsumljl."
      },
      {
        "type": "added",
        "content": "+Lorem bla."
      },
      {
        "type": "added",
        "content": "+Lorem ipsumlkj."
      },
      {
        "type": "unchanged",
        "content": " Lorem ipsum."
      },
      {
        "type": "deleted",
        "content": "-Lorem ipsum."
      },
      {
        "type": "deleted",
        "content": "-Lorem ipsum."
      },
      {
        "type": "deleted",
        "content": "-Lorem ipsum."
      },
      {
        "type": "added",
        "content": "+aaabbbccc"
      }
    ],
    "file_url": "https://helixteamhub.cloud/api/projects/my_project/repositories/my_repo/commits/foobar/files/foo.txt"
  }
]

GET /projects/:project_id/tasks/:task_id/commits

Returns commits that reference the task identifier (e.g. #123) in the commit messages.

Example Request

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  https://helixteamhub.cloud/api/projects/luotsi/tasks/123/commits

Example Response

{
  "metadata": {
    "more_results": false,
    "next_offset": 0,
    "count": 2
  },
  "results": [
    {
      "api_status": 200,
      "api_timestamp": "2016-06-01T12:27:42Z",
      "id": "40e364753c6d116624416df1cb05d3594fc20ea5",
      "author": "Bruce Wayne",
      "email": "bruce@waynecorp.com",
      "description": "Simplify exception handling #123",
      "timestamp": "2016-06-01T12:27:07Z",
      "repository": {
        "id": "chef",
        "uuid": "9ddb4b81-5f7b-42c9-9860-1e519a75b483"
      },
      "project": {
        "id": "luotsi",
        "uuid": "9c54e6ca-402b-4db9-9bc1-fcb6d20f935a"
      }
    },
    {
      "api_status": 200,
      "api_timestamp": "2016-06-01T12:27:42Z",
      "id": "efb518e2e295a8f7b2d08cc5151969f7aeb6d371",
      "author": "Bruce Wayne",
      "email": "bruce@waynecorp.com",
      "description": "Remove deprecated methods. #123 & #124",
      "timestamp": "2016-06-01T12:25:57Z",
      "repository": {
        "id": "chef",
        "uuid": "9ddb4b81-5f7b-42c9-9860-1e519a75b483"
      },
      "project": {
        "id": "luotsi",
        "uuid": "9c54e6ca-402b-4db9-9bc1-fcb6d20f935a"
      }
    }
  ]
}