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: 31b58dba7971bdb29e9a1e6cc9fcdafcc172de69
server-id:  5b7d9290afdb7e5eadc6a2b30515d33388efceb4
admin-user: ubuntu (initial remote-access password is "iAZ3cTyXGK")
$ 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: 31b58dba7971bdb29e9a1e6cc9fcdafcc172de69
checkout:     e94df4894d7b683f4db60d9376e14af1e5cb95ae 2026-03-31 13:00:45 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: b91b03cdf6acf20b448c1063d7e0f31b7090078385ac68c65bee52c593db3d2e

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

Show recent activity (compact view)

$ vb timeline --oneline -n 5
c1e66595c0 add b.txt
b91b03cdf6 add a.txt
e94df4894d 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-03-31 ===
13:00:45 [b91b03cdf6] 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-03-31 ===
13:00:45 [c1e66595c0] *CURRENT* add b.txt (user: ubuntu tags: trunk)
13:00:45 [b91b03cdf6] add a.txt (user: ubuntu tags: trunk)
13:00:45 [e94df4894d] 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
c1e66595c0 2026-03-31 13:00:45 ubuntu add b.txt
b91b03cdf6 2026-03-31 13:00:45 ubuntu add a.txt
e94df4894d 2026-03-31 13:00:45 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":"c1e66595c04c84cb34c0783f17a139cb1ec08b8a887ca99624b12f21030e60f8",
			"author":"ubuntu",
			"comment":"add b.txt",
			"tags":"trunk",
			"date":"Tue, 31 Mar 2026 13:00:45 +0000"
		},
		{
			"revision":"b91b03cdf6acf20b448c1063d7e0f31b7090078385ac68c65bee52c593db3d2e",
			"author":"ubuntu",
			"comment":"add a.txt",
			"tags":"trunk",
			"date":"Tue, 31 Mar 2026 13:00:45 +0000"
		},
		{
			"revision":"e94df4894d7b683f4db60d9376e14af1e5cb95ae816207717445d90edf588d63",
			"author":"ubuntu",
			"comment":"initial empty check-in",
			"tags":"trunk",
			"date":"Tue, 31 Mar 2026 13:00:45 +0000"
		}
	],
	"limit":5,
	"count":3,
	"total":3
}