# Labels and commits

```bash
buf push  # commit lands on the "main" label
buf push --label v1.0.0  # commit lands on a named label
buf registry label list protos.rip/<scope>/<module>  # see all labels and which commit each points at
buf registry label archive protos.rip/<scope>/<module>:<label>  # archive a label
buf registry commit list protos.rip/<scope>/<module>  # see commit history
```

## How labels and commits work

A commit is the immutable unit — every push creates one. A label is a movable pointer at a commit; labels are mutable, commits are not. Push without `--label` and the default label moves, which starts as `main`. Push with `--label v1.0.0` and the label is created if it doesn’t exist, or moved to the new commit if it does. The dashboard’s module page lists current labels and recent commits.

## Tag a release

Run `buf push --label <name>` to publish a commit under a named label.

```bash
buf push --label v1.0.0
```

Consumers pin to that label by appending `:v1.0.0` to their dep entry — see [Depend on a module](/docs/guides/depend-on-a-module). Re-pushing with the same `--label` moves the label, so what `:v1.0.0` resolves to changes; use immutable labels (e.g. semver tags) when consumers depend on stability. To release a fix without disturbing existing consumers, push with a new label.

## List labels and commits

List labels and the commit each points at:

```bash
buf registry label list protos.rip/<scope>/<module>
```

List commit history (most recent first):

```bash
buf registry commit list protos.rip/<scope>/<module>
```

Get info on a single commit by ID:

```bash
buf registry commit info protos.rip/<scope>/<module>:<commit_id>
```

## Archive a label

Archive a label to mark it deprecated without deleting commits — list operations exclude archived labels by default.

```bash
buf registry label archive protos.rip/<scope>/<module>:<label>
```

The underlying commit is untouched; only the label is hidden. Push to an archived label with `buf push --label <archived_label>` and it is unarchived. Unarchive without pushing:

```bash
buf registry label unarchive protos.rip/<scope>/<module>:<label>
```

## See also

← Depend on a module Manage modules →