Staging & Committing

Prefer a visual workflow? See Changes in the web UI.

The Staging Workflow

Git-Semantic uses the same two-step workflow as Git: stage changes first, then commit them. This gives you control over exactly what goes into each commit.

Working Tree → (vc add) → Staging Area → (vc commit) → Commit History

Working tree: The current state of your context tree files on disk
Staging area: A snapshot of changes queued for the next commit
Commit history: The permanent record of all committed snapshots

Check Working Tree Status

See what has changed in your context tree since the last commit. This is usually the first command you run to understand the current state.

brv vc status

/vc status

What Status Shows

The output includes several sections:

Section	Description
Current branch	The branch you are on (e.g., `main`, `feature/auth`)
Tracking info	How many commits you are ahead/behind the upstream remote branch
Merge state	Whether a merge is currently in progress
Staged changes	Files added to the staging area, ready to be committed
Unstaged changes	Files that have been modified but not yet staged
Untracked files	New files that are not being tracked by version control
Unmerged paths	Files with conflicts during an active merge
Conflict markers	Files still containing unresolved conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)

Run vc status frequently to stay aware of your working state — especially before committing, merging, or switching branches.

Stage Changes

Add files to the staging area to include them in the next commit. Only staged changes are included when you run vc commit.

Stage All Changes

brv vc add .

/vc add .

The . stages everything — all modified, deleted, and new (untracked) files in the context tree.

Stage Specific Files

# Stage a single file
brv vc add notes.md

# Stage multiple files
brv vc add design/architecture.md api/endpoints.md

# Stage an entire directory
brv vc add authentication/

/vc add notes.md
/vc add design/architecture.md api/endpoints.md
/vc add authentication/

Default Behavior

When no paths are provided, vc add defaults to staging everything (equivalent to vc add .).

Paths are relative to the context tree root. You can stage individual files, multiple files, or entire directories.

Create a Commit

Save staged changes as a new commit with a descriptive message. Each commit is an immutable snapshot of your context tree at that point in time.

brv vc commit -m "add authentication best practices"

/vc commit -m add authentication best practices

Commit Message

The -m flag is required — every commit needs an explicit message. There is no auto-generated commit message. Write messages that describe what changed and why:

# Good messages
brv vc commit -m "add JWT token rotation patterns"
brv vc commit -m "reorganize database domain into separate topics"
brv vc commit -m "update API design context after v2 migration"

# Avoid vague messages
brv vc commit -m "update"
brv vc commit -m "changes"

What a Commit Records

Each commit stores:

Field	Description
SHA	A unique ID for this commit (displayed as a short 7-character code)
Message	The commit message you provided
Author name	From `vc config user.name`
Author email	From `vc config user.email`
Timestamp	When the commit was created
Parent(s)	Reference to the previous commit(s)

Requirements

Author configured: Both user.name and user.email must be set via vc config
Something staged: At least one file must be in the staging area

Error Handling

Error	Cause	Solution
`USER_NOT_CONFIGURED`	`user.name` or `user.email` not set	Run `vc config user.name` and `vc config user.email`
`NOTHING_STAGED`	No files in the staging area	Run `vc add` to stage changes first
`GIT_NOT_INITIALIZED`	VC not initialized	Run `vc init` first

View Commit History

Browse the commit log to see what has changed over time.

# Show recent commits (default: last 10)
brv vc log

# Show more commits
brv vc log --limit 20

# Show commits on a specific branch
brv vc log feature/auth

# Show commits from all branches
brv vc log --all

# Combine flags
brv vc log --all --limit 50

/vc log
/vc log --limit 20
/vc log feature/auth
/vc log --all
/vc log --all --limit 50

Log Entry Fields

Each entry in the log includes:

Field	Description
SHA	The commit’s unique ID
Message	The commit message
Author	Name and email of who made the commit
Timestamp	When the commit was created

Arguments & Flags

Argument/Flag	Default	Description
`[branch]`	Current branch	Show history for a specific branch
`--limit`	`10`	Maximum number of commits to display
`--all`, `-a`	`false`	Show commits from all branches, not just the current one

Error Handling

Error	Cause	Solution
`NO_COMMITS`	No commits exist yet	Create your first commit with `vc add` and `vc commit`
`BRANCH_NOT_FOUND`	Specified branch doesn’t exist	Check branch name with `vc branch`

Unstage Files

Remove files from the staging area without discarding the actual changes. The files remain modified in your working tree.

# Unstage all files
brv vc reset

# Unstage specific files
brv vc reset notes.md

# Unstage multiple files
brv vc reset design/architecture.md api/endpoints.md

