# Publishing from a repo

> Publish single files or keep a whole folder of docs in step with a project.

## One file

```sh
dockito publish plan.md                       # your personal Docs
dockito publish plan.md --to handbook/specs   # a project's folder
dockito publish plan.md -m "Sent to the client"
```

A file with the same name in that place updates its doc: same link, a new [History](/help/concepts/history) entry. Unchanged files are skipped. `--doc <link>` updates a particular doc whatever the file is called, and `--new` makes a new doc even if the name is taken.

New docs are private. Add `--public` only when you want anyone with the link to read it.

## A folder

```sh
dockito sync docs --to handbook
```

`sync` mirrors a folder into a project:

- Subfolders become folders, and each file updates the doc with the same name in the same folder, or becomes a new doc there.
- Only changed files are sent.
- Nothing is moved or deleted in Dockito.

It always shows a plan first. If it would make a project or folders, it waits for `--yes`. `--dry-run` shows the plan and changes nothing.

```sh
dockito sync docs --to handbook --create --dry-run   # see what would happen
dockito sync docs --to handbook --create --yes       # do it
```

Projects go two folders deep. `--fold` puts deeper folders into the deepest allowed one. Where two files would clash, the folders left out go in front of the name.

## Git

When a file you publish matches a commit in your repo, the History entry records the commit, so you can tell which version of the repo a doc came from.

## In CI

```yaml
- run: npx dockito@beta sync docs --to handbook
  env:
    DOCKITO_TOKEN: ${{ secrets.DOCKITO_TOKEN }}
```

Use a personal token with **Publish** access to just that workspace.