Quick Start¶

This guide helps you get productive quickly with the VisionByte distributed version control system.

Installation¶

Verify that VisionByte is installed and available on your PATH:

$ vb version
VisionByte version 2.26 [1205ec86cb] 2025-04-30 16:57:32 UTC
Copyright © 2025 Softbridge Inc. All rights reserved.

Basic Workflow¶

VisionByte manages projects with two core concepts:

Repository — usually a single file named FILENAME.vbyte that stores the complete history.
Working copy — a directory containing a snapshot of the repository for day-to-day edits.

A typical flow:

Create or clone a repository (init or clone).
Create/open a working copy for that repository (open).
Make changes and record them in the repository (configure, add, commit, update, etc.).

Starting a New Project¶

Create a New Repository

To start a project from scratch, create an empty repository file:

vb init PATH

Example (local)

Create demo.vbyte and keep the repo file alongside your docs build. We initialize the repo but do not open it yet:

$ vb init demo.vbyte
project-id: c4eed8564835fa639b9e8e74ee30560e74717e96
server-id:  8c7f1f0b82a47d9aab3d33228539901fea8a594b
admin-user: ubuntu (initial remote-access password is "4nfWFdsAVk")

You may name the repository file however you like and place it anywhere. By default, the repo’s location is the current directory.

For full initialization options, see init.

Clone a Repository

Clone a remote repository:

vb clone URI PATH

Most commands operate on a local copy of the repository. If the repository is remote, clone it first.

Example (remote, illustrative)

$ vb clone https://visionbyte-scm.org/project.vbyte project.vbyte
Rebuilding repository meta-data...
100% complete
...

If the remote requires authentication, include your user name in the URL; you’ll be prompted for a password:

$ vb clone https://username@code.softbridge.com/projectz projectz.vbyte
password for https://username@code.softbridge.com/projectz: ********
... 100% complete

Working Copy¶

Create a working copy from a repository using open:

vb open REPOSITORY --workdir DIR

This creates a working copy for REPOSITORY inside DIR (created if missing). If you omit --workdir DIR, the working copy will be placed in the current directory.

Example (open into current directory)

Open demo.vbyte into the current directory of this example workspace so subsequent commands can run in-place:

$ vb open --nested --workdir . demo.vbyte
project-name: <unnamed>
repository:   /tmp/sphinx_tests/27182049/demo/demo.vbyte
local-root:   /tmp/sphinx_tests/27182049/demo/
config-db:    /tmp/sphinx_tests/27182049/.visionbyte
project-code: c4eed8564835fa639b9e8e74ee30560e74717e96
checkout:     7b2b5bbb5c029020e71fe772427a9c61df548844 2026-03-26 07:18:53 UTC
tags:         trunk
comment:      initial empty check-in (user: ubuntu)
check-ins:    1

Basic Operations¶

Changes¶

After you have a working copy, create or edit files as needed, then stage them for commit.

Examples

Add a new file (add). Here we create the file first, then add it:

$ vb sys echo "VisionByte Quick Start" > README.md
$ vb add README.md
ADDED  README.md

Remove a tracked file (rm). The file remains in history:

$ vb sys echo "legacy" > old.txt
$ vb add old.txt
ADDED  old.txt
$ vb ci -m "track old.txt for removal demo"
Committed version: c110ca4e3c56726a946957e7cd2f9e423bbdf99ed7f4366721c7e0fbcf1b9185
$ vb rm old.txt
DELETED old.txt

Add newly created files and drop missing ones in one sweep (addremove):

$ vb sys echo "temp data" > temp.txt
$ vb addremove
ADDED  temp.txt
added 1 files, deleted 0 files

Commit¶

Record your staged changes in the repository with commit:

vb commit|ci -m "message" [PATH...]

Use -m to provide the commit message in-place. If you omit PATH..., VisionByte commits the whole working copy.

Example

$ vb ci -m "initial content and housekeeping"
Committed version: 9af95273049416ae1e8c238121435c3eddc06b66a7f477a791c4f5f0452bb57a

For detailed options, see commit.

Note

VisionByte defaults to autosync mode, which pushes commits to the configured remote immediately (if you have write permission).

Update¶

Bring your working copy to a specific revision, branch, tag, or time using update:

vb update VERSION

If VERSION is omitted, VisionByte updates to the tip of the current branch.

Examples

Update to the latest on the current branch:

$ vb update
UPDATE work2.txt
REMOVE work3.txt
ADD work3/work3.txt
ADD work4.txt
-------------------------------------------------------------------------------
updated-from: 93abb4c005a71800fe95d68f81144ff9ff89a9a8 2024-07-23 07:08:16 UTC
updated-to:   8aa0b7b6467217cf1a0a9f6fb04f9b7aa904b8ca 2024-07-23 07:13:26 UTC
tags:         trunk
...

Update to a specific commit (replace with an actual hash from your history):

