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⚓︎

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

Default

wok.toml

Overrides default path to Wokfile.

--help⚓︎

git-wok --help
git-wok <COMMAND> --help

Shows list of possible commands and global options. When used with a specific subcommand, shows help for that subcommand.

Workspace Initialization Commands⚓︎

init⚓︎

git-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
git-wok init

assemble⚓︎

git-wok assemble <DIRECTORY>

Assemble a workspace by initializing subrepos and generating 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
git-wok assemble .

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

Housekeeping Commands⚓︎

status⚓︎

git-wok status

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

What it shows: - Current branch of umbrella repository - Whether umbrella repository has uncommitted changes - Current branch of each subrepo - Whether each subrepo has uncommitted changes

Example output:

On branch 'main', all clean
- 'api' is on branch 'main', all clean
- 'frontend' is on branch 'develop'
- 'docs' is on branch 'main', all clean

Repository Management Commands⚓︎

repo add⚓︎

git-wok repo add <SUBMODULE_PATH>

Add a submodule previously configured in the repository to 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
git-wok repo add component

repo rm⚓︎

git-wok repo 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:

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

Branch Management Commands⚓︎

head switch⚓︎

git-wok head switch

Switch all configured subrepos to match the current umbrella repository branch.

What it does: - Reads the current branch of the umbrella repository - Switches all configured subrepos to that same branch - Updates the Wokfile configuration - Commits the submodule state changes

Use case: Quick synchronization after checking out a branch in the umbrella repository.

Example:

git checkout feature-x
git-wok head switch
# All subrepos now on 'feature-x'

switch⚓︎

git-wok switch [OPTIONS] [REPOS]...

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

Options:

--all⚓︎

git-wok switch --all

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

--create⚓︎

git-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 ⚓︎

git-wok switch --branch <BRANCH_NAME>

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

repos⚓︎

git-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
git-wok switch

# Switch all repos
git-wok switch --all

# Switch specific repos
git-wok switch api frontend

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

# Create and switch to new branch
git-wok switch --all --create --branch feature-new

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

Synchronization Commands⚓︎

lock⚓︎

git-wok lock

Lock the current submodule state by committing submodule commit references.

What it does: - Ensures each repo is on its configured branch - Adds all submodule entries to the git index - Commits the current commit hashes of all submodules to the umbrella repository

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
git-wok lock

# Umbrella repo now has a commit with updated submodule pointers

update⚓︎

git-wok update [OPTIONS]

Update submodules by fetching and merging latest changes from remotes.

What it does: - Switches each repo to its configured branch - Fetches changes from the remote - Merges changes into the local branch - Stages submodule updates in the umbrella repository - Commits the updated state (unless --no-commit is used)

Options:

--no-commit⚓︎

git-wok update --no-commit

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

Behavior: - Skips repos with update in their skip_for list - Reports merge conflicts if any occur - Does not commit umbrella repo if conflicts are detected

Examples:

# Update and commit
git-wok update

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

Example output:

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

Remote Operations Commands⚓︎

push⚓︎

git-wok push [OPTIONS] [REPOS]...

Push changes from configured repositories to their remotes.

Options:

-u / --set-upstream⚓︎

git-wok push -u
git-wok push --set-upstream

Set upstream tracking for new branches.

--all⚓︎

git-wok push --all

Act on all configured repos, respecting skip_for settings.

--branch ⚓︎

git-wok push --branch <BRANCH_NAME>

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

repos⚓︎

git-wok push <REPO1> <REPO2> ...

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

Behavior: - Skips repos with push in their skip_for list (unless explicitly targeted) - Reports which repos were pushed successfully - Handles "up to date" and error cases gracefully

Examples:

# Push repos on current branch
git-wok push

# Push all repos
git-wok push --all

# Push specific repos
git-wok push api docs

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

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

Release Management Commands⚓︎

tag⚓︎

git-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 ⚓︎

git-wok tag --create <TAG_NAME>

Create a new tag with the specified name.

--sign⚓︎

git-wok tag --sign

Sign the tag with GPG. Requires GPG to be configured.

--push⚓︎

git-wok tag --push

Push tags to remote repositories after creating them.

--all⚓︎

git-wok tag --all

Act on all configured repos, respecting skip_for settings.

Positional Arguments⚓︎

The command accepts flexible positional argument formats:

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

Behavior: - Skips repos with tag in their skip_for list (unless explicitly targeted) - Reports existing tags or creation status for each repo - Handles tag conflicts gracefully

Examples:

List tags:

# List tags in repos on current branch
git-wok tag

# List tags in all repos
git-wok tag --all

# List tags in specific repos
git-wok tag api frontend

Create tags:

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

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

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

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

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

Alternative syntax (positional tag argument):

# These work similarly to --create
git-wok tag v1.0.0 --all --sign --push
git-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⚓︎

git-wok completion [SHELL]

Generate shell completion script for the specified shell.

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

Installation:

Bash:

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

Zsh:

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

Fish:

git-wok completion fish > ~/.config/fish/completions/git-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
  • head switch - Quick branch sync
  • lock - Capture current state
  • update - Fetch and merge from remotes

Repository Management⚓︎

  • repo add - Add submodule to config
  • repo 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:

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