Skip to content

repos.md

Latest commit

 

History

History
91 lines (61 loc) · 3.2 KB

repos.md

File metadata and controls

91 lines (61 loc) · 3.2 KB
Raw

f repos

Clone repositories into a structured local directory or create new ones.

If you want standard git clone destination behavior, use f clone instead.

Overview

f repos clone clones GitHub repositories into ~/repos/<owner>/<repo> using SSH URLs. By default it does a shallow clone for speed, then fetches full history in the background. It always sets up an upstream remote and local tracking branch unless you pass --no-upstream. Clone-time bootstrap is local-only: it does not create or push a private mirror repo. If the target checkout already exists, Flow reports that and exits without re-bootstrapping or reopening the repo. f repos create creates a GitHub repository from the current folder and pushes it.

By default, Flow treats ~/repos as an immutable managed root. Use FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 if you need to point --root somewhere else.

Quick Start

# Clone a GitHub repo into ~/repos/<owner>/<repo>
f repos clone https://github.com/owner/repo

# Short form
f repos clone owner/repo

# Skip upstream auto-setup
f repos clone owner/repo --no-upstream

# Full clone (skip background history fetch)
f repos clone owner/repo --full

# Create a new repo from the current folder (prompts for name/visibility)
f repos create

Options

f repos clone

Option Short Description
<URL> Repository URL or owner/repo
--root <PATH> Root directory for clones (default: ~/repos, override requires FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1)
--full Full clone (skip shallow clone + background history fetch)
--no-upstream Skip upstream setup
--upstream-url <URL> -u Upstream URL override (skips GitHub lookup)
--no-home-branch-bootstrap Skip local nikiv home-branch setup after clone

f repos create

Option Short Description
--name <NAME> -n Repository name (defaults to current folder)
--public Create as public repository
--private Create as private repository
--description <TEXT> -d Description for the repository
--yes -y Skip confirmation prompts

Upstream Automation

Flow will:

  1. Query GitHub via gh api repos/<owner>/<repo>
  2. Detect the parent repository
  3. Run f upstream setup --url <parent> inside the cloned repo

If the repo is not a fork (or gh is unavailable), flow sets upstream to the origin URL.

Background History Fetch

When cloning in fast mode (default), flow spawns a background fetch:

  • git fetch --unshallow --tags origin
  • git fetch --tags upstream (if upstream was configured)

Private Mirror Setup

f repos clone no longer creates or pushes the fork / *-i private mirror as part of clone.

If you want Flow to create or repair the private mirror workflow for an existing repo, run:

f repos bootstrap-home-branch --path ~/repos/<owner>/<repo>

Examples

# Clone into a custom root (requires override)
FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 f repos clone https://github.com/owner/repo --root ~/work/repos

# Override upstream manually
f repos clone https://github.com/your-user/repo -u git@github.com:upstream-org/repo.git