git.iko.soy/urbit.org
on fd4ee29 help sign in
urbit.org/docs/using/filesystem.md
234 lines 6.8 kB history raw
1---
2next: true
3sort: 6
4title: Filesystem
5---
7# Filesystem (`%clay`)
9<div class="row"> <div class="col-md-8">
11Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
12a typed, global, referentially transparent namespace. An easy way to
13think about it is like typed `git` with continuous sync.
15The most common way to use `%clay` is to mount a `%clay` node in a
16Unix directory. The Urbit process will watch this directory and
17automatically record edits as changes, Dropbox style. The mounted
18directory is always at the root of your pier directory.
20</div> </div>
22## Quickstart
24When developing it's a good idea to use a separate desk.
26Create a `%sandbox` desk based on the `%home` desk:
28 |merge %sandbox ~your-urbit %home
30Most of the time we want to use `%clay` from Unix.
32Mount the entire contents of your `sandbox` desk to Unix:
34 ~your-urbit:dojo> |mount /=sandbox=
36To explore the filesystem from inside Urbit `+ls` and `+cat` are
37useful:
39 ~your-urbit:dojo> +ls /=sandbox=/web
41Let's see the contents of `/=sandbox=/web/md`:
43 ~your-urbit:dojo> +cat /=sandbox=/web/md
45Sync from your friend `~some-ship`'s `%experiment` desk to your
46`%sandbox` desk:
48 |sync %sandbox ~some-ship %experiment
50## Manual
52<h3 class="first child">Paths</h3>
54A path in `%clay` is a list of URL-safe text, restricted to `[a
55z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
56where each segment is a `@ta`.
58Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
59The first three segments of an urbit path are `/plot/desk/case`, for
60example `/~doznec/home/1`.
62#### Relative paths
64Relative paths are expressed using `%` which is roughly equivalent to
65Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
66be. There are no local relative paths. `foo/bar` must be written
67`%/foo/bar`.
69#### Substitution
71If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
72`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
73or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
75Most commonly this is used to avoid having to know the current
76revision number in the `dojo`. Instead of writing
77`/~your-urbit/home/4/path/to/file` you can just write
78`/=home=/path/to/file`.
80### Revision-control
82<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
84Mount the `clay-path` at the unix mount point `unix-name`.
86**Examples:**
88 |mount %/web
90Mounts `%/web` to `/web` inside your pier directory.
92 |mount %/gen generators
94Mounts `%/gen` to `/generators` inside your pier directory.
96### `|unmount [clay-path || unix-name]`
98Unmount the path or name from Unix.
100**Examples:**
102 |unmount %/web
104Unmounts the path `%/web` from whatever name it was mounted as.
106 |unmount %generators
108Unmounts the Unix path `/generators`.
110### `|merge desk beak [strategy]`
112Merges a `beak` into a `desk` using an optional merge `strategy`.
114A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec
115%home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
117**Examples:**
119 |merge %home-work /=home= %fine
121Merge `/=home=` into `%home-work` using merge strategy `%fine`.
123 |merge %examples [~wacbex-ribmex %examples]
125Merge the `%examples` desk from `~waxbex-ribmex`
127### `|sync desk plot [plot-desk]`
129Subscribe to continuous updates from remote `plot` on local `desk`.
130`plot-desk` can specify the remote `desk` name. When omitted it's
131assumed to be the same as `desk`. Moons have `|sync %home ~parent
132%kids` automatically set up (where `~parent` is the planet that issued
133the moon).
135**Examples:**
137 |sync %home-local ~doznec %home |sync %home ~doznec
139### `|unsync desk plot [plot-desk]`
141Unsubscribe from updates from remote `plot` on local `desk` with
142optional `plot-desk`. Arguments must match original `|sync` command
143exactly.
145Example:
147 |unsync %home-local ~doznec %home
149### `|label desk name`
151Label the current version of `desk` `name`.
153Example:
155 |label %home release
157### Merge strategies
159`%init` - Used iff it's the first commit to a desk.
161`%this` - Keep what's in Bob's desk, but join the ancestry.
163`%that` - take what's in Alice's desk, but join the ancestry. This is
164the reverse of `%this`.
166`%fine` - "fast-forward" merge. This succeeds iff one head is in the
167ancestry of the other.
169`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
170to use as our merge base.
172A `%meet` merge only succeeds if the changes from the merge base to
173Alice's head (hereafter, "Alice's changes") are in different files
174than Bob's changes. In this case, the parents are both Alice's and
175Bob's heads, and the data is the merge base plus Alice's changed files
176plus Bob's changed files.
178A `%mate` merge attempts to merge changes to the same file when both
179Alice and Bob change it. If the merge is clean, we use it; otherwise,
180we fail. A merge between different types of changes -- for example,
181deleting a file vs changing it -- is always a conflict. If we succeed,
182the parents are both Alice's and Bob's heads, and the data is the
183merge base plus Alice's changed files plus Bob's changed files plus
184the merged files.
186A `%meld` merge will succeed even if there are conflicts. If there are
187conflicts in a file, then we use the merge base's version of that
188file, and we produce a set of files with conflicts. The parents are
189both Alice's and Bob's heads, and the data is the merge base plus
190Alice's changed files plus Bob's changed files plus the successfully
191merged files plus the merge base's version of the conflicting files.
193`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
194doesn't we use an `%init` merge. Otherwise, we progressively try
195`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
196merge Bob's desk into a scratch desk. Then, we merge Alice's desk
197into the scratch desk with the `%meld` option to force the merge.
199### Manipulation
201<h3 class="first child"><code>|rm path</code></h3>
203Remove the data at `path`. `path` must be a path to actual node, not
204a 'directory'
206### `|cp to from how`
208Copy the subtree `from` into the subtree `to`, committing it with the
209specified merge strategy `how`.
211#### `|mv to from how`
213Move the subtree `from` into the subtree `to`, committing it with the
214specified merge strategy `how`.
216In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
217doesn't happen unless the `|cp` succeeds.
219### Generators
221<h3 class="first child"><code>+cat path</code> / <code>+cal [path
222...]</code></h3>
224Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of
225paths.
227Produces the contents of the file at the given `path`.
229### `+ls path` / `+ll [path ...]`
231Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of
232paths.
234Produces a list of names at the `path`.