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. 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

bash

# 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)

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:

Query GitHub via gh api repos/<owner>/<repo>
Detect the parent repository
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)

Examples

bash

# 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 [email protected]:upstream-org/repo.git