gabrie30/ghorg/ghorg-create-vscode-workspace

Create ghorg reclone workspace

Creates a ghorg reclone workspace configuration and its repository list file, then clones the repositories. After completion the workspace is ready to use.

Prerequisites

• ghorg must be installed and available on the system PATH.
• The user must have network access to the SCM provider (e.g. GitHub, GitLab, Bitbucket).

Platform support

This skill works on macOS, Linux, and Windows. All file paths are constructed using the resolved environment variables below. Path separators are determined by the host operating system — use / on macOS and Linux, and \ on Windows. When running shell commands, use the appropriate shell for the platform (bash/zsh on macOS/Linux, cmd/powershell on Windows).

Environment variables

Resolving HOME_DIR

Resolve HOME_DIR using the following strategy:

1. If the environment variable $HOME_DIR (or %HOME_DIR% on Windows) is set, use that value.
2. Otherwise, detect the home directory from the operating system:

• macOS / Linux: Use the $HOME environment variable (typically /Users/<username> on macOS, /home/<username> on Linux).
• Windows: Use the %USERPROFILE% environment variable (typically C:\Users\<username>).

Resolving SCM_ORG

Resolve SCM_ORG using the following strategy:

1. If the environment variable $SCM_ORG (or %SCM_ORG% on Windows) is set, use that value.
2. Otherwise, prompt the user:

What is the SCM organization to clone from?

Example: my-github-org

Store as SCM_ORG. This value is required and cannot be empty.

Paths

All paths are relative to HOME_DIR. Use the platform-appropriate path separator.

Windows note: On Windows the ghorg config directory may be at %USERPROFILE%\.config\ghorg. Verify by checking if the directory exists or by running ghorg ls. Adjust paths accordingly.

Workflow

Step 1 — Resolve environment

Resolve HOME_DIR and SCM_ORG as described in the Environment variables section above. Both values must be resolved before continuing.

Step 2 — Ask for workspace name

Prompt the user:

What should the new reclone workspace be called?

Example: my-reclone

Validation: Must match regex ^[a-z0-9-]+$ (lowercase letters, numbers, hyphens only).

Store as WORKSPACE_NAME. If invalid, ask again until valid.

Step 3 — Ask for repositories

Prompt the user:

List any repositories to include in this workspace.

Enter one repository per line. Press enter on an empty line when finished.

Example input:

repo-one
repo-two
repo-three

Store as REPO_LIST. If none provided, continue with an empty list (empty file).

Step 4 — Ensure ghorg config exists

• Ensure HOME_DIR/.config/ghorg exists; create the directory (including parents) if it does not.
• Ensure HOME_DIR/.config/ghorg/reclone.yaml exists; create an empty file if it does not.

Step 5 — Create workspace repo list file

Create the file:

HOME_DIR/.config/ghorg/workspace-<WORKSPACE_NAME>.txt

Example: HOME_DIR/.config/ghorg/workspace-my-reclone.txt

• Write the repository list exactly as provided (one repo per line).
• If the file already exists, do not overwrite it — stop and report an error.

Step 6 — Append workspace configuration

Append the following YAML block to HOME_DIR/.config/ghorg/reclone.yaml:

<WORKSPACE_NAME>:
  cmd: "ghorg clone <SCM_ORG> --path=<HOME_DIR>/workspaces --target-repos-path=<HOME_DIR>/.config/ghorg/workspace-<WORKSPACE_NAME>.txt --output-dir=<WORKSPACE_NAME>"
  description: "Workspace for <WORKSPACE_NAME>"

Replace <WORKSPACE_NAME>, <SCM_ORG>, and <HOME_DIR> with the resolved values.

Rules:

• Check first: If a top-level key matching the workspace name already exists in reclone.yaml, stop and report an error. Do not overwrite.
• Preserve all existing YAML content.
• Append the new workspace to the end of the file.
• Maintain valid YAML formatting (e.g. ensure a newline before the new top-level key if the file was non-empty).

Step 7 — Run ghorg reclone

Run the following command:

ghorg reclone <WORKSPACE_NAME>

This clones the repositories into HOME_DIR/workspaces/<WORKSPACE_NAME>.

Step 8 — Create VS Code / Cursor workspace file

Create the file:

HOME_DIR/workspaces/<WORKSPACE_NAME>/<WORKSPACE_NAME>.code-workspace

With the following contents:

{
	"folders": [
		{
			"path": "."
		}
	],
	"settings": {}
}

• If the file already exists, overwrite it (this is safe to regenerate).

Step 9 — Confirmation

After all steps complete, output:

Workspace created and cloned successfully.
 
Workspace name:
<WORKSPACE_NAME>
 
SCM organization:
<SCM_ORG>
 
Repo list file:
<HOME_DIR>/.config/ghorg/workspace-<WORKSPACE_NAME>.txt
 
Config updated:
<HOME_DIR>/.config/ghorg/reclone.yaml
 
Cloned to:
<HOME_DIR>/workspaces/<WORKSPACE_NAME>
 
VS Code workspace file:
<HOME_DIR>/workspaces/<WORKSPACE_NAME>/<WORKSPACE_NAME>.code-workspace

Replace <WORKSPACE_NAME>, <SCM_ORG>, and <HOME_DIR> with the resolved values.

Then explain to the user what was added and how the pieces fit together, using this structure with resolved values:

**What was added**
 
1.**Repo list:** `<HOME_DIR>/.config/ghorg/workspace-<WORKSPACE_NAME>.txt`
   -Contains: the repositories in this workspace, one per line (<N> repos: <names>).
   -Role: ghorg reads it through `--target-repos-path` to decide which repos to clone. Add or remove lines to change the workspace.
2.**Reclone entry:** `<WORKSPACE_NAME>` in `<HOME_DIR>/.config/ghorg/reclone.yaml`
   -Contains: the `ghorg clone` command for this workspace (organization, clone location, repo list, and output folder name).
   -Role: `ghorg reclone <WORKSPACE_NAME>` runs this command. Run it again to pick up repos added to the repo list.
3.**Workspace folder:** `<HOME_DIR>/workspaces/<WORKSPACE_NAME>/`
   -Contains: one folder per cloned repository.
   -Role: where you work. Each reclone updates these clones in place.
4.**VS Code workspace file:** `<HOME_DIR>/workspaces/<WORKSPACE_NAME>/<WORKSPACE_NAME>.code-workspace`
   -Contains: a VS Code / Cursor workspace whose only folder is the workspace root.
   -Role: open it to load every repo in one editor window.
 
**Workflow:** edit the repo list, run `ghorg reclone <WORKSPACE_NAME>`, then open the `.code-workspace` file.
 
**Warning:** by default, ghorg resets existing clones to the remote default branch on every reclone, which discards local changes. Add `--protect-local` (skips repos with local changes) or `--no-clean` (leaves existing repos untouched) to the entry's `cmd` to prevent this.
 
**Removing it later:** use the `ghorg-remove-vscode-workspace` skill. It shows what it will remove and asks before deleting.

Failure conditions

Stop and report an error (do not silently continue) if:

• HOME_DIR cannot be resolved from the environment.
• SCM_ORG is not set and the user does not provide a value when prompted.
• The workspace name already exists as a top-level key in reclone.yaml.
• The repo list file HOME_DIR/.config/ghorg/workspace-<WORKSPACE_NAME>.txt already exists.
• The ghorg reclone command fails (non-zero exit code).
• Filesystem write fails (directory or file creation).
• YAML formatting cannot be preserved when appending.

Never silently continue after an error.