git.iko.soy/urbit.org
on 7258313 help sign in
urbit.org/docs/using/filesystem.md
248 lines 6.9 kB history raw
1---
2navhome: /docs/
3navuptwo: true
4next: true
5sort: 7
6title: Filesystem (Clay)
7---
9# Filesystem (Clay)
11<div class="row">
13<div class="col-md-8">
15Urbit has its own revision-controlled filesystem, Clay. Clay is a
16typed, global, referentially transparent namespace. An easy way to think
17about it is like typed `git` with continuous sync.
19The most common way to use Clay is to mount a Clay node in a Unix
20directory. The Urbit process will watch this directory and automatically
21record edits as changes, Dropbox style. The mounted directory is always
22at the root of your pier directory.
24</div>
26</div>
28## Quickstart
30When developing it's a good idea to use a separate desk.
32Create a `%sandbox` desk based on the `%home` desk:
34 |merge %sandbox ~your-urbit %home
36Most of the time we want to use Clay from Unix.
38Mount the entire contents of your `sandbox` desk to Unix:
40 ~your-urbit:dojo> |mount /=sandbox=
42To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
44 ~your-urbit:dojo> +ls /=sandbox=/web
46Let's see the contents of `/=sandbox=/web/md`:
48 ~your-urbit:dojo> +cat /=sandbox=/web/md
50Sync from your friend `~some-ship`'s `%experiment` desk to your
51`%sandbox` desk:
53 |sync %sandbox ~some-ship %experiment
55## Manual
57<h3 class="first child">
58Paths
59</h3>
61A path in Clay is a list of URL-safe text, restricted to
62`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
63where each segment is a `@ta`.
65Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
66The first three segments of an urbit path are `/plot/desk/case`, for
67example `/~dozbud/home/1`.
69#### Relative paths
71Relative paths are expressed using `%` which is roughly equivalent to
72Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
73There are no local relative paths. `foo/bar` must be written
74`%/foo/bar`.
76#### Substitution
78If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
79`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
80`/=/=/=/voo`, write `/==zoo` or `/===voo`.
82Most commonly this is used to avoid having to know the current revision
83number in the `dojo`. Instead of writing
84`/~your-urbit/home/4/path/to/file` you can just write
85`/=home=/path/to/file`.
87### Revision-control
89<h3 class="first child">
90<code>|mount clay-path [unix-name]</code>
91</h3>
93Mount the `clay-path` at the unix mount point `unix-name`.
95**Examples:**
97 |mount %/web
99Mounts `%/web` to `/web` inside your pier directory.
101 |mount %/gen generators
103Mounts `%/gen` to `/generators` inside your pier directory.
105### `|unmount [clay-path || unix-name]`
107Unmount the path or name from Unix.
109**Examples:**
111 |unmount %/web
113Unmounts the path `%/web` from whatever name it was mounted as.
115 |unmount %generators
117Unmounts the Unix path `/generators`.
119### `|merge desk beak[, =gem strategy]`
121Merges a `beak` into a `desk` using an optional merge `strategy`.
123A `beak` is a ship-desk-case triple, encoded as a
124path(`/~dozbud/home/2`)
126**Examples:**
128 |merge %home-work /=home=, =gem %fine
130Merge `/=home=` into `%home-work` using merge strategy `%fine`.
132 |merge %examples ~wacbex-ribmex %examples
134Merge the `%examples` desk from `~waxbex-ribmex`
136### `|sync desk plot [plot-desk]`
138Subscribe to continuous updates from remote `plot` on local `desk`.
139`plot-desk` can specify the remote `desk` name. When omitted it is
140defaulted to being the same as `desk`. Non-comet urbits have
141`|sync %home ~parent %kids` automatically set up (where `~parent` is the
142planet that issued a moon, the star that issued a planet, or the galaxy
143that issued a star).
145**Examples:**
147 |sync %home-local ~dozbud %home
149 |sync %home ~doznec
151### `|unsync desk plot [plot-desk]`
153Unsubscribe from updates from remote `plot` on local `desk` with
154optional `plot-desk`. Arguments must match original `|sync` command.
156Example:
158 |unsync %home-local ~dozbud %home
160### `|label desk name`
162Label the current version of `desk` `name`.
164Example:
166 |label %home release
168### Merge strategies
170`%init` - Used if it's the first commit to a desk. Also can be used to
171"reinitialize" a desk -- revision numbers keep going up, but the new
172revision isn't necessarily a descendent of the previously-numbered
173version, allowing merges to be rerun.
175`%this` - Keep what's in Bob's desk, but join the ancestry.
177`%that` - take what's in Alice's desk, but join the ancestry. This is
178the reverse of `%this`. This is different from `%init` because the new
179commit has both sides in its ancestry.
181`%fine` - "fast-forward" merge. This succeeds iff one head is in the
182ancestry of the other.
184`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
185use as our merge base.
187A `%meet` merge only succeeds if the changes from the merge base to
188Alice's head (hereafter, "Alice's changes") are in different files than
189Bob's changes. In this case, the parents are both Alice's and Bob's
190heads, and the data is the merge base plus Alice's changed files plus
191Bob's changed files.
193A `%mate` merge attempts to merge changes to the same file when both
194Alice and Bob change it. If the merge is clean, we use it; otherwise, we
195fail. A merge between different types of changes -- for example,
196deleting a file vs changing it -- is always a conflict. If we succeed,
197the parents are both Alice's and Bob's heads, and the data is the merge
198base plus Alice's changed files plus Bob's changed files plus the merged
199files.
201A `%meld` merge will succeed even if there are conflicts. If there are
202conflicts in a file, then we use the merge base's version of that file,
203and we produce a set of files with conflicts. The parents are both
204Alice's and Bob's heads, and the data is the merge base plus Alice's
205changed files plus Bob's changed files plus the successfully merged
206files plus the merge base's version of the conflicting files.
208`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
209doesn't we use an `%init` merge. Otherwise, we progressively try
210`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
211merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
212the scratch desk with the `%meld` option to force the merge. Finally, we
213annotate any conflicts, if we know how.
215### Manipulation
217<h3 class="first child">
218<code>|rm path</code>
219</h3>
221Remove the data at `path`. `path` must be a path to actual node, not a
222'directory'
224### `|cp to from`
226Copy the file at `from` into the path `to`.
228#### `|mv to from`
230Move the file at `from` into the path `to`.
232In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
233doesn't happen unless the `|cp` succeeds.
235### Generators
237<h3 class="first child">
238<code>+cat path [path ...]</code>
239</h3>
241Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
242their contents.
244### `+ls path`
246Similar to Unix `ls`. `+ls` takes a single `path`.
248Produces a list of names at the `path`.