git.iko.soy/urbit.org
on 7fa97bd help sign in
urbit.org/docs/using/filesystem.umd
265 lines 6.9 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'7'
5 title/'Filesystem (Clay)'
6 ==
7;>
9# Filesystem (Clay)
12Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global, referentially transparent namespace. An easy way to think about it is like typed `git` with continuous sync.
14The most common way to use Clay is to mount a Clay node in a Unix directory. The Urbit process will watch this directory and automatically record edits as changes, Dropbox style. The mounted directory is always at the root of your pier directory.
17## Quickstart
19When developing it's a good idea to use a separate desk. Create a `%sandbox` desk based on the `%home` desk:
21```
22|merge %sandbox ~your-urbit %home
23```
25Most of the time we want to use Clay from Unix. Mount the entire contents of your `sandbox` desk to Unix:
27```
28~your-urbit:dojo> |mount /=sandbox=
29```
31To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
33```
34~your-urbit:dojo> +ls /=sandbox=/web
35```
37Let's see the contents of `/=sandbox=/web/md`:
39```
40~your-urbit:dojo> +cat /=sandbox=/web/md
41```
43Sync from your friend `~some-ship`'s `%experiment` desk to your
44`%sandbox` desk:
46```
47|sync %sandbox ~some-ship %experiment
48```
50## Manual
52### Paths
54A path in Clay is a list of URL-safe text, restricted to
55`[a z]`,`[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 `/~dozbud/home/1`.
62#### Relative paths
64Relative paths are expressed using `%` which is roughly equivalent to
65Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
66There 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` or
73`/=/=/=/voo`, write `/==zoo` or `/===voo`.
75Most commonly this is used to avoid having to know the current revision
76number 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```
83|mount clay-path [unix-name]
84```
86Mount the `clay-path` at the unix mount point `unix-name`.
88*Examples:*
90```
91|mount %/web
92```
94Mounts `%/web` to `/web` inside your pier directory.
96```
97|mount %/gen generators
98```
100Mounts `%/gen` to `/generators` inside your pier directory.
102```
103|unmount [clay-path || unix-name]
104```
106Unmount the path or name from Unix.
108*Examples:*
110```
111|unmount %/web
112```
114Unmounts the path `%/web` from whatever name it was mounted as.
116```
117|unmount %generators
118```
120Unmounts the Unix path `/generators`.
122```
123|merge desk beak[, =gem strategy]
124```
126Merges a `beak` into a `desk` using an optional merge `strategy`.
128A `beak` is a ship-desk-case triple, encoded as a
129path(`/~dozbud/home/2`)
131*Examples:*
133```
134|merge %home-work /=home=, =gem %fine
135```
137Merge `/=home=` into `%home-work` using merge strategy `%fine`.
139```
140|merge %examples ~wacbex-ribmex %examples
141```
143Merge the `%examples` desk from `~waxbex-ribmex`
145```
146|sync desk plot [plot-desk]
147```
149Subscribe to continuous updates from remote `plot` on local `desk`.
150`plot-desk` can specify the remote `desk` name. When omitted it is
151defaulted to being the same as `desk`. Non-comet urbits have
152`|sync %home ~parent %kids` automatically set up (where `~parent` is the
153planet that issued a moon, the star that issued a planet, or the galaxy
154that issued a star).
156*Examples:*
158```
159|sync %home-local ~dozbud %home
161|sync %home ~doznec
162```
164```
165|unsync desk plot [plot-desk]
166```
168Unsubscribe from updates from remote `plot` on local `desk` with
169optional `plot-desk`. Arguments must match original `|sync` command.
171Example:
173```
174|unsync %home-local ~dozbud %home
175```
177```
178|label desk name`
179```
181Label the current version of `desk` `name`.
183Example:
185```
186|label %home release
187```
189### Merge strategies
191`%init` - Used if it's the first commit to a desk. Also can be used to
192"reinitialize" a desk -- revision numbers keep going up, but the new
193revision isn't necessarily a descendent of the previously-numbered
194version, allowing merges to be rerun.
196`%this` - Keep what's in Bob's desk, but join the ancestry.
198`%that` - take what's in Alice's desk, but join the ancestry. This is
199the reverse of `%this`. This is different from `%init` because the new
200commit has both sides in its ancestry.
202`%fine` - "fast-forward" merge. This succeeds iff one head is in the
203ancestry of the other.
205`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
206use as our merge base.
208A `%meet` merge only succeeds if the changes from the merge base to
209Alice's head (hereafter, "Alice's changes") are in different files than
210Bob's changes. In this case, the parents are both Alice's and Bob's
211heads, and the data is the merge base plus Alice's changed files plus
212Bob's changed files.
214A `%mate` merge attempts to merge changes to the same file when both
215Alice and Bob change it. If the merge is clean, we use it; otherwise, we
216fail. A merge between different types of changes -- for example,
217deleting a file vs changing it -- is always a conflict. If we succeed,
218the parents are both Alice's and Bob's heads, and the data is the merge
219base plus Alice's changed files plus Bob's changed files plus the merged
220files.
222A `%meld` merge will succeed even if there are conflicts. If there are
223conflicts in a file, then we use the merge base's version of that file,
224and we produce a set of files with conflicts. The parents are both
225Alice's and Bob's heads, and the data is the merge base plus Alice's
226changed files plus Bob's changed files plus the successfully merged
227files plus the merge base's version of the conflicting files.
229`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
230doesn't we use an `%init` merge. Otherwise, we progressively try
231`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
232merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
233the scratch desk with the `%meld` option to force the merge. Finally, we
234annotate any conflicts, if we know how.
236### Manipulation
238#### `|rm path`
240Remove the data at `path`. `path` must be a path to actual node, not a
241'directory'
243#### `|cp to from`
245Copy the file at `from` into the path `to`.
247#### `|mv to from`
249Move the file at `from` into the path `to`.
251In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
252doesn't happen unless the `|cp` succeeds.
254### Generators
256#### `+cat path [path ...]`
258Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
259their contents.
261### `+ls path`
263Similar to Unix `ls`. `+ls` takes a single `path`.
265Produces a list of names at the `path`.