Documentation

Get started with ForgeVCS

Everything you need to install, configure, and version your projects with the forge CLI.

Introduction

ForgeVCS is a version control system written in C++20 with its own repository format (.forge/) and a CLI named forge. It uses Zstd compression and BLAKE3 hashing to deliver fast operations and cryptographic integrity checks on every stored object.

Requirements

CMake 3.23+
A C++20 compiler (MSVC, clang, or gcc)
vcpkg (recommended) with these dependencies: zstd, blake3, and cpp-httplib

Installation

Build the binary from source using CMake. On Windows, via PowerShell:

powershell

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -G "Visual Studio 17 2022" -A x64
cmake --build build -j

The output binary will be at build/apps/forge/forge.exe. Add that path to your PATH to use the forge command globally.

Quick start

Create a repository, add a file, and ship your first commit:

$ mkdir demo
$ cd demo
$ forge init
$ echo hello > a.txt
$ forge add a.txt
$ forge commit --m="first commit"
$ forge log
$ forge status

Configuration

Before your first commit, set your name and email globally:

$ forge config --global user.name "Your Name"
$ forge config --global user.email "you@example.com"
$ forge config --list

Commands

Use forge help [command] to see details for any command directly from the terminal.

Repository

forge init	Initializes a new .forge/ repository in the current directory.
forge add <paths...>	Adds files to the staging area.
forge status	Shows the current state of the working tree.
forge diff	Displays uncommitted changes.
forge commit --m=<msg>	Creates a commit with the given message.
forge log	Lists the commit history (use --oneline for a compact view).

Configuration

forge config --list	Lists every active configuration value.
forge config --global user.name "Name"	Sets the author name globally.
forge config --global user.email "you@example.com"	Sets the author email globally.

Branches and history

forge branch [name]	Lists branches or creates a new one.
forge branch -d <name>	Deletes the given branch.
forge switch <branch>	Switches to another branch (alias: checkout).
forge checkout -b <branch>	Creates and switches to a new branch.
forge checkout -- <path>	Discards local changes in a path.
forge reset [--hard] <commit>	Moves HEAD to a commit (use --hard to reset the tree).
forge reset HEAD <path...>	Removes files from the staging area.
forge merge <branch> [--m=<msg>]	Merges another branch into the current one.
forge rebase <upstream> [--hard]	Rebases the current branch onto the upstream.

Stash, tags and submodules

forge tag <name>	Creates a tag at the current commit.
forge stash push [--m=<msg>]	Saves changes to a stash.
forge stash list	Lists available stashes.
forge stash apply	Applies the latest stash without removing it.
forge stash pop	Applies and removes the latest stash.
forge submodule add <url> <path>	Adds a submodule to the repository.
forge submodule status	Shows the state of submodules.

Remotes

forge remote add <name> <path>	Adds a remote (HTTP or local).
forge remote list	Lists all configured remotes.
forge clone <path> [dest]	Clones a repository into the destination.
forge fetch [remote] [--token=<t>]	Fetches objects from a remote.
forge push [remote] [--token=<t>]	Pushes commits to a remote.
forge pull [remote]	Equivalent to fetch + merge.
forge serve --http=:8080	Starts an HTTP server hosting the repository.
forge serve --stdio --repo=<p>	Server in stdio mode (for use over SSH).

Interoperability

forge import-git <repo> [dest]	Imports a snapshot from a Git repository.
forge export-git [dest]	Exports the Forge repository as a Git snapshot.

Branches and merges

Create a feature branch, work on it, and integrate the result back into the main branch:

# create and switch to a new branch
$ forge checkout -b feature/login
 
# ... edit files ...
$ forge add .
$ forge commit --m="feat: login screen"
 
# go back to main and integrate the changes
$ forge switch main
$ forge merge feature/login --m="merge: login"

Stash and tags

Save in-progress changes or mark important versions:

# stash uncommitted changes
$ forge stash push --m="wip: quick tweaks"
$ forge stash list
$ forge stash pop
 
# mark a version
$ forge tag v1.0.0

Remotes

ForgeVCS uses a native protocol over HTTP. Start a server pointing at a repository and add it as a remote on the client:

# on the server
$ forge serve --http=:8080 --repo=/path/to/repo
 
# on the client
$ forge remote add origin http://127.0.0.1:8080
$ forge fetch origin
$ forge push origin

There's also a stdio mode (forge serve --stdio) designed to be used behind an SSH forced-command.

Authentication

To require authentication, set the FORGE_TOKEN variable on the server. Clients must send the same token via --token or as an environment variable:

# server
$ export FORGE_TOKEN="my-secret-token"
$ forge serve --http=:8080 --repo=/path/to/repo
 
# client
$ forge push origin --token=my-secret-token
# or
$ export FORGE_TOKEN="my-secret-token"
$ forge push origin

The server validates the Authorization: Bearer <token> header on every request.

Git interoperability

The import-git and export-git commands let you move projects between Git and Forge as snapshots — this is not a full history conversion.

# bring a Git project into Forge
$ forge import-git /path/to/git-repo ./my-project
 
# export a Forge repository as a Git snapshot
$ forge export-git ./export-git

Tip

Whenever you're unsure about a command, run forge help <command>. The built-in help covers every flag and example directly in the terminal.