Skip to content
DRAFT

Workspace Tasks (workspace:)

Workspace initialization and management.

Overview

The workspace: namespace provides tools for initializing and managing workspace repositories. These tasks handle cloning workspace repositories and pulling updates.

Task Reference

Task Description
instantiate Instantiate a new workspace by cloning the workspace repository
overwrite Overwrite tasks/ and bin/ in a destination workspace with contents from a source workspace

Tasks

instantiate

Instantiate a new workspace by cloning the workspace repository.

Usage:

task workspace:instantiate -- <workspace-name> <workspace-path>

Parameters:

  • <workspace-name> (required): Name for the workspace
  • <workspace-path> (required): Path where workspace should be created

What it does:

  1. Parses workspace name and path from required arguments
  2. Creates the workspace directory if it doesn't exist
  3. If directory exists and is a git repository:
  4. Pulls latest changes using git pull --ff-only
  5. If directory exists but is not a git repository:
  6. Errors out (refuses to overwrite non-empty non-git directories)
  7. If directory doesn't exist:
  8. Clones the workspace repository from https://github.com/tvangundy/workspace.git

Example:

# Specify workspace name and path (both required)
task workspace:instantiate -- my-workspace ~/workspaces/my-workspace

# Instantiate in current directory's parent
task workspace:instantiate -- my-project ..

Output: Shows initialization status and workspace location.

Note: This clones the public workspace repository (https://github.com/tvangundy/workspace.git). For private workspace setups, you may need to modify the repository URL in the Taskfile.

overwrite

Overwrite tasks/ and bin/ in a destination workspace with contents from a source workspace. Use this to sync task definitions and scripts from one workspace (e.g. a template or upstream) into another.

Usage:

task workspace:overwrite -- <src-workspace-path> <dst-workspace-path>

Parameters:

  • <src-workspace-path> (required): Path to the source workspace (must contain tasks/ and bin/ directories)
  • <dst-workspace-path> (required): Path to the destination workspace where tasks/ and bin/ will be replaced

What it does:

  1. Resolves paths (supports . for current directory)
  2. Verifies source contains tasks/ and bin/ directories
  3. Ensures source and destination are different paths
  4. Removes existing tasks/ and bin/ in destination
  5. Copies tasks/ and bin/ from source to destination

Examples:

# Overwrite from current directory into another workspace
task workspace:overwrite -- . ~/workspaces/my-workspace

# Overwrite from one workspace into another
task workspace:overwrite -- ~/forest-shadows ~/my-project

Warning: This destructively replaces tasks/ and bin/ in the destination. Any local changes in those directories will be lost.

Prerequisites

For instantiate:

  • Git installed
  • Network access to GitHub
  • Write permissions to the target directory
  • For existing repositories: Git credentials configured

For overwrite:

  • Source workspace must contain tasks/ and bin/ directories
  • Write permissions to the destination workspace

Workflow Example

Typical workspace setup:

# 1. Instantiate workspace
task workspace:instantiate -- my-project ~/projects/my-project

# 2. Change to workspace directory
cd ~/projects/my-project

# 3. (Optional) Overwrite tasks/bin from another workspace
task workspace:overwrite -- ~/forest-shadows ~/projects/my-project

# 4. Follow workspace-specific setup instructions
# (Usually found in the workspace's README.md)

Help

View all available workspace commands:

task workspace:help

Taskfile Location

Task definitions are located in tasks/workspace/Taskfile.yaml.