Skip to content

Git Wok Commands Reference⚓︎

This page documents all available Git Wok commands and their options.

Global Options⚓︎

These options apply to all commands.

-f / --wokfile-path⚓︎

wok -f <WOK_FILE_PATH>
wok --wokfile-path <WOK_FILE_PATH>

Default

wok.toml

Override the default path to Wokfile.

--help⚓︎

wok --help
wok <COMMAND> --help

Show the list of possible commands and global options. When used with a specific subcommand, show help for that subcommand.

Workspace Initialization Commands⚓︎

init⚓︎

wok init

Initialize Git Wok configuration in an umbrella repository.

What it does: - Creates Wokfile (wok.toml) in the repository - Introspects existing submodules and adds them to the configuration - Optionally switches submodules to match the current branch

Prerequisites: - Must be run in a Git repository - Repository should already be initialized with git init

Fails if: - Wokfile already exists in the repository - Not inside a git repository

Example:

mkdir my-workspace && cd my-workspace
git init
git submodule add https://github.com/user/api api
wok init

assemble⚓︎

wok assemble <DIRECTORY>

Assemble a workspace by initializing subrepos and generating the configuration.

What it does: - Initializes the umbrella repository if needed - Discovers all subdirectories containing git repositories - Registers them as git submodules - Preserves existing remote URLs - Creates the Wokfile with all discovered repositories

Arguments: - <DIRECTORY> - Path to the workspace directory to assemble

Use case: Converting a directory with multiple independent git repositories into a managed workspace.

Example:

# You have a directory structure:
# workspace/
#   api/       (git repo)
#   frontend/  (git repo)
#   docs/      (git repo)

cd workspace
wok assemble .

# Now you have:
# workspace/.git
# workspace/.gitmodules
# workspace/wok.toml

Housekeeping Commands⚓︎

status⚓︎

wok status [--fetch]

Show the status of the umbrella repository and all configured subrepos.

Options:

  • --fetch - Fetch from remotes before comparing local and remote branches (performs network operations)

What it shows:

  • Current branch of umbrella repository
  • Whether umbrella repository has uncommitted changes
  • Comparison with remote tracking branch (ahead/behind/diverged/up-to-date)
  • Current branch of each subrepo
  • Whether each subrepo has uncommitted changes
  • Comparison with remote tracking branch for each subrepo

Note: By default, status does not perform any network operations. Use --fetch to update remote refs before comparison. Without --fetch, the comparison is based on the last fetched remote state.

Example output (without fetch):

On branch 'main', all clean, up to date with 'origin/main'
- 'api' is on branch 'main', all clean, ahead of 'origin/main' by 2 commits
- 'frontend' is on branch 'develop', behind 'origin/develop' by 3 commits
- 'docs' is on branch 'main', all clean

Example with fetch:

wok status --fetch

Output:

On branch 'main', all clean, diverged from 'origin/main' (1 ahead, 2 behind)
- 'api' is on branch 'main', all clean, up to date with 'origin/main'

Remote status indicators:

  • up to date with 'origin/main' - Local and remote branches point to the same commit
  • ahead of 'origin/main' by N commit(s) - Local branch has N commits not yet pushed to remote
  • behind 'origin/main' by N commit(s) - Remote branch has N commits not yet pulled locally
  • diverged from 'origin/main' (N ahead, M behind) - Both local and remote have unique commits
  • No indicator - No remote tracking branch configured for this branch

Repository Management Commands⚓︎

add⚓︎

wok add <SUBMODULE_PATH>

Add a submodule previously configured in the repository to the Wokfile.

Prerequisites: - Submodule must already be added with git submodule add - Wokfile must exist

Arguments: - <SUBMODULE_PATH> - Path to the submodule relative to umbrella repository root

Example:

git submodule add https://github.com/user/component component
wok add component

rm⚓︎

wok rm <SUBMODULE_PATH>

Remove a submodule from Wokfile configuration.

Note: This only removes the entry from wok.toml. It does not remove the git submodule itself. Use git submodule deinit and git rm to fully remove a submodule.

Arguments: - <SUBMODULE_PATH> - Path to the submodule relative to umbrella repository root

