git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/using/filesystem.udon
461 lines 13 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,
13referentially transparent namespace. An easy way to think about it is like typed
14`git` with continuous sync.
16The most common way to use Clay is to mount a Clay node in a Unix directory. The
17Urbit process will watch this directory and automatically record edits as
18changes, Dropbox style. The mounted directory is always at the root of your
19pier directory.
22## Quickstart
24This quick-start guide will walk you through some common commands. Follow along
25using your Dojo. When you get a `>=` message after entering a command, the means
26that the command was successful.
28When developing it's a good idea to use a separate desk. Create a `%sandbox`
29desk based on the `%home` desk:
31```
32|merge %sandbox ~your-urbit %home
33```
35Running `our` produces your ship-name, meaning that you can run the following
36command instead of typing out the entire thing. Useful for comets, due to their
37very long names.
39```
40|merge %sandbox our %home
41```
43Most of the time we want to use Clay from Unix. Mount the entire contents of
44your `sandbox` desk to Unix:
46```
47~your-urbit:dojo> |mount /=sandbox=
48```
50To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
51displays files in the current directory, and `+cat` displays the contents of
52a file.
54We can use `%` to mean "current directory." The result of the command below
55is just like using `ls` in a Unix terminal.
57```
58~your-urbit:dojo> +ls %
59```
61Notice how `+cat %` does the same thing. That's because everything in Clay,
62including directories, is a file.
64Let's explore the `/web` directory of the `%sandbox` desk.
66```
67~your-urbit:dojo> +ls /=sandbox=/web
68```
70Let's see the contents of `/=sandbox=/web/md`:
72```
73~your-urbit:dojo> +cat /=sandbox=/web/md
74```
76Now let's navigate to that folder using `=dir`, which is a like `cd` in Unix.
78```
79~your-urbit:dojo> =dir /=sandbox=/web/md
80```
82Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To
83change back to our home directory, we use `=dir` without any path.
85```
86~your-urbit:dojo/sandbox/web/md> =dir
87```
89Sync from your friend `~some-ship`'s `%experiment` desk to your
90`%sandbox` desk:
92```
93|sync %sandbox ~some-ship %experiment
94```
96If and when your sync is successful, you will receive a message:
98```
99activated sync from %experiment on ~some-ship to %sandbox
100```
102The ship that you sync from will get their own message indicating that you're
103both connected as peers:
105```
106; ~your-urbit is your neighbor.
107```
109---
111## Manual
113### Paths
115A path in Clay is a list of URL-safe text, restricted to the characters
116`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
117meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
118In other words, paths are expressed as `/foo/bar/baz`. File extensions are
119separated from file names with `/`, not `.`. Extensions are syntactically
120identical to subdirectories, except that they must terminate the path.
122Paths begin with a piece of data called a `beak`. A beak is formally a
123`(p=ship q=desk r=case)`; it has three components, and might look like
124`/~dozbud-namsep/home/11`.
126The first `beak` component is `ship`, which is, as you might guess, the name of
127an Urbit ship. The second component is `desk`, which is a workspace meant to
128contain other directories; the default desk is `%home`. The third component is
129`case`, which represents version information in various ways: date and time;
130a version sequence, which is a value incremented by one whenever a file on the
131given `desk` is modified; or an arbitrary plaintext label.
133You can find what your `beak` is at any given moment by
134typing `%` in the Dojo and looking at the first three results.
136We use `beak`s because, unlike the current internet, the Urbit network uses a
137global namespace. That means that a file named `example.hoon` in the `/gen`
138directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
139universal address to anyone else on the network:
140`~lodleb-ritrul/home/186/gen/example.hoon`. That, of
141course, doesn't mean that everyone on the network has privileges to access that
142path.
144The structure that combines a `beak` with further path information is called a
145`beam`.
147##### Relative paths
149The `%` command, which we gestured at in the above section, represents the
150*relative path*, which is the path where you are currently working. If your
151working directory is just your home desk, indicated by the
152prompt `~your-planet:dojo>`, then running the command below will print your
153working directory's `beam` information: your `beak`, and a `~` that represents
154the empty list since no path is present.
156```
157~your-urbit:dojo> %
158```
160`%`s can be stacked to indicate one level further up in the hierarchy for each
161additional `%`. Try the following command:
163```
164~your-planet:dojo> %%%
165```
167You'll probably notice that it only has your ship name and the empty list. The
168two additional `%`s abandoned the `case` and the `desk` information by moving
169up twice the hierarchy.
171There are no local relative paths. `/foo/bar` must be written as
172`%/foo/bar`.
174##### Substitution
176You don't need to write out the explicit path every time you want to reference
177somewhere outside of your working directory. You can substitute `=` for the
178segments of a path.
180Recall that a full address in the the Urbit namespace is a `beam`: the
181`/ship/desk/case/path`. If you've switched to another desk before, you're
182already familiar with substitution syntax:
184```
185~your-urbit:dojo> =dir /=sandbox=
186```
188The above command substitutes uses substitution to use your current `ship` and
189`case`; only the `desk` argument, which is located between the other two, is
190given something new. Without substitution, you would need to write:
192```
193~your-urbit:dojo> =dir /~your-urbit/home/85
194```
196Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
197paths. For example, if you are in the `/gen` directory, you can reference a file
198in the `/app` directory like below. (`+cat` displays the contents of a file).
200```
201~your-urbit:dojo/home/gen> +cat /===/app/curl/hoon
202```
204Note what was substituted out, and note that we don't need to separate `=` with
205`/`.
207If we changed our working directory to something called `/gen/gmail`, we could
208access a file called
210```
211~fasdul-balsev-lodleb-ritrul:dojo/home/gen/gmail> +cat /===/app/=/split/hoon
212```
214Because both paths share a directory named `/gmail` at the same position in the
215address hierarchy -- which, if you recall, is just a `list` -- the above command
216works!
218We can do the same thing between desks. If `%sandbox` has been merged with
219`%home`, the following command will produce the same results as the above
220command.
222```
223~your-urbit:dojo/home/gen/gmail> +cat /=sandbox=/app/=/split/hoon
224```
226Most commonly this is used to avoid having to know the current revision
227number in the `dojo`: `~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example.hoon`
229##### Changing directories
231Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
233For example, the syntax to navigate to `/home/gen/ask` is:
235```
236~your-urbit:dojo> =dir /=gen=/ask
237```
239This command will turn your prompt into something like this:
241```
242~your-urbit:dojo/gen/ask>
243```
245Using `=dir` without anything else uses the null path, which returns you to
246your home desk.
248```
249~your-urbit:dojo> =dir
250```
252To go up levels in the path hierarchy, recall the relative path expression
253`%`. Stacking them represents another level higher in the hierarchy than
254the current working directory for each `%` beyond the initial. The command below
255brings you one level up:
257```
258~your-urbit:dojo/gen> =dir %%
259```
261### Revision-control
263##### Mount
265Syntax: `|mount /clay/path [Unix-name]`
267Mount the `clay-path` at the Unix mount point `Unix-name`.
269*Examples:*
271```
272|mount %/web
273```
275Mounts `%/web` to `/web` inside your pier directory.
277```
278|mount %/gen generators
279```
281Mounts `%/gen` to `/generators` inside your pier directory.
283##### Unmount
285```
286|unmount [clay-path || Unix-name]
287```
289Unmount the path or name from Unix.
291*Examples:*
293```
294|unmount %/web
295```
297Unmounts the path `%/web` from whatever name it was mounted as.
299```
300|unmount %generators
301```
303Unmounts the Unix path `/generators`.
305```
306|merge desk beak[, =gem strategy]
307```
309Merges a `beak` into a `desk` using an optional merge `strategy`.
311A `beak` is a ship-desk-case triple, encoded as a
312path(`/~dozbud/home/2`)
314*Examples:*
316```
317|merge %home-work /=home=, =gem %fine
318```
320Merge `/=home=` into `%home-work` using merge strategy `%fine`.
322```
323|merge %examples ~wacbex-ribmex %examples
324```
326Merge the `%examples` desk from `~waxbex-ribmex`
328```
329|sync desk plot [plot-desk]
330```
332Subscribe to continuous updates from remote `plot` on local `desk`.
333`plot-desk` can specify the remote `desk` name. When omitted it is
334defaulted to being the same as `desk`. Non-comet urbits have
335`|sync %home ~parent %kids` automatically set up (where `~parent` is the
336planet that issued a moon, the star that issued a planet, or the galaxy
337that issued a star).
339*Examples:*
341```
342|sync %home-local ~dozbud %home
344|sync %home ~doznec
345```
347```
348|unsync desk plot [plot-desk]
349```
351Unsubscribe from updates from remote `plot` on local `desk` with
352optional `plot-desk`. Arguments must match original `|sync` command.
354Example:
356```
357|unsync %home-local ~dozbud %home
358```
360```
361|label desk name`
362```
364Label the current version of `desk` `name`.
366Example:
368```
369|label %home release
370```
372### Merge strategies
374`%init` - Used if it's the first commit to a desk. Also can be used to
375"reinitialize" a desk -- revision numbers keep going up, but the new
376revision isn't necessarily a descendent of the previously numbered
377version, allowing merges to be rerun.
379`%this` - Keep what's in Bob's desk, but join the ancestry.
381`%that` - take what's in Alice's desk, but join the ancestry. This is
382the reverse of `%this`. This is different from `%init` because the new
383commit has both sides in its ancestry.
385`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
386ancestry of the other.
388`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
389use as our merge base.
391A `%meet` merge only succeeds if the changes from the merge base to
392Alice's head (hereafter, "Alice's changes") are in different files than
393Bob's changes. In this case, the parents are both Alice's and Bob's
394heads, and the data is the merge base plus Alice's changed files plus
395Bob's changed files.
397A `%mate` merge attempts to merge changes to the same file when both
398Alice and Bob change it. If the merge is clean, we use it; otherwise, we
399fail. A merge between different types of changes -- for example,
400deleting a file vs changing it -- is always a conflict. If we succeed,
401the parents are both Alice's and Bob's heads, and the data is the merge
402base plus Alice's changed files plus Bob's changed files plus the merged
403files.
405A `%meld` merge will succeed even if there are conflicts. If there are
406conflicts in a file, then we use the merge base's version of that file,
407and we produce a set of files with conflicts. The parents are both
408Alice's and Bob's heads, and the data is the merge base plus Alice's
409changed files plus Bob's changed files plus the successfully merged
410files plus the merge base's version of the conflicting files.
412`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
413doesn't we use an `%init` merge. Otherwise, we progressively try
414`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
415merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
416the scratch desk with the `%meld` option to force the merge. Finally, we
417annotate any conflicts, if we know how.
419### Manipulation
421##### +cat
423Syntax: `+cat path [path ...]`
425Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
426contents. If that `path` is a file, the contents of the file is printed. If the
427`path` terminates in a directory, the list of names at that path is produced.
429##### +ls
431Syntax: `+ls path`
433Similar to Unix `ls`. `+ls` takes a single `path`.
435Produces a list of names at the `path`.
437```
438~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
439```
441##### |rm
443Syntax: `|rm path`
445Remove the data at `path`. `path` must be a path to actual node, not a
446'directory'
448##### |cp
450Syntax: `|cp to from`
452Copy the file at `from` into the path `to`.
454##### |mv
456Syntax: `|mv to from`
458Move the file at `from` into the path `to`.
460In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
461doesn't happen unless the `|cp` succeeds.