Documentation (2024.2 Enterprise)

# 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.

- Attributes
- Request Parameters
- Child Objects
- Operations
  - `GET /projects/:project_id/repositories/:repository_id/commits`
  - `POST /projects/:project_id/repositories/:repository_id/commits`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/changesets`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/tree(/:path)`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/files(/:path)`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/history(/:path)`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/future(/:path)`
  - `GET /projects/:project_id/repositories/:repository_id/commits/:id/search`
  - `GET /projects/:project_id/repositories/:repository_id/compare/commits/:base...:head` experimental
  - `GET /projects/:project_id/repositories/:repository_id/compare/changesets/:base...:head` experimental
  - `GET /projects/:project_id/tasks/:task_id/commits`

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

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"
          }
        }
      ]
    }

Your search for returned results

Your search for returned results