Skip to main content

# kater git clone

Makes a local copy of everything that you can read in Kater, in a new folder.

{/* Written by apps/landing-page/scripts/docs/write_cli_reference.py from the kater CLI's own help and scripts/docs/cli-reference.md. Do not edit it by hand: change those, then run the script. */}

The copy is an ordinary git repository on the branch `main`, with one snapshot commit and none of Kater's history.

## Examples

```bash
# Make a local copy in a folder named kater
kater git clone
# Make a local copy in a folder that you name
kater git clone ~/kater
```

## Arguments

<div class="cli-options">

| Argument | Description |
| --- | --- |
| `<directory>` | Optional. The folder for the local copy. It must be new or empty. The default is `kater`. |

</div>

## Options

It also takes `--help`.

## What a clone holds

- **One snapshot.** The copy holds one commit of everything you can read, on a hidden ref, `refs/kater/upstream`. Kater's own history never comes with it, because it would show paths that you cannot read.
- **Your branch.** That commit is checked out on `main`. Work there with plain git.
- **Which Kater.** `.git/kater.json` records the Kater API that the copy came from, and `kater git pull` and `kater git push` use that API. Leave the file and the ref as they are.
- **Sign in first.** A clone reaches Kater, so run `kater login` before you clone. When there is no `profiles.yml`, the clone writes `~/.kater/profiles.yml` with the profile `kater`, whose target `prod` is Kater's own API, as `kater login` does.
- **What you can only view.** `.git/kater-view-only.json` lists the folders and files that you can read and not change. The VS Code extension opens them read-only.
- **Old names.** `.git/kater-retired.json` holds the names that renames retired, so a command in your copy finds a query, a chart, a workspace or a field by a name it had. It also holds what is in the Trash, so a check of your copy says that a name was deleted.

## See also

- [`kater git`](https://kater.ai/docs/cli-reference/git/)
- [All commands](https://kater.ai/docs/cli-reference/kater/)

On this page

Examples
Arguments
Options
What a clone holds
See also

Kater CLI Share and administer git

kater git clone

Makes a local copy of everything that you can read in Kater, in a new folder.

The copy is an ordinary git repository on the branch main, with one snapshot commit and none of Kater’s history.

Examples

# Make a local copy in a folder named kater
kater git clone
# Make a local copy in a folder that you name
kater git clone ~/kater

Arguments

Argument	Description
`<directory>`	Optional. The folder for the local copy. It must be new or empty. The default is `kater`.

Options

It also takes --help.

What a clone holds

One snapshot. The copy holds one commit of everything you can read, on a hidden ref, refs/kater/upstream. Kater’s own history never comes with it, because it would show paths that you cannot read.
Your branch. That commit is checked out on main. Work there with plain git.
Which Kater. .git/kater.json records the Kater API that the copy came from, and kater git pull and kater git push use that API. Leave the file and the ref as they are.
Sign in first. A clone reaches Kater, so run kater login before you clone. When there is no profiles.yml, the clone writes ~/.kater/profiles.yml with the profile kater, whose target prod is Kater’s own API, as kater login does.
What you can only view. .git/kater-view-only.json lists the folders and files that you can read and not change. The VS Code extension opens them read-only.
Old names. .git/kater-retired.json holds the names that renames retired, so a command in your copy finds a query, a chart, a workspace or a field by a name it had. It also holds what is in the Trash, so a check of your copy says that a name was deleted.

See also