git.iko.soy/urbit.org
on 52df256 help sign in
urbit.org/using/filesystem.md
471 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`.
10The most common way to use Clay is to mount a Clay node in a Unix directory. The mounted directory is always at the root of your
11pier directory.
13## Quickstart
15This quick-start guide will walk you through some common commands. Follow along
16using your Dojo. When you get a `>=` message after entering a command, this means
17that the command was successful.
19When developing it's a good idea to use a separate desk. Create a `%sandbox`
20desk based on the `%home` desk:
22```
23~your-urbit:dojo> |merge %sandbox ~your-urbit %home
24```
26Running `our` produces your ship-name, meaning that you can run the following
27command instead of typing out the entire thing. Useful for comets, due to their
28very long names.
30```
31~your-urbit:dojo> |merge %sandbox our %home
32```
34Most of the time we want to use Clay from Unix. Mount the entire contents of
35your `sandbox` desk to Unix:
37```
38~your-urbit:dojo> |mount /=sandbox=
39```
41To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
42displays files in the current directory, and `+cat` displays the contents of
43a file.
45We can use `%` to mean "current directory." The result of the command below
46is just like using `ls` in a Unix terminal.
48```
49~your-urbit:dojo> +ls %
50```
52Notice how `+cat %` does the same thing. That's because everything in Clay,
53including directories, is a file.
55Let's explore the `/web` directory of the `%sandbox` desk.
57```
58~your-urbit:dojo> +ls /=sandbox=/web
59```
61Let's see the contents of `/=sandbox=/web/404/hoon`:
63```
64~your-urbit:dojo> +cat /=sandbox=/web/404/hoon
65```
67Now let's navigate to `/web` on `%sandbox` using `=dir`, which is like `cd` in Unix.
69```
70~your-urbit:dojo> =dir /=sandbox=/web
71```
73You'll notice that your prompt is now
74`~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web>`.
76```
77~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> +ls %
78```
80To change back to our home directory, we use `=dir` without any path.
82```
83~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> =dir
84```
86Sync from your friend `~some-ship`'s `%experiment` desk to your
87`%sandbox` desk:
89```
90~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
91```
93If and when your sync is successful, you will receive a message:
95```
96activated sync from %experiment on ~some-ship to %sandbox
97```
99The ship that you sync from will get their own message indicating that you're
100both connected as peers:
102```
103; ~your-urbit is your neighbor.
104```
106---
108## Manual
110### Paths
112A path in Clay is a list of URL-safe text, restricted to the characters
113`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
114meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
115In other words, paths are expressed as `/foo/bar/baz`. File extensions are
116separated from file names with `/`, not `.`. Extensions are syntactically
117identical to subdirectories, except that they must terminate the path.
119Paths begin with a piece of data called a `beak`. A beak is formally a
120`(p=ship q=desk r=case)`; it has three components, and might look like
121`/~dozbud-namsep/home/11`.
123The first `beak` component is `ship`, which is, as you might guess, the name of
124an Urbit ship. The second component is `desk`, which is a workspace meant to
125contain other directories; the default desk is `%home`. The third component is
126`case`, which represents version information in various ways: date and time;
127a version sequence, which is a value incremented by one whenever a file on the
128given `desk` is modified; or an arbitrary plaintext label.
130You can find what your `beak` is at any given moment by
131typing `%` in the Dojo and looking at the first three results.
133We use `beak`s because, unlike the current internet, the Urbit network uses a
134global namespace. That means that a file named `example.hoon` in the `/gen`
135directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
136universal address to anyone else on the network:
137`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
138course, doesn't mean that everyone on the network has privileges to access that
139path.
141The structure that combines a `beak` with further path information is called a
142`beam`.
144#### Relative paths
146The `%` command, which we gestured at in the above section, represents the
147**relative path**, which is the path where you are currently working. If your
148working directory is just your home desk, indicated by the
149prompt `~your-planet:dojo>`, then running the command below will print your
150working directory's `beam` information: your `beak`, and a `~` that represents
151the empty list since no path is present.
153```
154~your-urbit:dojo> %
155```
157`%`s can be stacked to indicate one level further up in the hierarchy for each
158additional `%`. Try the following command:
160```
161~your-planet:dojo> %%%
162```
164You'll probably notice that it only has your ship name and the empty list. The
165two additional `%`s abandoned the `case` and the `desk` information by moving
166up twice the hierarchy.
168There are no local relative paths. `/foo/bar` must be written as
169`%/foo/bar`.
171#### Substitution
173You don't need to write out the explicit path every time you want to reference
174somewhere outside of your working directory. You can substitute `=` for the
175segments of a path.
177Recall that a full address in the the Urbit namespace is a `beam`: the
178`/ship/desk/case/path`. If you've switched to another desk before, you're
179already familiar with substitution syntax:
181```
182~your-urbit:dojo> =dir /=sandbox=
183```
185The above command substitutes uses substitution to use your current `ship` and
186`case`; only the `desk` argument, which is located between the other two, is
187given something new. Without substitution, you would need to write:
189```
190~your-urbit:dojo> =dir /~your-urbit/home/85
191```
193Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
194paths. For example, if you are in the `/gen` directory, you can reference a file
195in the `/app` directory like below. (`+cat` displays the contents of a file).
197```
198~your-urbit:dojo> =dir %/gen
199~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
200```
202Note what was substituted out, and note that we don't need to separate `=` with
203`/`.
205If we changed our working directory to something called `/gen/gmail`, we could
206access a file called
208```
209~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
210~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
211```
213Because both paths share a directory named `/gmail` at the same position in the
214address hierarchy -- which, if you recall, is just a `list` -- the above command
215works!
217We can do the same thing between desks. If `%sandbox` has been merged with
218`%home`, the following command will produce the same results as the above
219command.
221```
222~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
223```
225Most commonly this is used to avoid having to know the current revision
226number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
228#### Changing directories
230Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
232For example, the syntax to navigate to `/home/gen/ask` is:
234```
235~your-urbit:dojo> =dir /=home=/gen/ask
236```
238This command will turn your prompt into something like this:
240```
241~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
242```
244Using `=dir` without anything else uses the null path, which returns you to
245your home desk.
247```
248~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
249```
251Your dojo prompt will turn back into `~your-urbit:dojo>`.
253To go up levels in the path hierarchy, recall the relative path expression
254`%`. Stacking them represents another level higher in the hierarchy than
255the current working directory for each `%` beyond the initial. The command below
256brings you one level up:
258```
259~your-urbit:dojo> =dir %/gen
260~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
261```
263### Revision-control
265#### Mount
267Syntax: `|mount /clay/path [Unix-name]`
269Mount the `clay-path` at the Unix mount point `Unix-name`.
271**Examples:**
273```
274|mount %/web
275```
277Mounts `%/web` to `/web` inside your pier directory.
279```
280|mount %/gen generators
281```
283Mounts `%/gen` to `/generators` inside your pier directory.
285#### Unmount
287```
288|unmount [clay-path || Unix-name]
289```
291Unmount the path or name from Unix.
293**Examples:**
295```
296|unmount %/web
297```
299Unmounts the path `%/web` from whatever name it was mounted as.
301```
302|unmount %generators
303```
305Unmounts the Unix path `/generators`.
307#### Merge
309```
310|merge desk beak[, =gem strategy]
311```
313Merges a `beak` into a `desk` using an optional merge `strategy`.
315A `beak` is a ship-desk-case triple, encoded as a
316path(`/~dozbud/home/2`)
318**Examples:**
320```
321|merge %home-work /=home=, =gem %fine
322```
324Merge `/=home=` into `%home-work` using merge strategy `%fine`.
326```
327|merge %examples ~wacbex-ribmex %examples
328```
330Merge the `%examples` desk from `~waxbex-ribmex`
332#### Sync
334```
335|sync desk plot [plot-desk]
336```
338Subscribe to continuous updates from remote `plot` on local `desk`.
339`plot-desk` can specify the remote `desk` name. When omitted it is
340defaulted to being the same as `desk`. Non-comet urbits have
341`|sync %home ~parent %kids` automatically set up (where `~parent` is the
342planet that issued a moon, the star that issued a planet, or the galaxy
343that issued a star).
345**Examples:**
347```
348|sync %home-local ~dozbud %home
350|sync %home ~doznec
351```
353#### Unsync
355```
356|unsync desk plot [plot-desk]
357```
359Unsubscribe from updates from remote `plot` on local `desk` with
360optional `plot-desk`. Arguments must match original `|sync` command.
362Example:
364```
365|unsync %home-local ~dozbud %home
366```
368#### Label
370```
371|label desk name`
372```
374Label the current version of `desk` `name`.
376Example:
378```
379|label %home release
380```
382### Merge strategies
384`%init` - Used if it's the first commit to a desk. Also can be used to
385"reinitialize" a desk -- revision numbers keep going up, but the new
386revision isn't necessarily a descendent of the previously numbered
387version, allowing merges to be rerun.
389`%this` - Keep what's in Bob's desk, but join the ancestry.
391`%that` - take what's in Alice's desk, but join the ancestry. This is
392the reverse of `%this`. This is different from `%init` because the new
393commit has both sides in its ancestry.
395`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
396ancestry of the other.
398`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
399use as our merge base.
401A `%meet` merge only succeeds if the changes from the merge base to
402Alice's head (hereafter, "Alice's changes") are in different files than
403Bob's changes. In this case, the parents are both Alice's and Bob's
404heads, and the data is the merge base plus Alice's changed files plus
405Bob's changed files.
407A `%mate` merge attempts to merge changes to the same file when both
408Alice and Bob change it. If the merge is clean, we use it; otherwise, we
409fail. A merge between different types of changes -- for example,
410deleting a file vs changing it -- is always a conflict. If we succeed,
411the parents are both Alice's and Bob's heads, and the data is the merge
412base plus Alice's changed files plus Bob's changed files plus the merged
413files.
415A `%meld` merge will succeed even if there are conflicts. If there are
416conflicts in a file, then we use the merge base's version of that file,
417and we produce a set of files with conflicts. The parents are both
418Alice's and Bob's heads, and the data is the merge base plus Alice's
419changed files plus Bob's changed files plus the successfully merged
420files plus the merge base's version of the conflicting files.
422`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
423doesn't we use an `%init` merge. Otherwise, we progressively try
424`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
425merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
426the scratch desk with the `%meld` option to force the merge. Finally, we
427annotate any conflicts, if we know how.
429### Manipulation
431#### +cat
433Syntax: `+cat path [path ...]`
435Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
436contents. If that `path` is a file, the contents of the file is printed. If the
437`path` terminates in a directory, the list of names at that path is produced.
439#### +ls
441Syntax: `+ls path`
443Similar to Unix `ls`. `+ls` takes a single `path`.
445Produces a list of names at the `path`.
447```
448~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
449```
451#### |rm
453Syntax: `|rm path`
455Remove the data at `path`. `path` must be a path to actual node, not a
456'directory'
458#### |cp
460Syntax: `|cp to from`
462Copy the file at `from` into the path `to`.
464#### |mv
466Syntax: `|mv to from`
468Move the file at `from` into the path `to`.
470In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
471doesn't happen unless the `|cp` succeeds.