git.iko.soy/urbit.org
on 8bbc06a help sign in
urbit.org/docs/using/filesystem.md
240 lines 7.1 kB history raw
1---
2navhome: /docs
3next: true
4sort: 6
5title: Filesystem
6---
8# Filesystem (`%clay`)
10<div class="row"> <div class="col-md-8">
12Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
13a typed, global, referentially transparent namespace. An easy way to
14think about it is like typed `git` with continuous sync.
16The most common way to use `%clay` is to mount a `%clay` node in a
17Unix directory. The Urbit process will watch this directory and
18automatically record edits as changes, Dropbox style. The mounted
19directory is always at the root of your pier directory.
21</div> </div>
23## Quickstart
25When developing it's a good idea to use a separate desk.
27Create a `%sandbox` desk based on the `%home` desk:
29 |merge %sandbox ~your-urbit %home
31Most of the time we want to use `%clay` from Unix.
33Mount the entire contents of your `sandbox` desk to Unix:
35 ~your-urbit:dojo> |mount /=sandbox=
37To explore the filesystem from inside Urbit `+ls` and `+cat` are
38useful:
40 ~your-urbit:dojo> +ls /=sandbox=/web
42Let's see the contents of `/=sandbox=/web/md`:
44 ~your-urbit:dojo> +cat /=sandbox=/web/md
46Sync from your friend `~some-ship`'s `%experiment` desk to your
47`%sandbox` desk:
49 |sync %sandbox ~some-ship %experiment
51## Manual
53<h3 class="first child">Paths</h3>
55A path in `%clay` is a list of URL-safe text, restricted to `[a
56z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
57where each segment is a `@ta`.
59Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
60The first three segments of an urbit path are `/plot/desk/case`, for
61example `/~doznec/home/1`.
63#### Relative paths
65Relative paths are expressed using `%` which is roughly equivalent to
66Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
67be. There are no local relative paths. `foo/bar` must be written
68`%/foo/bar`.
70#### Substitution
72If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
73`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
74or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
76Most commonly this is used to avoid having to know the current
77revision number in the `dojo`. Instead of writing
78`/~your-urbit/home/4/path/to/file` you can just write
79`/=home=/path/to/file`.
81### Revision-control
83<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
85Mount the `clay-path` at the unix mount point `unix-name`.
87**Examples:**
89 |mount %/web
91Mounts `%/web` to `/web` inside your pier directory.
93 |mount %/gen generators
95Mounts `%/gen` to `/generators` inside your pier directory.
97### `|unmount [clay-path || unix-name]`
99Unmount the path or name from Unix.
101**Examples:**
103 |unmount %/web
105Unmounts the path `%/web` from whatever name it was mounted as.
107 |unmount %generators
109Unmounts the Unix path `/generators`.
111### `|merge desk beak [strategy]`
113Merges a `beak` into a `desk` using an optional merge `strategy`.
115A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec
116%home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
118**Examples:**
120 |merge %home-work /=home= %fine
122Merge `/=home=` into `%home-work` using merge strategy `%fine`.
124 |merge %examples [~wacbex-ribmex %examples]
126Merge the `%examples` desk from `~waxbex-ribmex`
128### `|sync desk plot [plot-desk]`
130Subscribe to continuous updates from remote `plot` on local `desk`.
131`plot-desk` can specify the remote `desk` name. When omitted it's
132assumed to be the same as `desk`. Moons have `|sync %home ~parent
133%kids` automatically set up (where `~parent` is the planet that issued
134the moon).
136**Examples:**
138 |sync %home-local ~doznec %home |sync %home ~doznec
140### `|unsync desk plot [plot-desk]`
142Unsubscribe from updates from remote `plot` on local `desk` with
143optional `plot-desk`. Arguments must match original `|sync` command
144exactly.
146Example:
148 |unsync %home-local ~doznec %home
150### `|label desk name`
152Label the current version of `desk` `name`.
154Example:
156 |label %home release
158### Merge strategies
160`%init` - Used if it's the first commit to a desk. Also can be
161used to "reinitialize" a desk -- revision numbers keep going up,
162but the new revision isn't necessarily a descendent of the
163previously-numbered version.
165`%this` - Keep what's in Bob's desk, but join the ancestry.
167`%that` - take what's in Alice's desk, but join the ancestry. This is
168the reverse of `%this`. This is different from `%init` because
169the new commit has both sides in its ancestry.
171`%fine` - "fast-forward" merge. This succeeds iff one head is in the
172ancestry of the other.
174`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
175to use as our merge base.
177A `%meet` merge only succeeds if the changes from the merge base to
178Alice's head (hereafter, "Alice's changes") are in different files
179than Bob's changes. In this case, the parents are both Alice's and
180Bob's heads, and the data is the merge base plus Alice's changed files
181plus Bob's changed files.
183A `%mate` merge attempts to merge changes to the same file when both
184Alice and Bob change it. If the merge is clean, we use it; otherwise,
185we fail. A merge between different types of changes -- for example,
186deleting a file vs changing it -- is always a conflict. If we succeed,
187the parents are both Alice's and Bob's heads, and the data is the
188merge base plus Alice's changed files plus Bob's changed files plus
189the merged files.
191A `%meld` merge will succeed even if there are conflicts. If there are
192conflicts in a file, then we use the merge base's version of that
193file, and we produce a set of files with conflicts. The parents are
194both Alice's and Bob's heads, and the data is the merge base plus
195Alice's changed files plus Bob's changed files plus the successfully
196merged files plus the merge base's version of the conflicting files.
198`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
199doesn't we use an `%init` merge. Otherwise, we progressively try
200`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
201merge Bob's desk into a scratch desk. Then, we merge Alice's desk
202into the scratch desk with the `%meld` option to force the merge.
203Finally, we annotate any conflicts, if we know how.
205### Manipulation
207<h3 class="first child"><code>|rm path</code></h3>
209Remove the data at `path`. `path` must be a path to actual node, not
210a 'directory'
212### `|cp to from how`
214Copy the subtree `from` into the subtree `to`, committing it with the
215specified merge strategy `how`.
217#### `|mv to from how`
219Move the subtree `from` into the subtree `to`, committing it with the
220specified merge strategy `how`.
222In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
223doesn't happen unless the `|cp` succeeds.
225### Generators
227<h3 class="first child"><code>+cat path</code> / <code>+cal [path
228...]</code></h3>
230Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of
231paths.
233Produces the contents of the file at the given `path`.
235### `+ls path` / `+ll [path ...]`
237Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of
238paths.
240Produces a list of names at the `path`.