git.iko.soy/urbit.org
on bdf9204 help sign in
urbit.org/docs/using/filesystem.md
231 lines 6.9 kB history raw
1---
2navhome: '/docs'
3next: True
4sort: 6
5title: Filesystem
6---
8# Filesystem (`%clay`)
10<div class="row">
11<div class="col-md-8">
12Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a typed,
13global, referentially transparent namespace. An easy way to think about it is
14like typed `git` with continuous sync.
16The most common way to use `%clay` is to mount a `%clay` node in a Unix
17directory. The Urbit process will watch this directory and automatically record
18edits as changes, Dropbox style. The mounted directory is always at the root of
19your pier directory.
21</div>
22</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 useful:
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 `%sandbox` desk:
47 |sync %sandbox ~some-ship %experiment
49## Manual
51<h3 class="first child">
52Paths
53</h3>
54A path in `%clay` is a list of URL-safe text, restricted to `[a z]`,`[0 9]`,
55`.`, `-`, `_` and `~`. Formally this is a `(list knot)` where each segment is a
56`@ta`.
58Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`. The first
59three segments of an urbit path are `/plot/desk/case`, for example
60`/~dozbud/home/1`.
62#### Relative paths
64Relative paths are expressed using `%` which is roughly equivalent to Unix `.`.
65`%%` is `..` and `%%%` is what you would expect `...` to be. There are no local
66relative paths. `foo/bar` must be written `%/foo/bar`.
68#### Substitution
70If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
71`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
72`/=/=/=/voo`, write `/==zoo` or `/===voo`.
74Most commonly this is used to avoid having to know the current revision number
75in the `dojo`. Instead of writing `/~your-urbit/home/4/path/to/file` you can
76just write `/=home=/path/to/file`.
78### Revision-control
80<h3 class="first child">
81<code>|mount clay-path \[unix-name\]</code>
82</h3>
83Mount the `clay-path` at the unix mount point `unix-name`.
85**Examples:**
87 |mount %/web
89Mounts `%/web` to `/web` inside your pier directory.
91 |mount %/gen generators
93Mounts `%/gen` to `/generators` inside your pier directory.
95### `|unmount [clay-path || unix-name]`
97Unmount the path or name from Unix.
99**Examples:**
101 |unmount %/web
103Unmounts the path `%/web` from whatever name it was mounted as.
105 |unmount %generators
107Unmounts the Unix path `/generators`.
109### `|merge desk beak[, =gem strategy]`
111Merges a `beak` into a `desk` using an optional merge `strategy`.
113A `beak` is a ship-desk-case triple, encoded as a path(`/~dozbud/home/2`)
115**Examples:**
117 |merge %home-work /=home=, =gem %fine
119Merge `/=home=` into `%home-work` using merge strategy `%fine`.
121 |merge %examples ~wacbex-ribmex %examples
123Merge the `%examples` desk from `~waxbex-ribmex`
125### `|sync desk plot [plot-desk]`
127Subscribe to continuous updates from remote `plot` on local `desk`. `plot-desk`
128can specify the remote `desk` name. When omitted it is defaulted to being the
129same as `desk`. Non-comet urbits have `|sync %home ~parent %kids` automatically
130set up (where `~parent` is the planet that issued a moon, the star that issued a
131planet, or the galaxy that issued a star).
133**Examples:**
135 |sync %home-local ~dozbud %home
137 |sync %home ~doznec
139### `|unsync desk plot [plot-desk]`
141Unsubscribe from updates from remote `plot` on local `desk` with optional
142`plot-desk`. Arguments must match original `|sync` command.
144Example:
146 |unsync %home-local ~dozbud %home
148### `|label desk name`
150Label the current version of `desk` `name`.
152Example:
154 |label %home release
156### Merge strategies
158`%init` - Used if it's the first commit to a desk. Also can be used to
159"reinitialize" a desk -- revision numbers keep going up, but the new revision
160isn't necessarily a descendent of the previously-numbered version, allowing
161merges to be rerun.
163`%this` - Keep what's in Bob's desk, but join the ancestry.
165`%that` - take what's in Alice's desk, but join the ancestry. This is the
166reverse of `%this`. This is different from `%init` because the new commit has
167both sides in its ancestry.
169`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of
170the other.
172`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as
173our merge base.
175A `%meet` merge only succeeds if the changes from the merge base to Alice's head
176(hereafter, "Alice's changes") are in different files than Bob's changes. In
177this case, the parents are both Alice's and Bob's heads, and the data is the
178merge base plus Alice's changed files plus Bob's changed files.
180A `%mate` merge attempts to merge changes to the same file when both Alice and
181Bob change it. If the merge is clean, we use it; otherwise, we fail. A merge
182between different types of changes -- for example, deleting a file vs changing
183it -- is always a conflict. If we succeed, the parents are both Alice's and
184Bob's heads, and the data is the merge base plus Alice's changed files plus
185Bob's changed files plus the merged files.
187A `%meld` merge will succeed even if there are conflicts. If there are conflicts
188in a file, then we use the merge base's version of that file, and we produce a
189set of files with conflicts. The parents are both Alice's and Bob's heads, and
190the data is the merge base plus Alice's changed files plus Bob's changed files
191plus the successfully merged files plus the merge base's version of the
192conflicting files.
194`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it doesn't we
195use an `%init` merge. Otherwise, we progressively try `%fine`, `%meet`, and
196`%mate` until one succeeds. If none succeed, we merge Bob's desk into a scratch
197desk. Then, we merge Alice's desk into the scratch desk with the `%meld` option
198to force the merge. Finally, we annotate any conflicts, if we know how.
200### Manipulation
202<h3 class="first child">
203<code>|rm path</code>
204</h3>
205Remove the data at `path`. `path` must be a path to actual node, not a
206'directory'
208### `|cp to from`
210Copy the file at `from` into the path `to`.
212#### `|mv to from`
214Move the file at `from` into the path `to`.
216In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm` doesn't
217happen unless the `|cp` succeeds.
219### Generators
221<h3 class="first child">
222<code>+cat path \[path ...\]</code>
223</h3>
224Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
225contents.
227### `+ls path`
229Similar to Unix `ls`. `+ls` takes a single `path`.
231Produces a list of names at the `path`.