/vc reset
/vc reset notes.md
/vc reset design/architecture.md api/endpoints.md

This is the equivalent of git reset (without --soft or --hard) — it only affects the staging area, not your working tree.

Use vc reset when you accidentally staged files you didn’t intend to commit. Your changes are preserved — only the staging state is cleared.

Undo Commits

Roll back commits using --soft or --hard reset. Both move HEAD to a previous commit, but they differ in what happens to your changes.

Soft Reset

Moves HEAD back but keeps all changes staged. The changes from the undone commit(s) remain in the staging area, ready to be re-committed.

# Undo the last commit, keep changes staged
brv vc reset --soft HEAD~1

# Undo the last 3 commits
brv vc reset --soft HEAD~3

/vc reset --soft HEAD~1
/vc reset --soft HEAD~3

Use cases:

Re-writing a commit message (soft reset, then commit again with a new message)
Combining multiple commits into one (soft reset several commits, then commit once)
Removing a commit but keeping the work

Hard Reset

Moves HEAD back and discards all changes. Your working tree and staging area are reset to match the target commit.

# Discard all uncommitted changes (reset to current HEAD)
brv vc reset --hard

# Undo the last commit and discard changes
brv vc reset --hard HEAD~1

# Reset to a specific commit
brv vc reset --hard HEAD~3

/vc reset --hard
/vc reset --hard HEAD~1
/vc reset --hard HEAD~3

--hard reset permanently discards changes. There is no way to recover the discarded changes after a hard reset. Make sure you don’t need the changes before running this command.

Use cases:

Completely undoing a bad commit
Resetting to match the remote state after a failed merge
Starting over from a known good state

Comparison

Mode	HEAD	Staging Area	Working Tree
`vc reset` (no flag)	Unchanged	Cleared	Unchanged
`vc reset --soft`	Moved back	Keeps changes	Unchanged
`vc reset --hard`	Moved back	Cleared	Cleared

--soft and --hard are mutually exclusive — you cannot use both in the same command.

Error Handling

Error	Cause	Solution
`INVALID_REF`	The ref (e.g., `HEAD~5`) doesn’t exist	Check how many commits exist with `vc log`
`NOTHING_TO_RESET`	No changes to unstage	Nothing to do — working tree is clean

Common Workflows

Basic Edit-Stage-Commit Cycle

The day-to-day workflow for tracking context changes:

# 1. Check what's changed
brv vc status

# 2. Stage your changes
brv vc add .

# 3. Commit with a descriptive message
brv vc commit -m "update API design patterns for v2 endpoints"

# 4. Verify the commit
brv vc log --limit 1

Selective Staging

When you’ve made changes across multiple domains but want separate commits:

# Stage and commit authentication changes
brv vc add authentication/
brv vc commit -m "add OAuth2 flow documentation"

# Stage and commit database changes separately
brv vc add database/
brv vc commit -m "update connection pooling best practices"

Rewriting a Commit Message

If you made a typo or want a better message:

# Undo the last commit but keep changes staged
brv vc reset --soft HEAD~1

# Re-commit with a new message
brv vc commit -m "add JWT token rotation patterns for auth service"

Squashing Multiple Commits

Combine several small commits into one:

# Soft reset to undo the last 3 commits (changes stay staged)
brv vc reset --soft HEAD~3

# Create a single commit with all those changes
brv vc commit -m "reorganize authentication domain with new subtopics"

​The Staging Workflow

​Check Working Tree Status

​What Status Shows

​Stage Changes

​Stage All Changes

​Stage Specific Files

​Default Behavior

​Create a Commit

​Commit Message

​What a Commit Records

​Requirements

​Error Handling

​View Commit History

​Log Entry Fields

​Arguments & Flags

​Error Handling

​Unstage Files

​Undo Commits

​Soft Reset

​Hard Reset

​Comparison

​Error Handling

​Common Workflows

​Basic Edit-Stage-Commit Cycle

​Selective Staging

​Rewriting a Commit Message

​Squashing Multiple Commits

The Staging Workflow

Check Working Tree Status

What Status Shows

Stage Changes

Stage All Changes

Stage Specific Files

Default Behavior

Create a Commit

Commit Message

What a Commit Records

Requirements

Error Handling

View Commit History

Log Entry Fields

Arguments & Flags

Error Handling

Unstage Files

Undo Commits

Soft Reset

Hard Reset

Comparison

Error Handling

Common Workflows

Basic Edit-Stage-Commit Cycle

Selective Staging

Rewriting a Commit Message

Squashing Multiple Commits