git.iko.soy/urbit.org
on d659381 help sign in
urbit.org/docs/using/filesystem.md
247 lines 6.9 kB history raw
1---
2navhome: '/docs'
3next: True
4sort: 6
5title: Filesystem
6---
8# Filesystem (`%clay`)
10<div class="row">
12<div class="col-md-8">
14Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a
15typed, global, referentially transparent namespace. An easy way to think
16about it is like typed `git` with continuous sync.
18The most common way to use `%clay` is to mount a `%clay` node in a Unix
19directory. The Urbit process will watch this directory and automatically
20record edits as changes, Dropbox style. The mounted directory is always
21at the root of your pier directory.
23</div>
25</div>
27## Quickstart
29When developing it's a good idea to use a separate desk.
31Create a `%sandbox` desk based on the `%home` desk:
33 |merge %sandbox ~your-urbit %home
35Most of the time we want to use `%clay` from Unix.
37Mount the entire contents of your `sandbox` desk to Unix:
39 ~your-urbit:dojo> |mount /=sandbox=
41To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
43 ~your-urbit:dojo> +ls /=sandbox=/web
45Let's see the contents of `/=sandbox=/web/md`:
47 ~your-urbit:dojo> +cat /=sandbox=/web/md
49Sync from your friend `~some-ship`'s `%experiment` desk to your
50`%sandbox` desk:
52 |sync %sandbox ~some-ship %experiment
54## Manual
56<h3 class="first child">
57Paths
58</h3>
60A path in `%clay` is a list of URL-safe text, restricted to
61`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
62where each segment is a `@ta`.
64Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
65The first three segments of an urbit path are `/plot/desk/case`, for
66example `/~dozbud/home/1`.
68#### Relative paths
70Relative paths are expressed using `%` which is roughly equivalent to
71Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
72There are no local relative paths. `foo/bar` must be written
73`%/foo/bar`.
75#### Substitution
77If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
78`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
79`/=/=/=/voo`, write `/==zoo` or `/===voo`.
81Most commonly this is used to avoid having to know the current revision
82number in the `dojo`. Instead of writing
83`/~your-urbit/home/4/path/to/file` you can just write
84`/=home=/path/to/file`.
86### Revision-control
88<h3 class="first child">
89<code>|mount clay-path [unix-name]</code>
90</h3>
92Mount the `clay-path` at the unix mount point `unix-name`.
94**Examples:**
96 |mount %/web
98Mounts `%/web` to `/web` inside your pier directory.
100 |mount %/gen generators
102Mounts `%/gen` to `/generators` inside your pier directory.
104### `|unmount [clay-path || unix-name]`
106Unmount the path or name from Unix.
108**Examples:**
110 |unmount %/web
112Unmounts the path `%/web` from whatever name it was mounted as.
114 |unmount %generators
116Unmounts the Unix path `/generators`.
118### `|merge desk beak[, =gem strategy]`
120Merges a `beak` into a `desk` using an optional merge `strategy`.
122A `beak` is a ship-desk-case triple, encoded as a
123path(`/~dozbud/home/2`)
125**Examples:**
127 |merge %home-work /=home=, =gem %fine
129Merge `/=home=` into `%home-work` using merge strategy `%fine`.
131 |merge %examples ~wacbex-ribmex %examples
133Merge the `%examples` desk from `~waxbex-ribmex`
135### `|sync desk plot [plot-desk]`
137Subscribe to continuous updates from remote `plot` on local `desk`.
138`plot-desk` can specify the remote `desk` name. When omitted it is
139defaulted to being the same as `desk`. Non-comet urbits have
140`|sync %home ~parent %kids` automatically set up (where `~parent` is the
141planet that issued a moon, the star that issued a planet, or the galaxy
142that issued a star).
144**Examples:**
146 |sync %home-local ~dozbud %home
148 |sync %home ~doznec
150### `|unsync desk plot [plot-desk]`
152Unsubscribe from updates from remote `plot` on local `desk` with
153optional `plot-desk`. Arguments must match original `|sync` command.
155Example:
157 |unsync %home-local ~dozbud %home
159### `|label desk name`
161Label the current version of `desk` `name`.
163Example:
165 |label %home release
167### Merge strategies
169`%init` - Used if it's the first commit to a desk. Also can be used to
170"reinitialize" a desk -- revision numbers keep going up, but the new
171revision isn't necessarily a descendent of the previously-numbered
172version, allowing merges to be rerun.
174`%this` - Keep what's in Bob's desk, but join the ancestry.
176`%that` - take what's in Alice's desk, but join the ancestry. This is
177the reverse of `%this`. This is different from `%init` because the new
178commit has both sides in its ancestry.
180`%fine` - "fast-forward" merge. This succeeds iff one head is in the
181ancestry of the other.
183`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
184use as our merge base.
186A `%meet` merge only succeeds if the changes from the merge base to
187Alice's head (hereafter, "Alice's changes") are in different files than
188Bob's changes. In this case, the parents are both Alice's and Bob's
189heads, and the data is the merge base plus Alice's changed files plus
190Bob's changed files.
192A `%mate` merge attempts to merge changes to the same file when both
193Alice and Bob change it. If the merge is clean, we use it; otherwise, we
194fail. A merge between different types of changes -- for example,
195deleting a file vs changing it -- is always a conflict. If we succeed,
196the parents are both Alice's and Bob's heads, and the data is the merge
197base plus Alice's changed files plus Bob's changed files plus the merged
198files.
200A `%meld` merge will succeed even if there are conflicts. If there are
201conflicts in a file, then we use the merge base's version of that file,
202and we produce a set of files with conflicts. The parents are both
203Alice's and Bob's heads, and the data is the merge base plus Alice's
204changed files plus Bob's changed files plus the successfully merged
205files plus the merge base's version of the conflicting files.
207`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
208doesn't we use an `%init` merge. Otherwise, we progressively try
209`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
210merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
211the scratch desk with the `%meld` option to force the merge. Finally, we
212annotate any conflicts, if we know how.
214### Manipulation
216<h3 class="first child">
217<code>|rm path</code>
218</h3>
220Remove the data at `path`. `path` must be a path to actual node, not a
221'directory'
223### `|cp to from`
225Copy the file at `from` into the path `to`.
227#### `|mv to from`
229Move the file at `from` into the path `to`.
231In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
232doesn't happen unless the `|cp` succeeds.
234### Generators
236<h3 class="first child">
237<code>+cat path [path ...]</code>
238</h3>
240Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
241their contents.
243### `+ls path`
245Similar to Unix `ls`. `+ls` takes a single `path`.
247Produces a list of names at the `path`.