repos

# f repos

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

If you want standard `git clone` destination behavior, use [`f clone`](clone.md) 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

```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) |
| `--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:

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

## 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 git@github.com:upstream-org/repo.git
```