Example:

wok rm component
# Then, if desired:
git submodule deinit component
git rm component

Branch Management Commands⚓︎

switch⚓︎

wok switch [OPTIONS] [REPOS]...

Switch repositories to a specified branch with fine-grained control.

Options:

--all⚓︎

wok switch --all

Act on all configured repos, respecting skip_for settings. Repos in the skip list can still be targeted explicitly.

Note: This flag replaces the deprecated head switch command. Use wok switch --all to switch all repositories to the umbrella's current branch.

-c / --create⚓︎

wok switch -c
wok switch --create

Create the target branch in repositories if it doesn't exist. Without this flag, the command fails if the branch doesn't exist.

--branch ⚓︎

wok switch --branch <BRANCH_NAME>

Use the specified branch name instead of the current umbrella repository branch.

repos⚓︎

wok switch <REPO1> <REPO2> ...

Specific repositories to switch. If not provided and --all is not used, switches repos matching the current umbrella branch.

Examples:

# Switch repos matching current branch
git checkout main
wok switch

# Switch all repos
wok switch --all

# Switch specific repos
wok switch api frontend

# Switch to specific branch
wok switch --all --branch develop

# Create and switch to new branch (long form)
wok switch --all --create --branch feature-new

# Create and switch to new branch (short form)
wok switch --all -c --branch feature-new

Behavior: - Update the Wokfile configuration to reflect new branch assignments - Commit submodule state changes to the umbrella repository - Skip repos with switch in their skip_for list (unless explicitly targeted)

Commit Message Format:

When submodules are switched, the commit message shows which repos changed:

Switch and lock submodule state

Switched to 'feature-branch':
- api: feature-branch
- frontend: feature-branch
- docs: feature-branch

Synchronization Commands⚓︎

lock⚓︎

wok lock

Lock the current submodule state by committing submodule commit references.

What it does: - Ensure each repo is on its configured branch - Add all submodule entries to the git index - Compare the current state with the previous commit - Only commit if submodules have changed (no-op if nothing changed) - Create a commit with updated commit hashes of changed submodules

Commit Message Format:

When submodules have changed, the lock command creates a descriptive commit message: - Summary header: "Lock submodule state" - List of changed submodules with their latest commit messages (truncated to 50 characters)

Example commit message:

Lock submodule state

Changed submodules:
- api: Add new authentication endpoint for OAuth2 flow
- frontend: Update dashboard UI with new chart compone...
- docs: Fix typo in installation guide

Output Messages: - "Locked submodule state" - When changes were committed - "No submodule changes detected; nothing to lock" - When no changes were found

Use case: Capturing a snapshot of the workspace state after making changes in subrepos.

Example:

# After making changes in api/ and frontend/
cd api && git commit -am "Update API" && cd ..
cd frontend && git commit -am "Update UI" && cd ..

# Lock the state - creates commit with summary
wok lock
# Output: Locked submodule state

# Running lock again with no changes
wok lock
# Output: No submodule changes detected; nothing to lock

# Umbrella repo now has a commit with updated submodule pointers
git log -1
# Shows:
# Lock submodule state
#
# Changed submodules:
# - api: Update API
# - frontend: Update UI

update⚓︎

wok update [OPTIONS]

Update submodules by fetching and merging latest changes from remotes.

What it does: - Switch each repo to its configured branch - Fetch changes from the remote - Merge or rebase changes into the local branch (respects pull.rebase and branch.<name>.rebase config) - Stage submodule updates in the umbrella repository - Commit the updated state (unless --no-commit is used)

Options:

--no-commit⚓︎

wok update --no-commit

Stage submodule updates without creating a commit in the umbrella repository.

--umbrella / --no-umbrella⚓︎

wok update --no-umbrella
wok update --umbrella

Control whether the umbrella repository is fetched and merged alongside subrepos. Enabled by default; use --no-umbrella to skip updating the umbrella repo.

Behavior: - Skip repos with update in their skip_for list - Report merge conflicts if any occur - Do not commit umbrella repo if conflicts are detected - Include the umbrella repository in the update process unless --no-umbrella is provided

