git.iko.soy/urbit.org
on d5508cb help sign in
urbit.org/using/filesystem.md
473 lines 13 kB history raw
1+++
2title = "Filesystem"
3weight = 5
4template = "doc.html"
5+++
6Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
7referentially transparent namespace. An easy way to think about it is like typed
8`git` with continuous sync.
10The most common way to use Clay is to mount a Clay node in a Unix directory. The
11Urbit process will watch this directory and automatically record edits as
12changes, Dropbox style. The mounted directory is always at the root of your
13pier directory.
15## Quickstart
17This quick-start guide will walk you through some common commands. Follow along
18using your Dojo. When you get a `>=` message after entering a command, this means
19that the command was successful.
21When developing it's a good idea to use a separate desk. Create a `%sandbox`
22desk based on the `%home` desk:
24```
25~your-urbit:dojo> |merge %sandbox ~your-urbit %home
26```
28Running `our` produces your ship-name, meaning that you can run the following
29command instead of typing out the entire thing. Useful for comets, due to their
30very long names.
32```
33~your-urbit:dojo> |merge %sandbox our %home
34```
36Most of the time we want to use Clay from Unix. Mount the entire contents of
37your `sandbox` desk to Unix:
39```
40~your-urbit:dojo> |mount /=sandbox=
41```
43To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
44displays files in the current directory, and `+cat` displays the contents of
45a file.
47We can use `%` to mean "current directory." The result of the command below
48is just like using `ls` in a Unix terminal.
50```
51~your-urbit:dojo> +ls %
52```
54Notice how `+cat %` does the same thing. That's because everything in Clay,
55including directories, is a file.
57Let's explore the `/web` directory of the `%sandbox` desk.
59```
60~your-urbit:dojo> +ls /=sandbox=/web
61```
63Let's see the contents of `/=sandbox=/web/404/hoon`:
65```
66~your-urbit:dojo> +cat /=sandbox=/web/404/hoon
67```
69Now let's navigate to `/web` on `%sandbox` using `=dir`, which is like `cd` in Unix.
71```
72~your-urbit:dojo> =dir /=sandbox=/web
73```
75You'll notice that your prompt is now
76`~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web>`.
78```
79~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> +ls %
80```
82To change back to our home directory, we use `=dir` without any path.
84```
85~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> =dir
86```
88Sync from your friend `~some-ship`'s `%experiment` desk to your
89`%sandbox` desk:
91```
92~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
93```
95If and when your sync is successful, you will receive a message:
97```
98activated sync from %experiment on ~some-ship to %sandbox
99```
101The ship that you sync from will get their own message indicating that you're
102both connected as peers:
104```
105; ~your-urbit is your neighbor.
106```
108---
110## Manual
112### Paths
114A path in Clay is a list of URL-safe text, restricted to the characters
115`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
116meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
117In other words, paths are expressed as `/foo/bar/baz`. File extensions are
118separated from file names with `/`, not `.`. Extensions are syntactically
119identical to subdirectories, except that they must terminate the path.
121Paths begin with a piece of data called a `beak`. A beak is formally a
122`(p=ship q=desk r=case)`; it has three components, and might look like
123`/~dozbud-namsep/home/11`.
125The first `beak` component is `ship`, which is, as you might guess, the name of
126an Urbit ship. The second component is `desk`, which is a workspace meant to
127contain other directories; the default desk is `%home`. The third component is
128`case`, which represents version information in various ways: date and time;
129a version sequence, which is a value incremented by one whenever a file on the
130given `desk` is modified; or an arbitrary plaintext label.
132You can find what your `beak` is at any given moment by
133typing `%` in the Dojo and looking at the first three results.
135We use `beak`s because, unlike the current internet, the Urbit network uses a
136global namespace. That means that a file named `example.hoon` in the `/gen`
137directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
138universal address to anyone else on the network:
139`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
140course, doesn't mean that everyone on the network has privileges to access that
141path.
143The structure that combines a `beak` with further path information is called a
144`beam`.
146#### Relative paths
148The `%` command, which we gestured at in the above section, represents the
149**relative path**, which is the path where you are currently working. If your
150working directory is just your home desk, indicated by the
151prompt `~your-planet:dojo>`, then running the command below will print your
152working directory's `beam` information: your `beak`, and a `~` that represents
153the empty list since no path is present.
155```
156~your-urbit:dojo> %
157```
159`%`s can be stacked to indicate one level further up in the hierarchy for each
160additional `%`. Try the following command:
162```
163~your-planet:dojo> %%%
164```
166You'll probably notice that it only has your ship name and the empty list. The
167two additional `%`s abandoned the `case` and the `desk` information by moving
168up twice the hierarchy.
170There are no local relative paths. `/foo/bar` must be written as
171`%/foo/bar`.
173#### Substitution
175You don't need to write out the explicit path every time you want to reference
176somewhere outside of your working directory. You can substitute `=` for the
177segments of a path.
179Recall that a full address in the the Urbit namespace is a `beam`: the
180`/ship/desk/case/path`. If you've switched to another desk before, you're
181already familiar with substitution syntax:
183```
184~your-urbit:dojo> =dir /=sandbox=
185```
187The above command substitutes uses substitution to use your current `ship` and
188`case`; only the `desk` argument, which is located between the other two, is
189given something new. Without substitution, you would need to write:
191```
192~your-urbit:dojo> =dir /~your-urbit/home/85
193```
195Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
196paths. For example, if you are in the `/gen` directory, you can reference a file
197in the `/app` directory like below. (`+cat` displays the contents of a file).
199```
200~your-urbit:dojo> =dir %/gen
201~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/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~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
212~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
213```
215Because both paths share a directory named `/gmail` at the same position in the
216address hierarchy -- which, if you recall, is just a `list` -- the above command
217works!
219We can do the same thing between desks. If `%sandbox` has been merged with
220`%home`, the following command will produce the same results as the above
221command.
223```
224~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
225```
227Most commonly this is used to avoid having to know the current revision
228number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
230#### Changing directories
232Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
234For example, the syntax to navigate to `/home/gen/ask` is:
236```
237~your-urbit:dojo> =dir /=home=/gen/ask
238```
240This command will turn your prompt into something like this:
242```
243~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
244```
246Using `=dir` without anything else uses the null path, which returns you to
247your home desk.
249```
250~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
251```
253Your dojo prompt will turn back into `~your-urbit:dojo>`.
255To go up levels in the path hierarchy, recall the relative path expression
256`%`. Stacking them represents another level higher in the hierarchy than
257the current working directory for each `%` beyond the initial. The command below
258brings you one level up:
260```
261~your-urbit:dojo> =dir %/gen
262~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
263```
265### Revision-control
267#### Mount
269Syntax: `|mount /clay/path [Unix-name]`
271Mount the `clay-path` at the Unix mount point `Unix-name`.
273**Examples:**
275```
276|mount %/web
277```
279Mounts `%/web` to `/web` inside your pier directory.
281```
282|mount %/gen generators
283```
285Mounts `%/gen` to `/generators` inside your pier directory.
287#### Unmount
289```
290|unmount [clay-path || Unix-name]
291```
293Unmount the path or name from Unix.
295**Examples:**
297```
298|unmount %/web
299```
301Unmounts the path `%/web` from whatever name it was mounted as.
303```
304|unmount %generators
305```
307Unmounts the Unix path `/generators`.
309#### Merge
311```
312|merge desk beak[, =gem strategy]
313```
315Merges a `beak` into a `desk` using an optional merge `strategy`.
317A `beak` is a ship-desk-case triple, encoded as a
318path(`/~dozbud/home/2`)
320**Examples:**
322```
323|merge %home-work /=home=, =gem %fine
324```
326Merge `/=home=` into `%home-work` using merge strategy `%fine`.
328```
329|merge %examples ~wacbex-ribmex %examples
330```
332Merge the `%examples` desk from `~waxbex-ribmex`
334#### Sync
336```
337|sync desk plot [plot-desk]
338```
340Subscribe to continuous updates from remote `plot` on local `desk`.
341`plot-desk` can specify the remote `desk` name. When omitted it is
342defaulted to being the same as `desk`. Non-comet urbits have
343`|sync %home ~parent %kids` automatically set up (where `~parent` is the
344planet that issued a moon, the star that issued a planet, or the galaxy
345that issued a star).
347**Examples:**
349```
350|sync %home-local ~dozbud %home
352|sync %home ~doznec
353```
355#### Unsync
357```
358|unsync desk plot [plot-desk]
359```
361Unsubscribe from updates from remote `plot` on local `desk` with
362optional `plot-desk`. Arguments must match original `|sync` command.
364Example:
366```
367|unsync %home-local ~dozbud %home
368```
370#### Label
372```
373|label desk name`
374```
376Label the current version of `desk` `name`.
378Example:
380```
381|label %home release
382```
384### Merge strategies
386`%init` - Used if it's the first commit to a desk. Also can be used to
387"reinitialize" a desk -- revision numbers keep going up, but the new
388revision isn't necessarily a descendent of the previously numbered
389version, allowing merges to be rerun.
391`%this` - Keep what's in Bob's desk, but join the ancestry.
393`%that` - take what's in Alice's desk, but join the ancestry. This is
394the reverse of `%this`. This is different from `%init` because the new
395commit has both sides in its ancestry.
397`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
398ancestry of the other.
400`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
401use as our merge base.
403A `%meet` merge only succeeds if the changes from the merge base to
404Alice's head (hereafter, "Alice's changes") are in different files than
405Bob's changes. In this case, the parents are both Alice's and Bob's
406heads, and the data is the merge base plus Alice's changed files plus
407Bob's changed files.
409A `%mate` merge attempts to merge changes to the same file when both
410Alice and Bob change it. If the merge is clean, we use it; otherwise, we
411fail. A merge between different types of changes -- for example,
412deleting a file vs changing it -- is always a conflict. If we succeed,
413the parents are both Alice's and Bob's heads, and the data is the merge
414base plus Alice's changed files plus Bob's changed files plus the merged
415files.
417A `%meld` merge will succeed even if there are conflicts. If there are
418conflicts in a file, then we use the merge base's version of that file,
419and we produce a set of files with conflicts. The parents are both
420Alice's and Bob's heads, and the data is the merge base plus Alice's
421changed files plus Bob's changed files plus the successfully merged
422files plus the merge base's version of the conflicting files.
424`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
425doesn't we use an `%init` merge. Otherwise, we progressively try
426`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
427merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
428the scratch desk with the `%meld` option to force the merge. Finally, we
429annotate any conflicts, if we know how.
431### Manipulation
433#### +cat
435Syntax: `+cat path [path ...]`
437Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
438contents. If that `path` is a file, the contents of the file is printed. If the
439`path` terminates in a directory, the list of names at that path is produced.
441#### +ls
443Syntax: `+ls path`
445Similar to Unix `ls`. `+ls` takes a single `path`.
447Produces a list of names at the `path`.
449```
450~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
451```
453#### |rm
455Syntax: `|rm path`
457Remove the data at `path`. `path` must be a path to actual node, not a
458'directory'
460#### |cp
462Syntax: `|cp to from`
464Copy the file at `from` into the path `to`.
466#### |mv
468Syntax: `|mv to from`
470Move the file at `from` into the path `to`.
472In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
473doesn't happen unless the `|cp` succeeds.