Repositories

Table of Contents

1. Working with Repositories
2. Api/{version}/Repo/Create (POST)
3. Api/{version}/Repo/{ixRepo} (GET)
4. Api/{version}/Repo/{ixRepo} (POST)
5. Api/{version}/Repo/{ixRepo}/Delete (POST)
6. Api/{version}/Repo/{ixRepo}/Outgoing (GET)
7. Api/{version}/Repo/{ixRepo}/Push/{ixTargetRepo} (POST)
8. Api/{version}/Repo/{ixRepo}/History (GET)
9. Api/{version}/Repo/{ixRepo}/History/{rev} (GET)
10. Api/{version}/Repo/{ixRepo}/File/{bpPath} (GET)
11. Api/{version}/Repo/Related (GET)
12. Api/{version}/Repo/{ixRepo}/Related (GET)
13. Api/{version}/Repo/{ixRepo}/Manifest (GET)
14. Api/{version}/Repo/{ixRepo}/CaseAssociation/Create(POST)
15. Api/{version}/Repo/{ixRepo}/CaseAssociation/Delete(POST)
16. Api/{version}/Repo/{ixRepo}/Tags (GET)
17. Api/{version}/Repo/{ixRepo}/Tags/Create (POST)
18. Api/{version}/Repo/{ixRepo}/NamedBranches (GET)
19. Api/{version}/Repo/{ixRepo}/Commit (POST)
20. Api/{version}/Repo/{ixRepo}/Raw/History/{rev} (GET)
21. Api/{version}/Repo/{ixRepo}/Raw/File/{bpPath} (GET)
22. Errors

Working with Repositories

At last, repositories. API 1.0 lets you create, read, update, and delete repositories in addition to including some basic history and changeset functionality. As a reminder, you can query for the ixRepos you need from the Api/{version}/Project call.

Api/{version}/Repo/Create (POST)

You need to be a project administrator to create a central repository. You need to have at least project write permissions to the project to create a branch repository. Takes

• sName (required): the new repository name
• sDescription (optional): the new repository description
• ixRepoGroup (required): the repository group the new repository will belong to
• ixParent (optional; if given, the ixParent repository will be branched to create the new repository): the parent repository
• fCentral (optional; defaults to true): true if the new repository should be central; false otherwise
• permissionDefault (optional; defaults to "none"): the default repository permission, one of "none", "read", "modify", or "inherit"
• vcs (optional; defaults to "Both"): the type of repository to create: "Git", "Hg", or "Both" (Harmony)

Returns the new repository's repository record, which does not guarantee the backend has created the repository yet. This is an asynchronous call. You should poll Api/{version}/Repo/{ixRepo} until "sStatus" becomes "good" to determine when the backend has finished. This call will be slower if the backend needs to branch a parent repository.

Important note: Setting ixParent on this call is how you branch repositories through the API.

As of Kiln 2.5.171: You can now also create branch repositories with project read + write permissions. (A previous announcement regarding this feature in 2.5.96 was incorrect due to a bug in the implementation; we apologize for this error.)

Api/{version}/Repo/{ixRepo} (GET)

You need read permissions to the repository. Returns the repository record.

Api/{version}/Repo/{ixRepo} (POST)

You need to be the repository creator or have administrator permissions to modify a branch repository; you need to have administrator permissions to modify a central repository. Takes

• sName: the new repository name
• sDescription: the new repository description
• ixRepoGroup: the new repository group to move the repository 
• ixParent: the new repository parent (you must have read permission to the new parent).
  Kiln 2.5.96 and higher only: Specify 0 to set the repository's parent to None (null).
• fCentral: if true, converts the branch repository into a central repository (can only be set for branch repositories)
• permissionDefault: the new default repository permission

(All optional.) and updates the repository with the fields. Returns the updated repository record.

Api/{version}/Repo/{ixRepo}/Delete (POST)

