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.
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
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
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
- 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.
- 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"
