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
15a Unix directory. The Urbit process will watch this directory
16and automatically record edits as changes, Dropbox style. The
17mounted directory is always at the root of your pier directory.
24When developing it's a good idea to use a separate desk.
26Create a `%sandbox` desk based on the `%home` desk:
28 |merge %sandbox ~your-urbit %home
30Most of the time we want to use `%clay` from Unix.
32Mount the entire contents of your `sandbox` desk to Unix:
34 ~your-urbit:dojo> |mount /=sandbox=
36To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
38 ~your-urbit:dojo> +ls /=sandbox=/web
40Let's see the contents of `/=sandbox=/web/md`:
42 ~your-urbit:dojo> +cat /=sandbox=/web/md
44Sync with a remote desk on the network:
46 |sync %sandbox ~wactex-ribmex %examples
50<h3 class="first child">Paths</h3>
52A 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`.
54Paths 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`.
58Relative 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`.
62If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
63and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
64`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
66Most 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`.
70<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
72Mount the `clay-path` at the unix mount point `unix-name`.
78Mounts `%/web` to `/web` inside your pier directory.
80 |mount %/gen generators
82Mounts `%/gen` to `/generators` inside your pier directory.
84### `|unmount [clay-path || unix-name]`
86Unmount the path or name from Unix.
92Unmounts the path `%/web` from whatever name it was mounted as.
96Unmounts the Unix path `/generators`.
98### `|merge desk beak [strategy]`
100Merges a `beak` into a `desk` using an optional merge `strategy`.
102A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec %home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
106 |merge %home-work /=home= %fine
108Merge `/=home=` into `%home-work` using merge strategy `%fine`.
110 |merge %examples [~wacbex-ribmex %examples]
112Merge the `%examples` desk from `~waxbex-ribmex`
114### `|sync desk plot [plot-desk]`
116Subscribe 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).
120 |sync %home-local ~doznec %home
123### `|unsync desk plot [plot-desk]`
125Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
129 |unsync %home-local ~doznec %home
131### `|label desk name`
133Label the current version of `desk` `name`.
142`%init` - Used iff it's the first commit to a desk.
144`%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`.
148`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
150`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
152A `%meet` merge only succeeds if the changes from the merge base
153to Alice's head (hereafter, "Alice's changes") are in different
154files than Bob's changes. In this case, the parents are both
155Alice's and Bob's heads, and the data is the merge base plus
156Alice's changed files plus Bob's changed files.
158A `%mate` merge attempts to merge changes to the same file when
159both Alice and Bob change it. If the merge is clean, we use it;
160otherwise, we fail. A merge between different types of changes --
161for example, deleting a file vs changing it -- is always a
162conflict. If we succeed, the parents are both Alice's and Bob's
163heads, and the data is the merge base plus Alice's changed files
164plus Bob's changed files plus the merged files.
166A `%meld` merge will succeed even if there are conflicts. If
167there are conflicts in a file, then we use the merge base's
168version of that file, and we produce a set of files with
169conflicts. The parents are both Alice's and Bob's heads, and the
170data is the merge base plus Alice's changed files plus Bob's
171changed files plus the successfully merged files plus the merge
172base'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.
178<h3 class="first child"><code>|rm path</code></h3>
180Remove the data at `path`. `path` must be a path to actual node, not a 'directory'
184Copy the subtree `from` into the subtree `to`, committing it with
185the specified merge strategy `how`.
187#### `|mv to from how`
189Move the subtree `from` into the subtree `to`, committing it with
190the specified merge strategy `how`.
192In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
193`|rm` doesn't happen unless the `|cp` succeeds.
197<h3 class="first child"><code>+cat path</code> / <code>+cal [path ...]</code></h3>
199Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of paths.
201Produces the contents of the file at the given `path`.
203### `+ls path` / `+ll [path ...]`
205Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of paths.
207Produces a list of names at the `path`.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list