---
title: "How to share notes, issues, and docs across repositories"
description: "Declare another store, link to its notes, and check what each tool can see."
type: how-to
canonical_url: https://eng.rip/how-to-share-notes-issues-and-docs-across-repositories/
---

# How to share notes, issues, and docs across repositories

Start with sibling repositories named `handbook` and `project`. The handbook has an initialized zettel store with the note `pzya-retry-with-jitter`. The project has initialized zettel, tisket, and diataxis stores.

## Declare the handbook

In `project`, create `stores.yml` beside the tool marker files:

```yaml
format: 2
stores:
  - alias: handbook
    path: ../handbook
```

List the note stores from `project`:

```sh
zettel store list
```

The list shows the local store and the declared handbook:

```
(this store)  /path/to/project  0 note(s)
handbook  ../handbook  1 note(s)
```

## Link to a note in the handbook

Use the handbook note's own prefix in place of `pzya`:

```sh
zettel note create "Client retries on 503" -t retries -p human -b "Follows [[handbook:pzya]]."
zettel check
zettel backlinks handbook:pzya
```

The check prints `no problems found`. The backlinks command lists the local note, with its generated prefix:

```
mfq3-client-retries-on-503  Client retries on 503
```

A body link uses the alias and note prefix, as in the command above. For a frontmatter link, use `handbook:pzya` in `links:`. For a provenance citation, use `citation:handbook:pzya` in the marker.

If a link names a missing note, `zettel check` exits 1. It prints `1 problem(s):` with the note and a target such as `→ handbook:zzzz [body]`.

## Check what each tool sees

List the same declarations through the other tools:

```sh
tisket store list
diataxis store list
```

Their handbook rows report:

```
handbook  ../handbook  0 issue(s)
handbook  ../handbook  0 page(s)
```

The handbook has notes but no tracker or docs. One `stores.yml` serves every tool beside it; almanac reads the file for skill libraries too.

Use backlinks and check to follow declared stores. `zettel search` and `zettel read` read only the local store.

## Make declarations available to other clones

For a repository other people clone, set top-level `shared: true` in `stores.yml`. Run the check:

```sh
zettel check
```

With `shared: true`, the check exits 1 for any `path` that leaves the repository, such as `../handbook`. Declare such a store by git URL before sharing the repository.

For remote stores, replace `path` with `git: <https url>` and an optional `rev`, or `blob: <https prefix with an index.txt>`. Declare HTTPS sources; SSH URLs are refused.

Run `<tool> store sync` for each tool that needs the remote store. It fetches remote stores into a local cache and is the only store command that reaches the network. With only path stores, it reports that no remote stores are declared.

Declare repositories in the personal store that annotates them.

[Zettel's composed stores](https://zettel.eng.rip/what-is-zettel/) describe this direction. [Almanac composition](https://almanac.eng.rip/composition/) covers skill libraries.