Examples:

# Update and commit
wok update

# Update but review before committing
wok update --no-commit
git diff --staged
git commit -m "Update submodules"

# Update only subrepos, skip umbrella
wok update --no-umbrella

Example output:

Updating submodules...
- 'umbrella': already up to date on 'main' (12345678)
- 'api': fast-forwarded 'main' to a1b2c3d4
- 'frontend': rebased 'develop' to e5f6g7h8
- 'docs': already up to date on 'main' (i9j0k1l2)
Updated submodule state committed

Commit Message Format:

When submodules are updated, the commit message shows what changed:

Update submodules to latest

Updated submodules:
- api: main to a1b2c3d4
- frontend: develop to e5f6g7h8
- docs: main to i9j0k1l2

Pull Strategy:

wok update respects your git configuration for pull strategy:

  • By default, or when pull.rebase = false, changes are merged
  • When pull.rebase = true, changes are rebased
  • Per-branch configuration with branch.<name>.rebase takes precedence over global pull.rebase

Example configurations:

# Set global preference to rebase
git config --global pull.rebase true

# Set specific branch to use merge in a subrepo
cd api/
git config branch.main.rebase false

Note: Interactive rebase (pull.rebase = interactive) and preserve-merges rebase (pull.rebase = merges) are treated as standard rebase in the current implementation.

Remote Operations Commands⚓︎

push⚓︎

wok push [OPTIONS] [REPOS]...

Push changes from configured repositories to their remotes.

Options:

-u / --set-upstream⚓︎

wok push -u
wok push --set-upstream

Set upstream tracking for new branches.

--all⚓︎

wok push --all

Act on all configured repos, respecting skip_for settings.

--branch ⚓︎

wok push --branch <BRANCH_NAME>

Push the specified branch instead of the current umbrella repository branch.

--umbrella / --no-umbrella⚓︎

wok push --no-umbrella
wok push --umbrella

Control whether the umbrella repository is included in the push. The umbrella repo is included by default; pass --no-umbrella to skip it.

repos⚓︎

wok push <REPO1> <REPO2> ...

Specific repositories to push. If not provided and --all is not used, pushes repos matching the current umbrella branch.

Behavior: - Check remote state before pushing to avoid unnecessary operations - Skip push entirely if the remote branch already matches the local branch - Skip repos with push in their skip_for list (unless explicitly targeted) - Report which repos were pushed successfully - Handle "up to date" and error cases gracefully - Include the umbrella repository by default so workspace-level changes are pushed alongside subrepos (unless --no-umbrella is specified)

Examples:

# Push repos on current branch
wok push

# Push all repos
wok push --all

# Push specific repos
wok push api docs

# Push and set upstream
wok push --all -u

# Push specific branch
wok push --all --branch release/v2

# Push only subrepos, skip umbrella
wok push --all --no-umbrella

Release Management Commands⚓︎

tag⚓︎

wok tag [OPTIONS] [TAG] [REPOS]...

Create, list, sign, and push tags across repositories.

Modes:

  1. List tags: When no tag name is provided
  2. Create tag: When --create is used or tag name is provided

Options:

--create ⚓︎

wok tag --create <TAG_NAME>

Create a new tag with the specified name.

-s / --sign⚓︎

wok tag -s
wok tag --sign

Sign the tag with GPG. Requires GPG to be configured. Creates an annotated tag.

-m / --message ⚓︎

wok tag -m <MESSAGE>
wok tag --message <MESSAGE>

Add a message to create an annotated tag. If not provided with --sign, lightweight tags are created by default.

When combined with --sign, the message is included in the signed annotated tag. When used without --sign, an unsigned annotated tag is created with the provided message.

Note: Annotated tags (created with --sign or --message) include metadata like tagger name, email, and timestamp. Lightweight tags are simple pointers to commits without additional metadata.

--push⚓︎

wok tag --push

Push tags to remote repositories after creating them.

--all⚓︎

wok tag --all

Act on all configured repos, respecting skip_for settings.

--umbrella / --no-umbrella⚓︎

wok tag --no-umbrella
wok tag --umbrella

