@@ -1,24 +1,28 @@
11---
2−navhome: /docs
3−next: true
2+navhome: '/docs'
3+next: True
44sort: 6
55title: Filesystem
66---
77
88# Filesystem (`%clay`)
99
10−<div class="row"> <div class="col-md-8">
10+<div class="row">
1111
12−Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
13−a typed, global, referentially transparent namespace. An easy way to
14−think about it is like typed `git` with continuous sync.
12+<div class="col-md-8">
1513
16−The most common way to use `%clay` is to mount a `%clay` node in a
17−Unix directory. The Urbit process will watch this directory and
18−automatically record edits as changes, Dropbox style. The mounted
19−directory is always at the root of your pier directory.
14+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is a
15+typed, global, referentially transparent namespace. An easy way to think
16+about it is like typed `git` with continuous sync.
2017
21−</div> </div>
18+The most common way to use `%clay` is to mount a `%clay` node in a Unix
19+directory. The Urbit process will watch this directory and automatically
20+record edits as changes, Dropbox style. The mounted directory is always
21+at the root of your pier directory.
22+
23+</div>
24+
25+</div>
2226
2327## Quickstart
2428
@@ -28,14 +32,13 @@ Create a `%sandbox` desk based on the `%home` desk:
2832
2933 |merge %sandbox ~your-urbit %home
3034
31−Most of the time we want to use `%clay` from Unix.
35+Most of the time we want to use `%clay` from Unix.
3236
3337Mount the entire contents of your `sandbox` desk to Unix:
3438
3539 ~your-urbit:dojo> |mount /=sandbox=
3640
37−To explore the filesystem from inside Urbit `+ls` and `+cat` are
38−useful:
41+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
3942
4043 ~your-urbit:dojo> +ls /=sandbox=/web
4144
@@ -50,37 +53,41 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your
5053
5154## Manual
5255
53−<h3 class="first child">Paths</h3>
56+<h3 class="first child">
57+Paths
58+</h3>
5459
55−A path in `%clay` is a list of URL-safe text, restricted to `[a
56−z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
60+A path in `%clay` is a list of URL-safe text, restricted to
61+`[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
5762where each segment is a `@ta`.
5863
5964Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
6065The first three segments of an urbit path are `/plot/desk/case`, for
61−example `/~doznec/home/1`.
66+example `/~dozbud/home/1`.
6267
6368#### Relative paths
6469
6570Relative paths are expressed using `%` which is roughly equivalent to
66−Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
67−be. There are no local relative paths. `foo/bar` must be written
71+Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.
72+There are no local relative paths. `foo/bar` must be written
6873`%/foo/bar`.
6974
7075#### Substitution
7176
7277If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
73−`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
74−or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
78+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or
79+`/=/=/=/voo`, write `/==zoo` or `/===voo`.
7580
76−Most commonly this is used to avoid having to know the current
77−revision number in the `dojo`. Instead of writing
81+Most commonly this is used to avoid having to know the current revision
82+number in the `dojo`. Instead of writing
7883`/~your-urbit/home/4/path/to/file` you can just write
7984`/=home=/path/to/file`.
8085
8186### Revision-control
8287
83−<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
88+<h3 class="first child">
89+<code>|mount clay-path [unix-name]</code>
90+</h3>
8491
8592Mount the `clay-path` at the unix mount point `unix-name`.
8693
@@ -112,7 +119,8 @@ Unmounts the Unix path `/generators`.
112119
113120Merges a `beak` into a `desk` using an optional merge `strategy`.
114121
115−A `beak` is a ship-desk-case triple, encoded as a path(`/~doznec/home/2`)
122+A `beak` is a ship-desk-case triple, encoded as a
123+path(`/~dozbud/home/2`)
116124
117125**Examples:**
118126
@@ -127,24 +135,24 @@ Merge the `%examples` desk from `~waxbex-ribmex`
127135### `|sync desk plot [plot-desk]`
128136
129137Subscribe to continuous updates from remote `plot` on local `desk`.
130−`plot-desk` can specify the remote `desk` name. When omitted it is
131−defaulted to being the same as `desk`. Non-comet urbits have `|sync
132−%home ~parent %kids` automatically set up (where `~parent` is the
133−planet that issued a moon, the star that issued a planet, or the
134−galaxy that issued a star).
138+`plot-desk` can specify the remote `desk` name. When omitted it is
139+defaulted to being the same as `desk`. Non-comet urbits have
140+`|sync %home ~parent %kids` automatically set up (where `~parent` is the
141+planet that issued a moon, the star that issued a planet, or the galaxy
142+that issued a star).
135143
136144**Examples:**
137145
138− |sync %home-local ~doznec %home |sync %home ~doznec
146+ |sync %home-local ~dozbud %home |sync %home ~doznec
139147
140148### `|unsync desk plot [plot-desk]`
141149
142150Unsubscribe from updates from remote `plot` on local `desk` with
143−optional `plot-desk`. Arguments must match original `|sync` command.
151+optional `plot-desk`. Arguments must match original `|sync` command.
144152
145153Example:
146154
147− |unsync %home-local ~doznec %home
155+ |unsync %home-local ~dozbud %home
148156
149157### `|label desk name`
150158
@@ -156,57 +164,59 @@ Example:
156164
157165### Merge strategies
158166
159−`%init` - Used if it's the first commit to a desk. Also can be
160−used to "reinitialize" a desk -- revision numbers keep going up,
161−but the new revision isn't necessarily a descendent of the
162−previously-numbered version, allowing merges to be rerun.
167+`%init` - Used if it's the first commit to a desk. Also can be used to
168+"reinitialize" a desk -- revision numbers keep going up, but the new
169+revision isn't necessarily a descendent of the previously-numbered
170+version, allowing merges to be rerun.
163171
164172`%this` - Keep what's in Bob's desk, but join the ancestry.
165173
166174`%that` - take what's in Alice's desk, but join the ancestry. This is
167−the reverse of `%this`. This is different from `%init` because
168−the new commit has both sides in its ancestry.
175+the reverse of `%this`. This is different from `%init` because the new
176+commit has both sides in its ancestry.
169177
170178`%fine` - "fast-forward" merge. This succeeds iff one head is in the
171179ancestry of the other.
172180
173−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
174−to use as our merge base.
181+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
182+use as our merge base.
175183
176184A `%meet` merge only succeeds if the changes from the merge base to
177−Alice's head (hereafter, "Alice's changes") are in different files
178−than Bob's changes. In this case, the parents are both Alice's and
179−Bob's heads, and the data is the merge base plus Alice's changed files
180−plus Bob's changed files.
185+Alice's head (hereafter, "Alice's changes") are in different files than
186+Bob's changes. In this case, the parents are both Alice's and Bob's
187+heads, and the data is the merge base plus Alice's changed files plus
188+Bob's changed files.
181189
182190A `%mate` merge attempts to merge changes to the same file when both
183−Alice and Bob change it. If the merge is clean, we use it; otherwise,
184−we fail. A merge between different types of changes -- for example,
191+Alice and Bob change it. If the merge is clean, we use it; otherwise, we
192+fail. A merge between different types of changes -- for example,
185193deleting a file vs changing it -- is always a conflict. If we succeed,
186−the parents are both Alice's and Bob's heads, and the data is the
187−merge base plus Alice's changed files plus Bob's changed files plus
188−the merged files.
194+the parents are both Alice's and Bob's heads, and the data is the merge
195+base plus Alice's changed files plus Bob's changed files plus the merged
196+files.
189197
190198A `%meld` merge will succeed even if there are conflicts. If there are
191−conflicts in a file, then we use the merge base's version of that
192−file, and we produce a set of files with conflicts. The parents are
193−both Alice's and Bob's heads, and the data is the merge base plus
194−Alice's changed files plus Bob's changed files plus the successfully
195−merged files plus the merge base's version of the conflicting files.
196−
197−`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
198−doesn't we use an `%init` merge. Otherwise, we progressively try
199−`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
200−merge Bob's desk into a scratch desk. Then, we merge Alice's desk
201−into the scratch desk with the `%meld` option to force the merge.
202−Finally, we annotate any conflicts, if we know how.
199+conflicts in a file, then we use the merge base's version of that file,
200+and we produce a set of files with conflicts. The parents are both
201+Alice's and Bob's heads, and the data is the merge base plus Alice's
202+changed files plus Bob's changed files plus the successfully merged
203+files plus the merge base's version of the conflicting files.
204+
205+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
206+doesn't we use an `%init` merge. Otherwise, we progressively try
207+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
208+merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
209+the scratch desk with the `%meld` option to force the merge. Finally, we
210+annotate any conflicts, if we know how.
203211
204212### Manipulation
205213
206−<h3 class="first child"><code>|rm path</code></h3>
214+<h3 class="first child">
215+<code>|rm path</code>
216+</h3>
207217
208−Remove the data at `path`. `path` must be a path to actual node, not
209−a 'directory'
218+Remove the data at `path`. `path` must be a path to actual node, not a
219+'directory'
210220
211221### `|cp to from`
212222
@@ -216,14 +226,16 @@ Copy the file at `from` into the path `to`.
216226
217227Move the file at `from` into the path `to`.
218228
219−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
229+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
220230doesn't happen unless the `|cp` succeeds.
221231
222232### Generators
223233
224−<h3 class="first child"><code>+cat path [path ...]</code></h3>
234+<h3 class="first child">
235+<code>+cat path [path ...]</code>
236+</h3>
225237
226−Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
238+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints
227239their contents.
228240
229241### `+ls path`