timeline¶

vb timeline [WHEN] [CHECKIN|DATETIME] [OPTIONS]

Description¶

Print a summary of activity going backwards in date and time specified or from the current date and time if no arguments are given. The WHEN argument can be any unique abbreviation of one of these keywords:

before
after
descendants | children
ancestors | parents

The CHECKIN can be any unique prefix of 4 characters or more. You can also say current for the current version.

The following options affect XLSX, JSON, and PDF export:

before
after
descendants | children
ancestors | parents
-b|--branch
-c|--current-branch
-p|--path
-n|--limit
-F|--format
-v|--verbose

Options¶

-b, --branch BRANCH¶: Show only items on the branch named BRANCH

-c, --current-branch¶: Show only items on the current branch

-F, --format¶

Entry format. Values oneline, medium, and full get mapped to the full options below. Otherwise a string which can contain these placeholders:

%n  newline
%%  a raw %
%H  commit hash
%h  abbreviated commit hash
%a  author name
%d  date
%c  comment (NL, TAB replaced by space, LF erased)
%b  branch
%t  tags
%p  phase: zero or more of *CURRENT*, *MERGE*,
    *FORK*, *UNPUBLISHED*, *LEAF*, *BRANCH*
%fn file name (available when exporting file details)
%fs file size (available when exporting file details)
%ft file status (available when exporting file details)
%fH file artifact hash (available when exporting file details)
%fh abbreviated file artifact hash (available when exporting file details)

--oneline¶: Show only short hash and comment for each entry

--medium¶: Medium-verbose entry formatting

--full¶: Extra verbose entry formatting

-n, --limit N¶: If N is positive, output the first N entries. If N is negative, output the first -N lines. If N is zero, no limit. Default is -20 meaning 20 lines.

--offset P¶: Skip P changes

-p, --path PATH¶: Output items affecting PATH only. PATH can be a file or a sub directory.

-R REPO_FILE¶: Specifies the repository db to use. Default is the current check-out’s repository.

--sql¶: Show the SQL used to generate the timeline

-t, --type TYPE¶

Output items from the given types only, such as:

ci = file commits only
e  = technical notes only
f  = forum posts only
t  = tickets only
w  = wiki commits only

-v, --verbose¶: Output the list of files changed by each commit and the type of each change (edited, deleted, etc.) after the check-in comment.

-W, --width N¶: Width of lines (default is to auto-detect). N must be either greater than 20 or it must be zero 0 to indicate no limit, resulting in a single line per entry.

--export-xlsx PATH¶: Export matching check-ins to a Microsoft Excel (.xlsx) file.

--export-json PATH¶: Export matching check-ins to a JSON file.

--export-pdf DIR¶: Export matching check-ins as split PDF parts in DIR.

--export-pdf-part-size N Revisions per PDF part. Default is 1000. If PDF¶: export fails, try a smaller part size.

--export-pdf-font PATH¶: Font file used by PDF export. When omitted, the export-pdf-font setting is used. The default value of that setting is empty, so PDF export falls back to the built-in libHaru fonts unless the setting is configured.

--export-changes-format¶: Changes format for XLSX/JSON export: csv (default) or JSON.

--date format¶

Specify the output date format, Allowed values include:

iso         ISO-8601 timestamp.
short       Date only, YYYY-MM-DD.
relative    Human-readable age ("2 hours ago").
rfc         RFC822 format.

Examples¶

Init and open a repository

$ vb init timeline_repo.vbyte
project-id: cf6960f7b2313ca13ba8db1311003b17ebe79bdd
server-id:  2b4b84e711f41aa6647eabb8fa704314bb9b7576
admin-user: ubuntu (initial remote-access password is "W4shgMzE2D")
$ vb open -f timeline_repo.vbyte
project-name: <unnamed>
repository:   /tmp/sphinx_tests/5fe847c6/timeline_repo/timeline_repo.vbyte
local-root:   /tmp/sphinx_tests/5fe847c6/timeline_repo/
config-db:    /tmp/sphinx_tests/5fe847c6/.visionbyte
project-code: cf6960f7b2313ca13ba8db1311003b17ebe79bdd
checkout:     610cf1b82eb2f8c607aa844d74454414f6c49a7a 2026-04-07 06:51:44 UTC
tags:         trunk
comment:      initial empty check-in (user: ubuntu)
check-ins:    1

Make a few commits

$ vb sys echo "a" > a.txt
$ vb add a.txt
ADDED  a.txt
$ vb ci -m "add a.txt"
Committed version: 512829f478a801505bb3d900300421ba03e08e5aabf2d691a49e3508c8927e48

$ vb sys echo "b" > b.txt
$ vb add b.txt
ADDED  b.txt
$ vb ci -m "add b.txt"
Committed version: 78522a5ff29d1d88aa406bd867089dc7f0942907edd4fd097604de679974fd64

Show recent activity (compact view)

$ vb timeline --oneline -n 5
78522a5ff2 add b.txt
512829f478 add a.txt
610cf1b82e initial empty check-in
+++ no more data (3) +++

Focus on the current branch and a single file

$ vb timeline --current-branch -p a.txt -v -n 5
=== 2026-04-07 ===
06:51:44 [512829f478] add a.txt (user: ubuntu tags: trunk)
   ADDED a.txt
+++ no more data (1) +++

View timeline before current check-in

$ vb timeline before current --type ci -n 5
=== 2026-04-07 ===
06:51:44 [78522a5ff2] *CURRENT* add b.txt (user: ubuntu tags: trunk)
06:51:44 [512829f478] add a.txt (user: ubuntu tags: trunk)
06:51:44 [610cf1b82e] initial empty check-in (user: ubuntu tags: trunk)
+++ no more data (3) +++

Customize the output format

$ vb timeline --format "%h %d %a %c" -n 3
78522a5ff2 2026-04-07 06:51:44 ubuntu add b.txt
512829f478 2026-04-07 06:51:44 ubuntu add a.txt
610cf1b82e 2026-04-07 06:51:44 ubuntu initial empty check-in
+++ no more data (3) +++

Export to XLSX for sharing

$ vb timeline --export-xlsx timeline.xlsx --date iso --export-changes-format csv -n 5
Exporting XLSX             1/3        33%Exporting XLSX             2/3        66%Exporting XLSX             3/3       100%

Export to JSON for tooling

$ vb timeline --export-json timeline.json --date rfc --export-changes-format json -n 5
Exporting JSON             1/3        33%Exporting JSON             2/3        66%Exporting JSON             3/3       100%
$ vb sys cat timeline.json
{
	"items":[
		{
			"revision":"78522a5ff29d1d88aa406bd867089dc7f0942907edd4fd097604de679974fd64",
			"author":"ubuntu",
			"comment":"add b.txt",
			"tags":"trunk",
			"date":"Tue, 7 Apr 2026 06:51:44 +0000"
		},
		{
			"revision":"512829f478a801505bb3d900300421ba03e08e5aabf2d691a49e3508c8927e48",
			"author":"ubuntu",
			"comment":"add a.txt",
			"tags":"trunk",
			"date":"Tue, 7 Apr 2026 06:51:44 +0000"
		},
		{
			"revision":"610cf1b82eb2f8c607aa844d74454414f6c49a7a998e29204a9e7f5e7b9fe627",
			"author":"ubuntu",
			"comment":"initial empty check-in",
			"tags":"trunk",
			"date":"Tue, 7 Apr 2026 06:51:44 +0000"
		}
	],
	"limit":5,
	"count":3,
	"total":3
}