@@ -6,18 +6,18 @@ title: Filesystem
66
77# Filesystem (`%clay`)
88
9−<div class="row">
10−<div class="col-md-8">
9+<div class="row"> <div class="col-md-8">
1110
12−Urbit 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.
11+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
12+a typed, global, referentially transparent namespace. An easy way to
13+think about it is like typed `git` with continuous sync.
1314
14−The most common way to use `%clay` is to mount a `%clay` node in
15−a Unix directory. The Urbit process will watch this directory
16−and automatically record edits as changes, Dropbox style. The
17−mounted directory is always at the root of your pier directory.
15+The most common way to use `%clay` is to mount a `%clay` node in a
16+Unix directory. The Urbit process will watch this directory and
17+automatically record edits as changes, Dropbox style. The mounted
18+directory is always at the root of your pier directory.
1819
19−</div>
20−</div>
20+</div> </div>
2121
2222## Quickstart
2323
@@ -33,7 +33,8 @@ Mount the entire contents of your `sandbox` desk to Unix:
3333
3434 ~your-urbit:dojo> |mount /=sandbox=
3535
36−To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
36+To explore the filesystem from inside Urbit `+ls` and `+cat` are
37+useful:
3738
3839 ~your-urbit:dojo> +ls /=sandbox=/web
3940
@@ -41,7 +42,8 @@ Let's see the contents of `/=sandbox=/web/md`:
4142
4243 ~your-urbit:dojo> +cat /=sandbox=/web/md
4344
44−Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
45+Sync from your friend `~some-ship`'s `%experiment` desk to your
46+`%sandbox` desk:
4547
4648 |sync %sandbox ~some-ship %experiment
4749
@@ -49,21 +51,31 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
4951
5052<h3 class="first child">Paths</h3>
5153
52−A path in `%clay` is a list of URL-safe text, restricted to `[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)` where each segment is a `@ta`.
54+A path in `%clay` is a list of URL-safe text, restricted to `[a
55+z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)`
56+where each segment is a `@ta`.
5357
54−Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`. The first three segments of an urbit path are `/plot/desk/case`, for example `/~doznec/home/1`.
58+Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
59+The first three segments of an urbit path are `/plot/desk/case`, for
60+example `/~doznec/home/1`.
5561
5662#### Relative paths
5763
58−Relative paths are expressed using `%` which is roughly equivalent to Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be. There are no local relative paths. `foo/bar` must be written `%/foo/bar`.
64+Relative paths are expressed using `%` which is roughly equivalent to
65+Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to
66+be. There are no local relative paths. `foo/bar` must be written
67+`%/foo/bar`.
5968
6069#### Substitution
6170
62−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
63−and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
64−`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
71+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
72+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
73+or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
6574
66−Most commonly this is used to avoid having to know the current revision number in the `dojo`. Instead of writing `/~your-urbit/home/4/path/to/file` you can just write `/=home=/path/to/file`.
75+Most commonly this is used to avoid having to know the current
76+revision number in the `dojo`. Instead of writing
77+`/~your-urbit/home/4/path/to/file` you can just write
78+`/=home=/path/to/file`.
6779
6880### Revision-control
6981
@@ -99,7 +111,8 @@ Unmounts the Unix path `/generators`.
99111
100112Merges a `beak` into a `desk` using an optional merge `strategy`.
101113
102−A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec %home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
114+A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec
115+%home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
103116
104117**Examples:**
105118
@@ -113,16 +126,21 @@ Merge the `%examples` desk from `~waxbex-ribmex`
113126
114127### `|sync desk plot [plot-desk]`
115128
116−Subscribe to continuous updates from remote `plot` on local `desk`. `plot-desk` can specify the remote `desk` name. When omitted it's assumed to be the same as `desk`. Moons have `|sync %home ~parent %kids` automatically set up (where `~parent` is the planet that issued the moon).
129+Subscribe to continuous updates from remote `plot` on local `desk`.
130+`plot-desk` can specify the remote `desk` name. When omitted it's
131+assumed to be the same as `desk`. Moons have `|sync %home ~parent
132+%kids` automatically set up (where `~parent` is the planet that issued
133+the moon).
117134
118135**Examples:**
119136
120− |sync %home-local ~doznec %home
121− |sync %home ~doznec
137+ |sync %home-local ~doznec %home |sync %home ~doznec
122138
123139### `|unsync desk plot [plot-desk]`
124140
125−Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
141+Unsubscribe from updates from remote `plot` on local `desk` with
142+optional `plot-desk`. Arguments must match original `|sync` command
143+exactly.
126144
127145Example:
128146
@@ -136,72 +154,81 @@ Example:
136154
137155 |label %home release
138156
139−
140157### Merge strategies
141158
142159`%init` - Used iff it's the first commit to a desk.
143160
144161`%this` - Keep what's in Bob's desk, but join the ancestry.
145162
146−`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
147−
148−`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
149−
150−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
151−
152−A `%meet` merge only succeeds if the changes from the merge base
153−to Alice's head (hereafter, "Alice's changes") are in different
154−files than Bob's changes. In this case, the parents are both
155−Alice's and Bob's heads, and the data is the merge base plus
156−Alice's changed files plus Bob's changed files.
157−
158−A `%mate` merge attempts to merge changes to the same file when
159−both Alice and Bob change it. If the merge is clean, we use it;
160−otherwise, we fail. A merge between different types of changes --
161−for example, deleting a file vs changing it -- is always a
162−conflict. If we succeed, the parents are both Alice's and Bob's
163−heads, and the data is the merge base plus Alice's changed files
164−plus Bob's changed files plus the merged files.
165−
166−A `%meld` merge will succeed even if there are conflicts. If
167−there are conflicts in a file, then we use the merge base's
168−version of that file, and we produce a set of files with
169−conflicts. The parents are both Alice's and Bob's heads, and the
170−data is the merge base plus Alice's changed files plus Bob's
171−changed files plus the successfully merged files plus the merge
172−base's version of the conflicting files.
173−
174−`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it doesn't we use an `%init` merge. Otherwise, we progressively try `%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we merge Bob's desk into a scratch desk. Then, we merge Alice's desk into the scratch desk with the `%meld` option to force the merge.
163+`%that` - take what's in Alice's desk, but join the ancestry. This is
164+the reverse of `%this`.
165+
166+`%fine` - "fast-forward" merge. This succeeds iff one head is in the
167+ancestry of the other.
168+
169+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
170+to use as our merge base.
171+
172+A `%meet` merge only succeeds if the changes from the merge base to
173+Alice's head (hereafter, "Alice's changes") are in different files
174+than Bob's changes. In this case, the parents are both Alice's and
175+Bob's heads, and the data is the merge base plus Alice's changed files
176+plus Bob's changed files.
177+
178+A `%mate` merge attempts to merge changes to the same file when both
179+Alice and Bob change it. If the merge is clean, we use it; otherwise,
180+we fail. A merge between different types of changes -- for example,
181+deleting a file vs changing it -- is always a conflict. If we succeed,
182+the parents are both Alice's and Bob's heads, and the data is the
183+merge base plus Alice's changed files plus Bob's changed files plus
184+the merged files.
185+
186+A `%meld` merge will succeed even if there are conflicts. If there are
187+conflicts in a file, then we use the merge base's version of that
188+file, and we produce a set of files with conflicts. The parents are
189+both Alice's and Bob's heads, and the data is the merge base plus
190+Alice's changed files plus Bob's changed files plus the successfully
191+merged files plus the merge base's version of the conflicting files.
192+
193+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
194+doesn't we use an `%init` merge. Otherwise, we progressively try
195+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
196+merge Bob's desk into a scratch desk. Then, we merge Alice's desk
197+into the scratch desk with the `%meld` option to force the merge.
175198
176199### Manipulation
177200
178201<h3 class="first child"><code>|rm path</code></h3>
179202
180−Remove the data at `path`. `path` must be a path to actual node, not a 'directory'
203+Remove the data at `path`. `path` must be a path to actual node, not
204+a 'directory'
181205
182206### `|cp to from how`
183207
184−Copy the subtree `from` into the subtree `to`, committing it with
185−the specified merge strategy `how`.
208+Copy the subtree `from` into the subtree `to`, committing it with the
209+specified merge strategy `how`.
186210
187211#### `|mv to from how`
188212
189−Move the subtree `from` into the subtree `to`, committing it with
190−the specified merge strategy `how`.
213+Move the subtree `from` into the subtree `to`, committing it with the
214+specified merge strategy `how`.
191215
192−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
193−`|rm` doesn't happen unless the `|cp` succeeds.
216+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
217+doesn't happen unless the `|cp` succeeds.
194218
195219### Generators
196220
197−<h3 class="first child"><code>+cat path</code> / <code>+cal [path ...]</code></h3>
221+<h3 class="first child"><code>+cat path</code> / <code>+cal [path
222+...]</code></h3>
198223
199−Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of paths.
224+Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of
225+paths.
200226
201227Produces the contents of the file at the given `path`.
202228
203229### `+ls path` / `+ll [path ...]`
204230
205−Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of paths.
231+Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of
232+paths.
206233
207234Produces a list of names at the `path`.