Skip to main content
wit provides full support for remote Git operations, allowing you to collaborate with others using any Git hosting service including GitHub, GitLab, Bitbucket, or self-hosted servers.

​
Quick Reference

CommandDescription
wit clone <url>Clone a repository
wit remote add <name> <url>Add a remote
wit fetch [remote]Download objects from remote
wit pull [remote]Fetch and merge
wit push [remote] [branch]Upload changes to remote

​
Clone

Clone a repository from a remote URL: 
# Clone into a new directory
wit clone https://github.com/user/repo.git

# Clone into a specific directory
wit clone https://github.com/user/repo.git my-project

# Clone into current directory
wit clone https://github.com/user/repo.git .

​
Clone Options

# Clone a specific branch
wit clone -b develop https://github.com/user/repo.git

# Shallow clone (faster, less history)
wit clone --depth 1 https://github.com/user/repo.git

# Bare clone (no working directory)
wit clone --bare https://github.com/user/repo.git

# Clone without checking out
wit clone -n https://github.com/user/repo.git
OptionDescription
--depth <n>Create a shallow clone with only n commits of history
-b, --branch <name>Clone only the specified branch
--bareCreate a bare repository (no working directory)
-n, --no-checkoutDon’t checkout HEAD after cloning
-o, --origin <name>Use <name> instead of ‘origin’ for the remote
--single-branchClone only one branch

​
Remotes

Manage remote repository connections: 
# List all remotes
wit remote

# List remotes with URLs
wit remote -v

# Add a new remote
wit remote add origin https://github.com/user/repo.git
wit remote add upstream https://github.com/original/repo.git

# Remove a remote
wit remote remove upstream

# Rename a remote
wit remote rename origin github

# Show remote details
wit remote show origin

# Update remote URL
wit remote set-url origin https://github.com/user/new-repo.git

# Get remote URL
wit remote get-url origin

​
Fetch

Download objects and refs from a remote without merging: 
# Fetch from origin (default remote)
wit fetch

# Fetch from a specific remote
wit fetch upstream

# Fetch all remotes
wit fetch --all

# Fetch and prune deleted remote branches
wit fetch --prune

# Fetch with tags
wit fetch --tags

​
Fetch Options

OptionDescription
--allFetch from all configured remotes
-p, --pruneRemove remote-tracking refs that no longer exist on the remote
-t, --tagsFetch all tags from the remote
--depth <n>Deepen a shallow clone to n commits
-v, --verboseBe more verbose
-n, --dry-runShow what would be done without making changes
After fetching, you can see what changed: 
# Compare local and remote
wit log main..origin/main

# See all remote branches
wit branch -r

​
Pull

Fetch from remote and merge into current branch: 
# Pull from tracking branch
wit pull

# Pull from specific remote/branch
wit pull origin main

# Pull with rebase instead of merge
wit pull --rebase

# Pull and auto-stash local changes
wit pull --autostash

# Only fast-forward (fail if not possible)
wit pull --ff-only

​
Pull Options

OptionDescription
-r, --rebaseRebase local commits on top of fetched commits
--ff-onlyOnly update if fast-forward is possible
--no-ffCreate a merge commit even for fast-forward
--autostashAutomatically stash/unstash local changes
-v, --verboseBe more verbose

​
Pull Strategies

# Creates a merge commit if branches have diverged
wit pull
Best for: Preserving complete history of parallel development

​
Pull Conflicts

If there are conflicts during pull: 
# See conflicts
wit merge --conflicts

# Resolve and continue
wit merge --continue

# Or abort
wit merge --abort

​
Push

Upload local commits to a remote repository: 
# Push current branch to tracking remote
wit push

# Push to specific remote/branch
wit push origin main

# Push and set upstream tracking
wit push -u origin main

# Push all branches
wit push --all

# Push tags
wit push --tags

# Delete remote branch
wit push --delete origin old-branch

# Force push (use with caution!)
wit push --force
wit push -f

# Safer force push
wit push --force-with-lease

​
Push Options

