Jump to:

Introduction

These requests return overview-level information about various types of changes. The response payload differs for each artifact type, and the current structures are almost certainly not "final" (e.g. we are still undecided on how/whether to handle artifact links within commit messages and whatnot).

By default the entries are returned in chronological order from newest to oldest, but some options might change that.

FIXME (20120623): we have some inconsistent type vs. eventType in the result sets. type is the current preferred choice (and it seems unlikely that eventType is actually used in any client code). We don't actually need either one (but a use for type is easily envisioned), and we may get rid of both.

Common request options (via CLI, GET or POST.payload):

limit=integer limits the number of entries in the response. Default is unspecified (but is "quite possibly 20 or so"). A limit value of 0 disables any limit, fetching all entries (which can take a really long time and might overload clients which have very limited memory).
CLI mode: --limit|-n #
after="YYYY-MM-DD[ HH:mm:ss]" limits the search to items on or after the given date string. Reverses the normal timeline sort order. Alias: "a". Only one of "after" or "before" can be used, and if both are specified then which one takes precedence is unspecified.
CLI mode: --after|-a "DATE[ TIME]"
before="YYYY-MM-DD[ HH:mm:ss]" limits the search to items on or before the given date string.
CLI mode: `--before|-b "DATE[ TIME]"
TODOs, still to be ported from the HTML-mode timeline:
- circa=DATETIME
- tag=string
- related=tag name
- string=search string

Branch Timeline

Status: partially implemented but undocumented because the utility of the current impl is under question. It also doesn't understand most of the common timeline options.

Checkin Timeline

Status: implemented 201109xx

Required privileges: "o"

Request: /json/timeline/checkin

Response payload example:

{
"limit": number, /* if not set, all records are returned */
"timeline":[{
  "uuid":"be700e84336941ef1bcd08d676310b75b9070f43",
  "timestamp":1317094090,
  "comment":"Added /json/timeline/ci showFiles to ajax test page.",
  "user":"stephan",
  "isLeaf":true,
  "bgColor":null, /* not quite sure why this is null? */
  "type":"ci",
  "parents": ["primary parent hash", "...other parent hashes"],
  "tags":["json"],
  "files":[{
    "name":"ajax/index.html",
    "uuid":"9f00773a94cea6191dc3289aa24c0811b6d0d8fe",
    "parent":"50e337c33c27529e08a7037a8679fb84b976ad0b",
    "state":"modified"
   }]
 },...]
}

(Achtung: the parents property was called prevUuid prior to 20120316.)

The parents property lists the checkins which were parents of this commit. The first entry in the array is the "primary parent" - the one which was not involved in a merge with the child.

Request options:

files=bool toggles the addition of a "files" array property which contains objects describing the files changed by the commit, including their hash, previous hash, and state change type (modified, added, or removed). (“uuid” here means hash)
CLI mode: --show-files|-f
tag|branch=string selects only entries with the given tag or "close to" the given branch. Only one of these may be specified and if both are specified, which one takes precedence is unspecified. If the given tag/branch does not exist, an error response is generated. The difference between the two is subtle - tag filters only on the given tag (analog to the HTML interface's "r" option) whereas branch can also return entries from other branches which were merged into the requested branch (analog to the HTML interface's "b" option). If one of these is specified, the response payload will contain a "tag" or "branch" property with the tag/branch name given by the client.

Technote (formerly Event) Timeline

Status: implemented 20180803

Required privileges: "j"

Request:

/json/timeline/technote
DEPRECATED: /json/timeline/event (technotes were formerly called events)

Response payload example:

{
"limit": number, /* if not set, all records are returned */
"timeline":[{
  "name":"8d18bf27e9f9ff8b9017edd55afc35701407d418",
  "uuid":"b23962c88c123924a77fd663e91af094780d920a",
  "timestamp":1478376113,
  "comment":"Style update due to [8d880f0bb4]",
  "user":"andygoth",
  "eventType":"e"
 },...]
}

The uuid of each entry can be passed to /json/artifact to fetch the raw event content.

Ticket Timeline

Status: implemented 201109xx

Required privileges: "r" or "o"

Request: /json/timeline/ticket

Response payload example:

{
  "limit": number, /* if not set, all records are returned */
  "timeline":[{
    "uuid":"5065a5da060e181da49a618f8ae5dc245215e95b",
    "timestamp":1316511322,
    "user":"stephan",
    "eventType":"t",
    "comment":"Ticket [b64435dba9] &lt;i&gt;How to...&lt;/i&gt;",
    "briefComment":"Ticket [b64435dba9]: 2 changes",
    "ticketUuid":"b64435dba9cceb709bd54fbc5883884d73f93491"
  },...]
}

Notice that there are two hashes for tickets - uuid is the change hash and ticketUuid is the actual ticket’s hash. This is an unfortunate discrepancy vis-a-vis the other timeline entries, which only have one hash. We may want to swap uuid to mean the ticket hash and change uuid to commitHash.

Wiki Timeline

Status: implemented 201109xx

Required privileges: "j" or "o"

Requests:

/json/timeline/wiki
/json/wiki/timeline (alias)

Response payload example:

{
"limit": number, /* if not set, all records are returned */
"timeline":[{
  "uuid":"4b2026f06eb48eaf187209fcb05ba5438c3b0ef0",
  "timestamp":1331351121,
  "comment":"Changes to wiki page [Page3]",
  "user":"stephan",
  "eventType":"w"
 },...]
}

The uuid of each entry can be passed to /json/artifact or /json/wiki/get?uuid=... to fetch the raw page and the hash of the parent version.

Fossil

JSON API: /timeline

Introduction

Branch Timeline

Checkin Timeline

Technote (formerly Event) Timeline

Ticket Timeline

Wiki Timeline