lw-clone-repo

name	lw-clone-repo
description	Clone a git remote into the workspace-local mirror at raw/upstream, bind repo_sync in the profile and manifest, then enable lw-sync-repo. Usage: /lw-clone-repo <git-url> [options]

LLM Wiki Clone From URL

Create or refresh the workspace-local source mirror from a git URL so repo-backed workflows can run without a pre-existing checkout elsewhere.

Canonical mirror path

• Checkout directory: raw/upstream/ (relative to the wiki workspace root)
• repo_sync.repo_path: raw/upstream
• raw/repo/ remains reserved for staged repo file artifacts on the way to lw-compile (see lw-ingest / lw-sync-repo). Do not use raw/repo/ as the live .git working tree.

Required reads

1. .llm-wiki/profile.json
2. Active profile markdown
3. .llm-wiki/manifest.json

If the workspace is missing, run lw-init (or bootstrap) first so raw/, wiki/, profiles/, and .llm-wiki/ exist.

Inputs

• git_url (required): https://..., git@..., or another URL git clone accepts
• branch (optional): defaults to profile repo_sync.default_branch or main
• shallow (optional): default true — use git clone --depth 1 for large repos; full history only when the user explicitly needs it
• dest (optional): override path; must stay under raw/ and must not be raw/repo or raw/changes

Procedure

1. Resolve workspace root

The wiki workspace root is the directory containing wiki/, raw/, and .llm-wiki/.

2. Choose destination

Default: raw/upstream. Resolve relative to the workspace root.

If raw/upstream exists and is already a git repository:

• Prefer git -C "$DEST" remote get-url origin and compare to the requested URL (normalized).
• If same remote: run git fetch --prune and optionally git checkout / reset to the requested branch instead of deleting the clone.
• If different remote: stop and ask the user whether to replace the mirror or use a different dest.

3. Clone

# Shallow (default)
git clone --depth 1 --branch "$BRANCH" "$GIT_URL" "$WORKSPACE/raw/upstream"

# Full history (only when explicitly requested)
git clone --branch "$BRANCH" "$GIT_URL" "$WORKSPACE/raw/upstream"

If --branch fails (wrong default branch name), retry without --branch so the remote default HEAD is used, then record the resolved branch from git rev-parse --abbrev-ref HEAD.

4. Derive provider metadata

• If the host is github.com, derive repo_slug as owner/repo from the URL when the profile or manifest does not already set it:

  • https://github.com/owner/repo.git → owner/repo
  • [e-mail]:owner/repo.git → owner/repo

• Set provider: github when using GitHub; otherwise leave provider as in the profile or null and rely on git-only mode in lw-sync-repo.

5. Bind repo_sync in the profile and manifest

Update the active profile’s repo_sync block (YAML) and mirror the same fields under .llm-wiki/manifest.json → repo_sync:

• enabled: true
• repo_path: raw/upstream (or the chosen dest relative to workspace root)
• repo_remote: origin (or the remote name used by clone)
• default_branch: branch checked out after clone
• provider / repo_slug: as derived or already configured

Do not copy the full file tree into raw/repo/ here; binding the mirror is enough for lw-sync-repo to inspect and stage.

6. Git hygiene (workspace repo)

If the wiki workspace is itself a git repository, ensure raw/upstream/ is listed in .gitignore so the mirror is not committed.

7. Next steps

Print a short summary (URL, dest, branch, shallow vs full, repo_slug if set) and recommend:

1. lw-sync-repo — first inspection and staging into raw/repo/ / raw/changes/
2. lw-compile — update wiki/
3. lw-lint / lw-reflect as appropriate

Auth and failures

• Public repos: HTTPS or git SSH as usual.
• Private repos: require working credentials (SSH agent, gh auth setup-git, or credential helper). If clone fails with auth errors, stop with concrete remediation; do not loop silent retries.
• Non-GitHub hosts: clone still works; repo_slug / GitHub API enrichment may be absent — lw-sync-repo git-only mode remains valid.

Hard rules

• Do not place the live .git checkout under raw/repo/ or raw/changes/.
• Do not git pull the mirror for routine refresh; use git fetch via lw-sync-repo.
• Do not mutate files inside raw/upstream/ for wiki edits; treat it as read-only input except for fetch/checkout operations driven by sync/clone.