OptionDescription
-u, --set-upstreamSet upstream tracking for the branch
-f, --forceForce push (overwrites remote history)
--force-with-leaseForce push only if remote hasn’t changed
--tagsPush all local tags
-d, --deleteDelete the specified remote branch
--allPush all branches
-n, --dry-runShow what would be pushed without pushing
-v, --verboseBe more verbose
--also <remote>Also push to an additional remote (dual-push)
--all-remotesPush to all configured remotes
Force Push Warning: Using --force can overwrite remote history and cause problems for collaborators. Prefer --force-with-lease which checks that the remote hasn’t changed before pushing.

​
Dual-Push (Multiple Remotes)

Push to multiple remotes simultaneously. This is useful when you want to keep both a wit server and GitHub (or another Git host) in sync: 
# Push to origin and also to github remote
wit push --also github

# Push to a specific remote and also another
wit push origin main --also github

# Push to ALL configured remotes
wit push --all-remotes
Use Case: If you’re using wit as your primary version control but need to sync with GitHub for CI/CD or deployment providers (Vercel, Netlify, etc.), dual-push keeps both remotes in sync with a single command.
Example workflow: 
# Set up remotes
wit remote add origin git@wit-server:user/repo.git
wit remote add github git@github.com:user/repo.git

# Push to both with one command
wit push origin main --also github

# Or push to all remotes
wit push --all-remotes

​
Push Rejections

If your push is rejected, it usually means the remote has changes you don’t have: 
# Push rejected - remote has new commits
wit push
# ! [rejected]        main -> main (non-fast-forward)
# error: failed to push some refs

# Solution: Pull first, then push
wit pull
wit push

# Or if you're sure, force push
wit push --force-with-lease

​
Authentication

​
GitHub Authentication

The recommended way to authenticate with GitHub: 
# Login with OAuth (opens browser)
wit github login

# Check authentication status
wit github status

# Logout
wit github logout

​
Environment Variables

You can also use environment variables: 
# GitHub token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Or use GH CLI token
export GH_TOKEN=ghp_xxxxxxxxxxxx

​
Personal Access Tokens

For other Git hosts, use personal access tokens: 
# Token in URL (not recommended for shared machines)
wit clone https://token@github.com/user/repo.git

# Or set in environment
export WIT_TOKEN=your-token

​
Working with Forks

Common fork workflow: 
# Clone your fork
wit clone https://github.com/you/repo.git
cd repo

# Add upstream remote
wit remote add upstream https://github.com/original/repo.git

# Fetch upstream changes
wit fetch upstream

# Merge upstream into your branch
wit merge upstream/main

# Push to your fork
wit push origin main

​
Tracking Branches

Set up tracking between local and remote branches: 
# Push and set upstream
wit push -u origin feature

# After this, you can just use:
wit push
wit pull

# See tracking configuration
wit branch -vv

# Set up tracking manually
wit branch --set-upstream-to=origin/main main

​
Complete Workflow Example

# 1. Clone a repository
wit clone https://github.com/user/repo.git my-project
cd my-project

# 2. Check remotes
wit remote -v
# origin    https://github.com/user/repo.git (fetch)
# origin    https://github.com/user/repo.git (push)

# 3. Create a feature branch and make changes
wit switch -c feature-x
echo "new feature" > feature.txt
wit add feature.txt
wit commit -m "Add new feature"

# 4. Push the new branch
wit push -u origin feature-x

# 5. Later, get updates from origin
wit fetch origin

# 6. Merge updates into your branch
wit pull origin main

# 7. Push your updated branch
wit push

# 8. After merge, clean up
wit switch main
wit pull
wit branch -d feature-x
wit push --delete origin feature-x

​
Troubleshooting

​
”Authentication failed"

# Check if logged in
wit github status

# Re-login
wit github logout
wit github login

​
"Updates were rejected”

Your local branch is behind the remote: 
# Option 1: Pull first
wit pull
wit push

# Option 2: Force push (if you know what you're doing)
wit push --force

​
“No upstream branch”

# Set upstream when pushing
wit push -u origin branch-name

​
Tips

Run wit fetch regularly to stay up-to-date with remote changes without affecting your working directory.
Set up tracking with wit push -u so future pushes/pulls just work with wit push and wit pull.
When you need to force push, use --force-with-lease to prevent accidentally overwriting someone else’s work.
Use wit fetch --prune to remove tracking branches for remote branches that have been deleted.