---
title: Doc sets
description: List doc sets, publish a docs folder as a version, and yank a version.
order: 7
---

A doc set is one body of Markdown docs with versions, a package's or a project's own.
Reading them needs no login.

## Read

```sh
ops docs                                   # every set: kind, project, latest version
ops docs --project rungholt --kind service # one project's, or one kind's
ops docs storage                           # one set's versions, newest first
```

## Publish a folder

```sh
ops docs push docs --set storage --version 0.4.0
ops docs push docs --set web --version "$GIT_SHA" --kind service --project rungholt
```

`ops docs push <dir>` packs the folder itself, no `tar` needed, and uploads it as one
version. Ops checks every page and answers with every reason it refuses, one per line, and
the command exits 1.

What goes in is every file under the folder except hidden ones (names starting with a
dot). A symbolic link is refused before anything is sent.

**The same folder is always the same bytes.** The archive carries no timestamps, owners or
modes from your disk and lists files in sorted order. A version never changes: pushing
other content under a version that exists is refused, and pushing the same folder again is
a no op that says so. A CI job that reruns on a fresh checkout is therefore told nothing
changed.

## Which kind of set

The first publish decides a set's kind from its name:

- the name of a module or a package makes a **package** set in the project that publishes
  it, and its version must be a published version of that package: publish the package
  first;
- any other name is a **service** set and needs `--project` (with `--kind service`, the
  project chosen with `ops use` is used when you give none).

`--kind` states what you expect. The command refuses before uploading when the set exists
as another kind.

## Yank

```sh
ops docs yank storage 0.4.0
```

Readers stop showing the version; its archive stays. Pushing the same folder again does
not bring it back, and other content under that version is refused.

## Permission

Publishing and yanking need `package.publish` in the set's project. Reading is public, so
a docs folder is never the place for anything private.