You need to be the repository creator or have administrator permissions to delete a branch repository; you need to have administrator permissions on the repository and the project to delete a central repository. Repositories can be undeleted by a project administrator from the website user interface.

Api/{version}/Repo/{ixRepo}/Outgoing (GET)

• ixOtherRepo: the repository to compare to
• revOlderThan: only include changesets older than this outgoing changeset (optional; defaults to tip)
• nChangesetLimit: the number of changesets to return (optional; defaults to 30)
• vcs: the Version Control System to use. 1 = Mercurial (default), 2 = Git. Git-only repos must specify vcs=2.

and returns a list of outgoing changeset records.    

Api/{version}/Repo/{ixRepo}/Push/{ixTargetRepo} (POST)

Where ixTargetRepo is the target repository to push to. Requires read permissions to the ixRepo source repository and write permissions to to the ixTargetRepo target repository. The target repository must contain a strict subset of the changesets in the source repository; the source must be related to the target; and the push must not create new heads in the target. Takes no other parameters. Returns true on success.

Api/{version}/Repo/{ixRepo}/History (GET)

Requires read permissions to the repository. Takes

• revs: a list of requested revisions from the same repository (optional; Kiln 2.7.5 and higher only)
• revOldest: revision of the oldest changeset to return (optional)
• nChangesetLimit: number of changesets to return, with a maximum of 100 (optional; defaults to 10)
• vcs (optional; defaults to "Hg"): the type of changesets to return: "Hg" or "Git"

and returns a list of the requested changesets corresponding to the revisions "revs". If revs is omitted, changeset records from the repository history, analogous to "hg log" are returned. If revOldest is omitted, the call returns "nChangesetLimit" records starting from the tip and working backward.

Api/{version}/Repo/{ixRepo}/History/{rev} (GET)

Requires read permissions to the repository. Returns the changeset-with-diffs record corresponding to the revision "rev" from the history, analogous to an amalgamation "hg diff" and "hg log". Make sure to pass "vcs=git" if the rev is a Git rev hash.

Api/{version}/Repo/{ixRepo}/File/{bpPath} (GET)

Requires read permissions to the repository. Takes

• rev: the revision to read the file from (optional; default to tip)
• fAnnotate: if true, returns annotation records as well (optional; defaults to false)

and returns the cat record corresponding to the file at "bpPath" at revision "rev", analogous to "hg cat". Note that "bpPath" must be an encoded byte path; see the API Idioms page for details.

Api/{version}/Repo/Related (GET)

• revTails: a list of revision tails

and returns a list of repository records that contains a tail from "revTails" and are readable by the user.

Api/{version}/Repo/{ixRepo}/Related (GET)

Requires read permissions to the repository. Returns a list of repository records that are related to the repository corresponding to "ixRepo" and are readable by the user.

Api/{version}/Repo/{ixRepo}/Manifest (GET)

Requires read permissions to the repository. Takes

• rev: the revision to read the manifest from (optional; defaults to tip)

and returns a list of manifest records at revision "rev".

Api/{version}/Repo/{ixRepo}/CaseAssociation/Create(POST)

Requires write permissions to the repository. Associates a list of changesets with a case or review. Takes

• revs: the list of revisions to associate
• ixBug: the case to associate

and returns the updated changesets. (Kiln 2.7.5 and higher only)

Api/{version}/Repo/{ixRepo}/CaseAssociation/Delete(POST)

Requires write permissions to the repository. Dissociates a list of changesets with a case or review. Takes

• revs: the list of revisions to dissociate
• ixBug: the case to dissociate

and returns the updated changesets. (Kiln 2.7.5 and higher only.)

Api/{version}/Repo/{ixRepo}/Tags (GET)

Requires read permissions to the repository. Returns an array of tag records that belong to ixRepo. (Kiln 2.7.5 and higher only)

Api/{version}/Repo/{ixRepo}/Tags/Create (POST)

Requires write permissions to the repository. Takes

