git.iko.soy/urbit.org
on ca868bc help sign in
urbit.org/using/filesystem.md
454 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|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|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/md`:
65```
66~your-urbit:dojo> +cat /=sandbox=/web/md
67```
69Now let's navigate to that folder using `=dir`, which is like `cd` in Unix.
71```
72~your-urbit:dojo> =dir /=sandbox=/web/md
73```
75Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To
76change back to our home directory, we use `=dir` without any path.
78```
79~your-urbit:dojo/sandbox/web/md> =dir
80```
82Sync from your friend `~some-ship`'s `%experiment` desk to your
83`%sandbox` desk:
85```
86|sync %sandbox ~some-ship %experiment
87```
89If and when your sync is successful, you will receive a message:
91```
92activated sync from %experiment on ~some-ship to %sandbox
93```
95The ship that you sync from will get their own message indicating that you're
96both connected as peers:
98```
99; ~your-urbit is your neighbor.
100```
102---
104## Manual
106### Paths
108A path in Clay is a list of URL-safe text, restricted to the characters
109`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
110meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
111In other words, paths are expressed as `/foo/bar/baz`. File extensions are
112separated from file names with `/`, not `.`. Extensions are syntactically
113identical to subdirectories, except that they must terminate the path.
115Paths begin with a piece of data called a `beak`. A beak is formally a
116`(p=ship q=desk r=case)`; it has three components, and might look like
117`/~dozbud-namsep/home/11`.
119The first `beak` component is `ship`, which is, as you might guess, the name of
120an Urbit ship. The second component is `desk`, which is a workspace meant to
121contain other directories; the default desk is `%home`. The third component is
122`case`, which represents version information in various ways: date and time;
123a version sequence, which is a value incremented by one whenever a file on the
124given `desk` is modified; or an arbitrary plaintext label.
126You can find what your `beak` is at any given moment by
127typing `%` in the Dojo and looking at the first three results.
129We use `beak`s because, unlike the current internet, the Urbit network uses a
130global namespace. That means that a file named `example.hoon` in the `/gen`
131directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
132universal address to anyone else on the network:
133`~lodleb-ritrul/home/186/gen/example.hoon`. That, of
134course, doesn't mean that everyone on the network has privileges to access that
135path.
137The structure that combines a `beak` with further path information is called a
138`beam`.
140##### Relative paths
142The `%` command, which we gestured at in the above section, represents the
143**relative path**, which is the path where you are currently working. If your
144working directory is just your home desk, indicated by the
145prompt `~your-planet:dojo>`, then running the command below will print your
146working directory's `beam` information: your `beak`, and a `~` that represents
147the empty list since no path is present.
149```
150~your-urbit:dojo> %
151```
153`%`s can be stacked to indicate one level further up in the hierarchy for each
154additional `%`. Try the following command:
156```
157~your-planet:dojo> %%%
158```
160You'll probably notice that it only has your ship name and the empty list. The
161two additional `%`s abandoned the `case` and the `desk` information by moving
162up twice the hierarchy.
164There are no local relative paths. `/foo/bar` must be written as
165`%/foo/bar`.
167##### Substitution
169You don't need to write out the explicit path every time you want to reference
170somewhere outside of your working directory. You can substitute `=` for the
171segments of a path.
173Recall that a full address in the the Urbit namespace is a `beam`: the
174`/ship/desk/case/path`. If you've switched to another desk before, you're
175already familiar with substitution syntax:
177```
178~your-urbit:dojo> =dir /=sandbox=
179```
181The above command substitutes uses substitution to use your current `ship` and
182`case`; only the `desk` argument, which is located between the other two, is
183given something new. Without substitution, you would need to write:
185```
186~your-urbit:dojo> =dir /~your-urbit/home/85
187```
189Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
190paths. For example, if you are in the `/gen` directory, you can reference a file
191in the `/app` directory like below. (`+cat` displays the contents of a file).
193```
194~your-urbit:dojo/home/gen> +cat /===/app/curl/hoon
195```
197Note what was substituted out, and note that we don't need to separate `=` with
198`/`.
200If we changed our working directory to something called `/gen/gmail`, we could
201access a file called
203```
204~fasdul-balsev-lodleb-ritrul:dojo/home/gen/gmail> +cat /===/app/=/split/hoon
205```
207Because both paths share a directory named `/gmail` at the same position in the
208address hierarchy -- which, if you recall, is just a `list` -- the above command
209works!
211We can do the same thing between desks. If `%sandbox` has been merged with
212`%home`, the following command will produce the same results as the above
213command.
215```
216~your-urbit:dojo/home/gen/gmail> +cat /=sandbox=/app/=/split/hoon
217```
219Most commonly this is used to avoid having to know the current revision
220number in the `dojo`: `~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example.hoon`
222##### Changing directories
224Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
226For example, the syntax to navigate to `/home/gen/ask` is:
228```
229~your-urbit:dojo> =dir /=gen=/ask
230```
232This command will turn your prompt into something like this:
234```
235~your-urbit:dojo/gen/ask>
236```
238Using `=dir` without anything else uses the null path, which returns you to
239your home desk.
241```
242~your-urbit:dojo> =dir
243```
245To go up levels in the path hierarchy, recall the relative path expression
246`%`. Stacking them represents another level higher in the hierarchy than
247the current working directory for each `%` beyond the initial. The command below
248brings you one level up:
250```
251~your-urbit:dojo/gen> =dir %%
252```
254### Revision-control
256##### Mount
258Syntax: `|mount /clay/path [Unix-name]`
260Mount the `clay-path` at the Unix mount point `Unix-name`.
262**Examples:**
264```
265|mount %/web
266```
268Mounts `%/web` to `/web` inside your pier directory.
270```
271|mount %/gen generators
272```
274Mounts `%/gen` to `/generators` inside your pier directory.
276##### Unmount
278```
279|unmount [clay-path || Unix-name]
280```
282Unmount the path or name from Unix.
284**Examples:**
286```
287|unmount %/web
288```
290Unmounts the path `%/web` from whatever name it was mounted as.
292```
293|unmount %generators
294```
296Unmounts the Unix path `/generators`.
298```
299|merge desk beak[, =gem strategy]
300```
302Merges a `beak` into a `desk` using an optional merge `strategy`.
304A `beak` is a ship-desk-case triple, encoded as a
305path(`/~dozbud/home/2`)
307**Examples:**
309```
310|merge %home-work /=home=, =gem %fine
311```
313Merge `/=home=` into `%home-work` using merge strategy `%fine`.
315```
316|merge %examples ~wacbex-ribmex %examples
317```
319Merge the `%examples` desk from `~waxbex-ribmex`
321```
322|sync desk plot [plot-desk]
323```
325Subscribe to continuous updates from remote `plot` on local `desk`.
326`plot-desk` can specify the remote `desk` name. When omitted it is
327defaulted to being the same as `desk`. Non-comet urbits have
328`|sync %home ~parent %kids` automatically set up (where `~parent` is the
329planet that issued a moon, the star that issued a planet, or the galaxy
330that issued a star).
332**Examples:**
334```
335|sync %home-local ~dozbud %home
337|sync %home ~doznec
338```
340```
341|unsync desk plot [plot-desk]
342```
344Unsubscribe from updates from remote `plot` on local `desk` with
345optional `plot-desk`. Arguments must match original `|sync` command.
347Example:
349```
350|unsync %home-local ~dozbud %home
351```
353```
354|label desk name`
355```
357Label the current version of `desk` `name`.
359Example:
361```
362|label %home release
363```
365### Merge strategies
367`%init` - Used if it's the first commit to a desk. Also can be used to
368"reinitialize" a desk -- revision numbers keep going up, but the new
369revision isn't necessarily a descendent of the previously numbered
370version, allowing merges to be rerun.
372`%this` - Keep what's in Bob's desk, but join the ancestry.
374`%that` - take what's in Alice's desk, but join the ancestry. This is
375the reverse of `%this`. This is different from `%init` because the new
376commit has both sides in its ancestry.
378`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
379ancestry of the other.
381`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
382use as our merge base.
384A `%meet` merge only succeeds if the changes from the merge base to
385Alice's head (hereafter, "Alice's changes") are in different files than
386Bob's changes. In this case, the parents are both Alice's and Bob's
387heads, and the data is the merge base plus Alice's changed files plus
388Bob's changed files.
390A `%mate` merge attempts to merge changes to the same file when both
391Alice and Bob change it. If the merge is clean, we use it; otherwise, we
392fail. A merge between different types of changes -- for example,
393deleting a file vs changing it -- is always a conflict. If we succeed,
394the parents are both Alice's and Bob's heads, and the data is the merge
395base plus Alice's changed files plus Bob's changed files plus the merged
396files.
398A `%meld` merge will succeed even if there are conflicts. If there are
399conflicts in a file, then we use the merge base's version of that file,
400and we produce a set of files with conflicts. The parents are both
401Alice's and Bob's heads, and the data is the merge base plus Alice's
402changed files plus Bob's changed files plus the successfully merged
403files plus the merge base's version of the conflicting files.
405`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
406doesn't we use an `%init` merge. Otherwise, we progressively try
407`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
408merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
409the scratch desk with the `%meld` option to force the merge. Finally, we
410annotate any conflicts, if we know how.
412### Manipulation
414##### +cat
416Syntax: `+cat path [path ...]`
418Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
419contents. If that `path` is a file, the contents of the file is printed. If the
420`path` terminates in a directory, the list of names at that path is produced.
422##### +ls
424Syntax: `+ls path`
426Similar to Unix `ls`. `+ls` takes a single `path`.
428Produces a list of names at the `path`.
430```
431~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
432```
434##### |rm
436Syntax: `|rm path`
438Remove the data at `path`. `path` must be a path to actual node, not a
439'directory'
441##### |cp
443Syntax: `|cp to from`
445Copy the file at `from` into the path `to`.
447##### |mv
449Syntax: `|mv to from`
451Move the file at `from` into the path `to`.
453In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
454doesn't happen unless the `|cp` succeeds.