$ vb update 93abb4c005
UPDATE work2.txt
ADD work3.txt
REMOVE work3/work3.txt
REMOVE work4.txt
-------------------------------------------------------------------------------
updated-from: 8aa0b7b6467217cf1a0a9f6fb04f9b7aa904b8ca 2024-07-23 07:13:26 UTC
updated-to:   93abb4c005a71800fe95d68f81144ff9ff89a9a8 2024-07-23 07:08:16 UTC
tags:         trunk
...

See update for more detail.

Note

With autosync enabled, update first pulls remote changes into your local repository and then merges them into your working copy.

History¶

Inspect the project’s history (timeline):

vb timeline

Example

$ vb timeline
=== 2026-03-26 ===
07:18:53 [9af9527304] *CURRENT* initial content and housekeeping (user: ubuntu tags: trunk)
07:18:53 [c110ca4e3c] track old.txt for removal demo (user: ubuntu tags: trunk)
07:18:53 [7b2b5bbb5c] initial empty check-in (user: ubuntu tags: trunk)
+++ no more data (3) +++

Undo / Redo¶

If a recent operation produced an unwanted state, use undo to revert the last reversible change, or redo to reapply it.

vb undo [OPTIONS] [PATH...]
vb redo [OPTIONS] [PATH...]

Operations eligible for undo include:

vb update
vb merge
vb revert
vb stash pop|apply|drop|goto
vb clean

Example

Perform and then undo/redo a merge:

$ vb branch new feature-login trunk
New branch: 4704d35070108b72c0adb6b1bb0654cd9ff5282e6627e7df2d6dc0d68093dd83
$ vb update feature-login
-------------------------------------------------------------------------------
checkout:     4704d35070108b72c0adb6b1bb0654cd9ff5282e 2026-03-26 07:18:53 UTC
tags:         feature-login
comment:      Create new branch named "feature-login" (user: ubuntu)
changes:      None. Already up-to-date.
$ vb sys echo "login WIP" >> README.md
$ vb ci -m "start login feature"
Committed version: 8ad379d99597ea9c7336da42f5a15ae16e87a6bbd144bb86fd6643ea37fbc180
$ vb update trunk
UPDATE README.md
-------------------------------------------------------------------------------
updated-from: 8ad379d99597ea9c7336da42f5a15ae16e87a6bb 2026-03-26 07:18:53 UTC
updated-to:   9af95273049416ae1e8c238121435c3eddc06b66 2026-03-26 07:18:53 UTC
tags:         trunk
comment:      initial content and housekeeping (user: ubuntu)
changes:      1 file modified.
 "vb undo" is available to undo changes to the working checkout.
$ vb merge feature-login
UPDATE README.md
 "vb undo" is available to undo changes to the working checkout.

$ vb undo
UNDO   README.md

$ vb redo
REDO   README.md

Revert¶

Discard local edits and restore content from the repository (revert). Specify paths to revert specific files:

vb revert [OPTIONS] [PATH...]

Example

Revert accidental edits to README.md:

$ vb sys echo "oops" >> README.md
$ vb revert README.md
REVERT   README.md
 "vb undo" is available to undo changes to the working checkout.

Branching¶

Create a Branch¶

trunk is the default mainline branch. You can develop on feature branches and merge them back later.

Create a new branch while committing (commit):

vb commit --branch NEW_BRANCH_NAME

Or create a branch explicitly before editing (branch):

vb branch new NEW_BRANCH_NAME BASIS

Examples

View pending changes:

$ vb sys echo "notes" >> README.md
$ vb changes
EDITED     README.md
EXTRA      old.txt
MERGED_WITH 8ad379d99597ea9c7336da42f5a15ae16e87a6bbd144bb86fd6643ea37fbc180

Commit those changes onto a new branch v2.0:

$ vb commit --branch v2.0 -m "cut v2.0 branch" --no-warnings
Committed version: f6c970e82bafd08026669c706829790ecb97bce6865acd10e0e85ca6b3fe3e62

List branches and switch between them:

$ vb branch
   feature-login
   trunk
 * v2.0

$ vb update v2.0
-------------------------------------------------------------------------------
checkout:     f6c970e82bafd08026669c706829790ecb97bce6 2026-03-26 07:18:54 UTC
tags:         v2.0
comment:      cut v2.0 branch (user: ubuntu)
changes:      None. Already up-to-date.

Note

The current branch is marked with an asterisk (*). Private branches are prefixed with a hash (#).

Warning

Commit your work on the branch you are editing before switching branches. Otherwise, your changes will be recorded on the branch you switch to.

Merge Branches¶

To merge a branch into trunk:

# Switch to trunk:
vb update trunk

# Merge the v2.0 branch:
vb merge v2.0

# Commit the merge:
vb commit -m "merge v2.0"

Example

$ vb merge v2.0
MERGE README.md
 "vb undo" is available to undo changes to the working checkout.

$ vb commit -m "merge v2.0 into trunk"
Committed version: 1d48f67a5ba75b2f20f6c222cfb04be1e55dc437c61bf1702b954904f72565ea

This command merges the branch being merged into the working copy of another branch; it does not change the repository itself. You must run a separate commit to record the merge in the repository so the changes persist and your teammates can see them. Before doing so, you can run tests to verify that the merge doesn’t introduce logical errors in the code.