> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jjhub.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Repositories

> Create, manage, and configure JJHub repositories

# Repositories

Repositories are the core unit of JJHub. They store your code, track changes via jj, and host landing requests, issues, workflows, and more. JJHub repositories are jj-native -- they use bookmarks instead of branches, stable Change IDs instead of commit SHAs, and first-class conflict tracking.

## Creating Repositories

### Via CLI

```bash theme={null}
# Create a public repository
jjhub repo create my-project --description "A new project"

# Create a private repository
jjhub repo create my-project --private

# Create a repository under an organization
jjhub repo create my-org/my-project --description "Org repository"
```

| Flag                       | Description                          |
| -------------------------- | ------------------------------------ |
| `-d, --description <text>` | Repository description               |
| `--public`                 | Make the repository public (default) |
| `--private`                | Make the repository private          |

### Via API

```bash theme={null}
# Create a user-owned repository
curl -X POST https://api.jjhub.tech/api/user/repos \
  -H "Authorization: token jjhub_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "description": "A new project",
    "private": false
  }'

# Create an org-owned repository
curl -X POST https://api.jjhub.tech/api/orgs/my-org/repos \
  -H "Authorization: token jjhub_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "description": "Org repository",
    "private": true
  }'
```

## Cloning Repositories

```bash theme={null}
# Clone by owner/repo
jjhub repo clone alice/my-project

# Clone into a specific directory
jjhub repo clone alice/my-project ./local-dir
```

The `jjhub repo clone` command clones via your preferred git protocol (SSH or HTTPS, configurable with `jjhub config set git_protocol`). After cloning, you work with standard jj commands.

## Listing and Viewing

```bash theme={null}
# List your repositories
jjhub repo list

# Limit results
jjhub repo list --limit 10

# Include archived repositories (excluded by default)
jjhub repo list --archived

# View repository details
jjhub repo view
jjhub repo view -R alice/my-project

# JSON output
jjhub repo view --json
```

## Bookmarks

Bookmarks are jj's replacement for git branches. They are named pointers to changes, and they are the primary reference type in JJHub.

### Key Differences from Branches

| Aspect   | Git Branches               | jj Bookmarks             |
| -------- | -------------------------- | ------------------------ |
| Identity | Tied to commit hash        | Tied to stable Change ID |
| Rebase   | Changes the hash           | Change ID persists       |
| Tracking | Implicit (remote tracking) | Explicit (push/pull)     |
| Default  | `main` or `master`         | `main` (configurable)    |

### Managing Bookmarks

```bash theme={null}
# List bookmarks (local jj-lib operation)
jjhub bookmark list

# List bookmarks from remote API
jjhub bookmark list --remote

# Create a bookmark at the current working copy
jjhub bookmark create feature-auth

# Create a bookmark at a specific change
jjhub bookmark create feature-auth --change-id kxyz1234

# Delete a bookmark
jjhub bookmark delete feature-auth

# Remote operations
jjhub bookmark create feature-auth --remote --change-id kxyz1234 -R owner/repo
jjhub bookmark delete feature-auth --remote -R owner/repo
```

### Bookmark Protection

Protect important bookmarks with rules that gate landing:

```bash theme={null}
# Require 1 approval before landing into main
jjhub bookmark protect main --require-review --approvals 1

# Require CI checks and 2 approvals
jjhub bookmark protect main \
  --require-review \
  --approvals 2 \
  --require-status-checks \
  --dismiss-stale-reviews \
  --no-force-push

# Protect release bookmarks with a glob pattern
jjhub bookmark protect "release/*" --require-review --approvals 2

# View all protection rules
jjhub bookmark protections

# Remove protection
jjhub bookmark unprotect main
```