Control whether the umbrella repository participates in listing or tagging. Enabled by default; use --no-umbrella to limit operations to subrepos.

Positional Arguments⚓︎

The command accepts flexible positional argument formats:

  • wok tag - List tags in repos on current branch
  • wok tag <TAG> - List tag in repos on current branch matching <TAG>
  • wok tag <TAG> <REPO>... - List tag in specific repos
  • wok tag --create <TAG> - Create tag in repos on current branch
  • wok tag --all <TAG> - When listing with --all, interpret first positional arg as tag

Behavior: - Skip repos with tag in their skip_for list (unless explicitly targeted) - Report existing tags or creation status for each repo - Handle tag conflicts gracefully - Include the umbrella repository in listing, creation, and push flows by default (disable with --no-umbrella)

Examples:

List tags:

# List tags in repos on current branch
wok tag

# List tags in all repos
wok tag --all

# List tags in specific repos
wok tag api frontend

Create tags:

# Create tag in repos on current branch
wok tag --create v1.0.0

# Create in all repos
wok tag --create v1.0.0 --all

# Create tag with custom message
wok tag --create v1.0.0 --all --message "Release version 1.0.0"

# Short form with message
wok tag --create v1.0.0 --all -m "Release version 1.0.0"

# Create signed tag
wok tag --create v1.0.0 --all --sign

# Create signed tag with message (short form)
wok tag --create v1.0.0 --all -s -m "Signed release v1.0.0"

# Create, sign, and push
wok tag --create v1.0.0 --all --sign --push

# Create in specific repos
wok tag --create v2.0.0 api docs

# Create only in subrepos, skip umbrella
wok tag --create v2.0.0 --all --no-umbrella

Alternative syntax (positional tag argument):

# These work similarly to --create
wok tag v1.0.0 --all --sign --push
wok tag v1.0.0 --all -s -m "Release version 1.0.0"
wok tag v2.0.0 api docs

Example output:

Creating tag 'v1.0.0' in 3 repositories...
- 'api': created tag 'v1.0.0'
- 'frontend': created tag 'v1.0.0'
- 'docs': tag 'v1.0.0' already exists
Successfully processed 3 repositories

Utility Commands⚓︎

completion⚓︎

wok completion [SHELL]

Generate shell completion script for the specified shell.

Arguments: - [SHELL] - Shell type: bash, fish, or zsh (default: bash)

Installation:

Bash:

wok completion bash > ~/.local/share/bash-completion/completions/wok

Zsh:

wok completion zsh > ~/.zsh/completions/_wok
# Add to .zshrc if not already there:
# fpath=(~/.zsh/completions $fpath)
# autoload -Uz compinit && compinit

Fish:

wok completion fish > ~/.config/fish/completions/wok.fish

Command Categories Summary⚓︎

Workspace Setup⚓︎

  • init - Initialize Wokfile in existing repo with submodules
  • assemble - Create workspace from directory of repos

Daily Operations⚓︎

  • status - Check workspace status
  • switch - Change branches with options (use --all for quick branch sync)
  • lock - Capture current state
  • update - Fetch and merge from remotes

Repository Management⚓︎

  • add - Add submodule to config
  • rm - Remove submodule from config

Remote Operations⚓︎

  • push - Push changes to remotes

Release Operations⚓︎

  • tag - Tag, sign, and push releases

Utilities⚓︎

  • completion - Generate shell completions

Selective Targeting⚓︎

Most commands support three targeting strategies:

  1. Branch-based (default): Operate on repos whose configured branch matches the umbrella's current branch
  2. All repos (--all): Operate on all configured repos (respecting skip lists)
  3. Explicit: Specify repo paths as arguments

This allows fine-grained control over which repositories are affected by each operation.

Skip Lists⚓︎

The skip_for field in wok.toml allows excluding repos from bulk operations:

[[repo]]
path = "archived-component"
head = "main"
skip_for = ["push", "update", "tag"]

Commands that honor skip lists: switch, push, tag, update

Repos in skip lists can still be targeted explicitly:

wok push archived-component  # This works even with skip_for = ["push"]