@@ -6,18 +6,18 @@ title: Filesystem
7# Filesystem (`%clay`)
7# Filesystem (`%clay`)
10−<div class="col-md-8">
9+<div class="row"> <div class="col-md-8">
11+Urbit has its own revision-controlled filesystem, `%clay`. `%clay` is
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.
12+a typed, global, referentially transparent namespace. An easy way to
13+think about it is like typed `git` with continuous sync.
14−The most common way to use `%clay` is to mount a `%clay` node in
15+The most common way to use `%clay` is to mount a `%clay` node in a
15−a Unix directory. The Urbit process will watch this directory
16+Unix directory. The Urbit process will watch this directory and
16−and automatically record edits as changes, Dropbox style. The
17+automatically record edits as changes, Dropbox style. The mounted
17−mounted directory is always at the root of your pier directory.
18+directory is always at the root of your pier directory.
19−</div>
20+</div> </div>
22## Quickstart
22## Quickstart
@@ -33,7 +33,8 @@ Mount the entire contents of your `sandbox` desk to Unix:
34 ~your-urbit:dojo> |mount /=sandbox=
34 ~your-urbit:dojo> |mount /=sandbox=
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
38 ~your-urbit:dojo> +ls /=sandbox=/web
39 ~your-urbit:dojo> +ls /=sandbox=/web
@@ -41,7 +42,8 @@ Let's see the contents of `/=sandbox=/web/md`:
42 ~your-urbit:dojo> +cat /=sandbox=/web/md
43 ~your-urbit:dojo> +cat /=sandbox=/web/md
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 |sync %sandbox ~some-ship %experiment
48 |sync %sandbox ~some-ship %experiment
@@ -49,21 +51,31 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your `%sandbox` desk:
50<h3 class="first child">Paths</h3>
52<h3 class="first child">Paths</h3>
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`.
58+Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.
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`.
59+The first three segments of an urbit path are `/plot/desk/case`, for
60+example `/~doznec/home/1`.
56#### Relative paths
62#### Relative paths
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
60#### Substitution
69#### Substitution
62−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
71+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and
63−and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
72+`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo`
64−`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
73+or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
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`.
68### Revision-control
80### Revision-control
@@ -99,7 +111,8 @@ Unmounts the Unix path `/generators`.
100Merges a `beak` into a `desk` using an optional merge `strategy`.
112Merges a `beak` into a `desk` using an optional merge `strategy`.
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`)
104**Examples:**
117**Examples:**
@@ -113,16 +126,21 @@ Merge the `%examples` desk from `~waxbex-ribmex`
114### `|sync desk plot [plot-desk]`
127### `|sync desk plot [plot-desk]`
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
118**Examples:**
135**Examples:**
120− |sync %home-local ~doznec %home
137+ |sync %home-local ~doznec %home |sync %home ~doznec
123### `|unsync desk plot [plot-desk]`
139### `|unsync desk plot [plot-desk]`
141+Unsubscribe from updates from remote `plot` on local `desk` with
125−Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
142+optional `plot-desk`. Arguments must match original `|sync` command
@@ -136,72 +154,81 @@ Example:
137 |label %home release
155 |label %home release
140### Merge strategies
157### Merge strategies
142`%init` - Used iff it's the first commit to a desk.
159`%init` - Used iff it's the first commit to a desk.
144`%this` - Keep what's in Bob's desk, but join the ancestry.
161`%this` - Keep what's in Bob's desk, but join the ancestry.
146−`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
163+`%that` - take what's in Alice's desk, but join the ancestry. This is
147−
164+the reverse of `%this`.
148−`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
166+`%fine` - "fast-forward" merge. This succeeds iff one head is in the
149−
167+ancestry of the other.
150−`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
169+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor
151−
170+to use as our merge base.
152−A `%meet` merge only succeeds if the changes from the merge base
172+A `%meet` merge only succeeds if the changes from the merge base to
153−to Alice's head (hereafter, "Alice's changes") are in different
173+Alice's head (hereafter, "Alice's changes") are in different files
154−files than Bob's changes. In this case, the parents are both
174+than Bob's changes. In this case, the parents are both Alice's and
155−Alice's and Bob's heads, and the data is the merge base plus
175+Bob's heads, and the data is the merge base plus Alice's changed files
156−Alice's changed files plus Bob's changed files.
176+plus Bob's changed files.
158−A `%mate` merge attempts to merge changes to the same file when
178+A `%mate` merge attempts to merge changes to the same file when both
159−both Alice and Bob change it. If the merge is clean, we use it;
179+Alice and Bob change it. If the merge is clean, we use it; otherwise,
160−otherwise, we fail. A merge between different types of changes --
180+we fail. A merge between different types of changes -- for example,
161−for example, deleting a file vs changing it -- is always a
181+deleting a file vs changing it -- is always a conflict. If we succeed,
162−conflict. If we succeed, the parents are both Alice's and Bob's
182+the parents are both Alice's and Bob's heads, and the data is the
163−heads, and the data is the merge base plus Alice's changed files
183+merge base plus Alice's changed files plus Bob's changed files plus
164−plus Bob's changed files plus the merged files.
184+the merged files.
166−A `%meld` merge will succeed even if there are conflicts. If
186+A `%meld` merge will succeed even if there are conflicts. If there are
167−there are conflicts in a file, then we use the merge base's
187+conflicts in a file, then we use the merge base's version of that
168−version of that file, and we produce a set of files with
188+file, and we produce a set of files with conflicts. The parents are
169−conflicts. The parents are both Alice's and Bob's heads, and the
189+both Alice's and Bob's heads, and the data is the merge base plus
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
190+Alice's changed files plus Bob's changed files plus the successfully
172−base's version of the conflicting files.
191+merged files plus the merge base's version of the conflicting files.
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.
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.
176### Manipulation
199### Manipulation
178<h3 class="first child"><code>|rm path</code></h3>
201<h3 class="first child"><code>|rm path</code></h3>
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
182### `|cp to from how`
206### `|cp to from how`
184−Copy the subtree `from` into the subtree `to`, committing it with
208+Copy the subtree `from` into the subtree `to`, committing it with the
185−the specified merge strategy `how`.
209+specified merge strategy `how`.
187#### `|mv to from how`
211#### `|mv to from how`
189−Move the subtree `from` into the subtree `to`, committing it with
213+Move the subtree `from` into the subtree `to`, committing it with the
190−the specified merge strategy `how`.
214+specified merge strategy `how`.
192−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
216+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
193−`|rm` doesn't happen unless the `|cp` succeeds.
217+doesn't happen unless the `|cp` succeeds.
195### Generators
219### Generators
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
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
201Produces the contents of the file at the given `path`.
227Produces the contents of the file at the given `path`.
203### `+ls path` / `+ll [path ...]`
229### `+ls path` / `+ll [path ...]`
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
207Produces a list of names at the `path`.
234Produces a list of names at the `path`.