• sName (required): the name of the tag
• rev (required): the revision to tag
• fForced (optional): if true, creates the tag even if a tag with the same sName already exists

Returns true on success, which does not guarantee the backend has added the tag yet.

This is an asynchronous call. You should poll Api/{version}/Repo/{ixRepo}/Tags until the tag is returned to determine when the backend has finished. (Kiln 3.1.537 and higher only)

Api/{version}/Repo/{ixRepo}/NamedBranches (GET)

Requires read permissions to the repository. Returns an array of named-branch records corresponding to the open named branches in the given repository. (Kiln 2.7.5 and higher only)

Api/{version}/Repo/{ixRepo}/Commit (POST)

Commits files to ixRepo. Files are committed directly to the repository and do not need to be pushed by the user. Uses multipart/form-data and takes

• ixPerson: the author of the commit (optional; defaults to current user)
• revParent1: the first parent changeset of the new commit (optional; defaults to tip)
• revParent2: the second parent changeset of the new commit; used when merging (optional; defaults to none)
• dt: the date of the commit (optional, defaults to the user's current day and time)
• sMessage: commit message
• <byte path of file to commit>: <file contents> (at least one file must be given)

and returns the new revision which does not guarantee the backend has added the changeset yet. This is an asynchronous call. You should poll Api/{version}/Repo/{ixRepo}/History/{the new rev} until the new changeset is returned to determine when the backend has finished. (Kiln 2.7.5 and higher only)

Api/{version}/Repo/{ixRepo}/Raw/History/{rev} (GET)

Requires read permissions to the repository. Returns a string corresponding to the changeset patch equivalent to the "hg export" or "git format-patch --stdout -1" commands. (Kiln 3.0.68 and higher only)

Api/{version}/Repo/{ixRepo}/Raw/File/{bpPath} (GET)

Requires read permissions to the repository. Takes

• rev: the revision to read from (optional; defaults to "tip")

and returns the contents of the file. Works for all files, including binary. Like Raw/History, it has a command analogue to "hg cat" or "git show". (Kiln 3.0.68 and higher only)

Errors

The following machine codes are errors that may be returned from these calls. See also Common Errors.

• ProblemWithBackend: there was an unknown problem with the backend.
• InvalidRepositoryGroup: invalid repository group.
• InvalidPermission: invalid default permission passed.
• CouldNotCreateRepo: unable to create the repository due to backend exception.
• CannotMakeCentralRepoABranch: you cannot convert a central repository into a branch repository.
• NoRepoToCompareTo: no repository passed to compare to for outgoing changesets.
• InvalidComparison: invalid repository to compare to for outgoing changesets.
• ChangesetNotFound: invalid changeset or changesets specified or occurred.
• PushFailNotStrictSubset: pushing to this repository would create a new head.
• PushFailNotRelated: the destination of the push contains changesets not in the source repository.
• PushFailCreatesNewHeads: pushing to this repository would create a new head.
• PushFailUnknown: unknown pushing error occurred.
• InvalidRange: an invalid range of changesets was specified for History.
• IsADirectory: File was called on a directory, not a file.
• FileNotFound: File was called on a file not found.
• InvalidRevisionTails: an empty list of revision tails was passed to Related.
• RepoNameAlreadyUsed: an identically named repository already exists in this group.
• RepoDescriptionTooLong: repo descriptions must be less than 200 characters long.
• InvalidBytePath: paths passed to the File API must be encoded byte paths
• DissociateReview: cannot dissociate a review from a changeset. (Cases and reviews in a different repository can be dissociated from a changeset but not reviews and changesets in the same repository.)
• CaseNotAssociated: case is not associated with the changeset and thus cannot be dissociated.
• CouldNotAssociatedCase: could not associate the case with the changeset
• CommitMessageRequired: a null or empty commit message was passed to Commit
• FileTooLarge: files must be less than or equal to 2097152 bytes
• NoFilesToCommit: at least one file must be passed to Commit
• CommitError: an error occurred while committing your file