See the [Landing Requests guide](/guides/landing-requests#bookmark-protection) for full details on protection rules.

### API Endpoints

| Method   | Endpoint                                  | Description       |
| -------- | ----------------------------------------- | ----------------- |
| `GET`    | `/api/repos/:owner/:repo/bookmarks`       | List bookmarks    |
| `POST`   | `/api/repos/:owner/:repo/bookmarks`       | Create a bookmark |
| `DELETE` | `/api/repos/:owner/:repo/bookmarks/:name` | Delete a bookmark |

## Changes & Change IDs

Changes are the fundamental unit of work in jj. Every edit you make creates a change with a stable Change ID that persists across rebases, amends, and rewrites.

### Viewing Changes

```bash theme={null}
# List recent changes (local jj-lib operation)
jjhub change list

# Show details for a specific change
jjhub change show kxyz1234

# Show the diff for a change
jjhub change diff kxyz1234

# Diff the working copy
jjhub change diff
```

### How Change IDs Work

Unlike git commit hashes, which change every time you amend or rebase, jj Change IDs are stable:

```bash theme={null}
# Create a change
jj new -m "Add feature"
# Change ID: kxyz1234

# Amend the change (add more edits)
jj describe -m "Add feature (updated)"
# Change ID is still kxyz1234

# Rebase onto latest main
jj rebase -d main
# Change ID is still kxyz1234
```

This stability is what makes landing requests, stacked changes, and CI statuses work seamlessly. A landing request tracks changes by their stable IDs, so amending or rebasing automatically updates the LR.

### Change IDs in the API

Changes are accessible via API endpoints that use the stable Change ID:

| Method | Endpoint                                               | Description          |
| ------ | ------------------------------------------------------ | -------------------- |
| `GET`  | `/api/repos/:owner/:repo/changes`                      | List changes         |
| `GET`  | `/api/repos/:owner/:repo/changes/:change_id`           | Get a change         |
| `GET`  | `/api/repos/:owner/:repo/changes/:change_id/diff`      | Get the diff         |
| `GET`  | `/api/repos/:owner/:repo/changes/:change_id/files`     | List files in change |
| `GET`  | `/api/repos/:owner/:repo/changes/:change_id/conflicts` | List conflicts       |

## Repository Settings

### Visibility

Repositories can be public or private:

* **Public**: Visible to everyone, cloneable without authentication
* **Private**: Visible only to the owner, org members with access, and explicit collaborators

Change visibility via the API:

```bash theme={null}
curl -X PATCH https://api.jjhub.tech/api/repos/owner/repo \
  -H "Authorization: token jjhub_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"private": true}'
```

### Topics

Topics tag your repository for discoverability:

```bash theme={null}
# View topics
curl -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/repos/owner/repo/topics

# Set topics
curl -X PUT https://api.jjhub.tech/api/repos/owner/repo/topics \
  -H "Authorization: token jjhub_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"topics": ["jj", "typescript", "ai"]}'
```

### Stars

Star a repository to bookmark it and show appreciation:

```bash theme={null}
# Star a repository
curl -X PUT -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/user/starred/owner/repo

# Unstar a repository
curl -X DELETE -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/user/starred/owner/repo

# List stargazers
curl https://api.jjhub.tech/api/repos/owner/repo/stargazers
```

## Repository Archiving

Archiving puts a repository into a read-only state. No pushes, no new issues, no new landing requests, and no new workflow runs are accepted. The repository remains cloneable and browsable for reference.

```bash theme={null}
# Archive a repository
jjhub repo archive owner/repo

# Unarchive a repository
jjhub repo unarchive owner/repo
```

**Who can archive/unarchive**: repository owner, organization owners (for org-owned repos), and platform admins.

**What archiving does:**

* Repository becomes read-only (no pushes, no new issues/LRs/workflows)
* Existing data is fully preserved and browsable
* Repository is filtered from default listings (use `--archived` to include)

### API Endpoints

| Method   | Endpoint                          | Description            |
| -------- | --------------------------------- | ---------------------- |
| `POST`   | `/api/repos/:owner/:repo/archive` | Archive a repository   |
| `DELETE` | `/api/repos/:owner/:repo/archive` | Unarchive a repository |

## Repository Transfer

Transfer moves a repository from one owner to another (user-to-org, org-to-user, or org-to-org).

```bash theme={null}
# Transfer a repo to an organization
jjhub repo transfer alice/my-repo acme-org

# Skip confirmation prompt
jjhub repo transfer alice/my-repo acme-org -y
```

**What happens during transfer:**

* The repository URL changes (e.g., `alice/my-repo` becomes `acme-org/my-repo`). The old URL redirects for a grace period.
* All collaborators, issues, landing requests, workflows, webhooks, stars, and watches are preserved.
* The target user or org owner may need to accept the transfer.

**Who can transfer**: repository owner, organization owners (for org-owned repos), and platform admins.

### API Endpoint

| Method | Endpoint                           | Description                                               |
| ------ | ---------------------------------- | --------------------------------------------------------- |
| `POST` | `/api/repos/:owner/:repo/transfer` | Transfer a repository (body: `{"new_owner": "acme-org"}`) |

## Deploy Keys

Deploy keys are SSH keys scoped to a single repository. They are useful for CI/CD pipelines and deployment automation where you need repository access without a personal account.

```bash theme={null}
# List deploy keys
jjhub repo deploy-key list -R owner/repo

# Add a read-only deploy key
jjhub repo deploy-key add -R owner/repo \
  --title "CI Runner" \
  --key "ssh-ed25519 AAAAC3..." \
  --read-only

# Add a read-write deploy key
jjhub repo deploy-key add -R owner/repo \
  --title "Dependency Bot" \
  --key "$(cat ~/.ssh/bot.pub)"

# Delete a deploy key
jjhub repo deploy-key delete -R owner/repo 3
```

See the [Deploy Keys guide](/guides/deploy-keys) for detailed usage and security best practices.

### API Endpoints

| Method   | Endpoint                           | Description         |
| -------- | ---------------------------------- | ------------------- |
| `GET`    | `/api/repos/:owner/:repo/keys`     | List deploy keys    |
| `POST`   | `/api/repos/:owner/:repo/keys`     | Add a deploy key    |
| `GET`    | `/api/repos/:owner/:repo/keys/:id` | Get a deploy key    |
| `DELETE` | `/api/repos/:owner/:repo/keys/:id` | Delete a deploy key |

## File Content Access

Access file contents via the API:

```bash theme={null}
# Get file contents
curl -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/repos/owner/repo/contents/src/main.ts

# Get a git tree
curl -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/repos/owner/repo/git/trees/main
```

### API Endpoints

| Method | Endpoint                                   | Description                    |
| ------ | ------------------------------------------ | ------------------------------ |
| `GET`  | `/api/repos/:owner/:repo/contents/:path`   | Get file or directory contents |
| `GET`  | `/api/repos/:owner/:repo/git/trees/:sha`   | Get a git tree                 |
| `GET`  | `/api/repos/:owner/:repo/git/commits/:sha` | Get a git commit               |
| `GET`  | `/api/repos/:owner/:repo/git/refs`         | List git refs                  |

## Operation Log

jj maintains an operation log of every repository operation. This provides a full audit trail and enables undo:

```bash theme={null}
# View operation log via API
curl -H "Authorization: token jjhub_xxxxx" \
  https://api.jjhub.tech/api/repos/owner/repo/operations
```

| Method | Endpoint                             | Description        |
| ------ | ------------------------------------ | ------------------ |
| `GET`  | `/api/repos/:owner/:repo/operations` | List jj operations |

## Full Repository API

| Method   | Endpoint                  | Description            |
| -------- | ------------------------- | ---------------------- |
| `GET`    | `/api/repos/:owner/:repo` | Get repository         |
| `POST`   | `/api/user/repos`         | Create user repository |
| `POST`   | `/api/orgs/:org/repos`    | Create org repository  |
| `PATCH`  | `/api/repos/:owner/:repo` | Update repository      |
| `DELETE` | `/api/repos/:owner/:repo` | Delete repository      |

## Next Steps

* [Stacked Changes](/guides/stacked-changes) -- work with stacked changes
* [Landing Requests](/guides/landing-requests) -- submit changes for review
* [Workflows](/guides/workflows) -- automate CI and AI workflows
* [jj Crash Course](/guides/jj-crash-course) -- learn jj fundamentals