a85ede5 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

simplify manual, remove wrong info

a85ede5drbeefsupreme6 years ago

content/using/os/filesystem.md+105−103

@@ -10,132 +10,139 @@ referentially transparent namespace. An easy way to think about it is like typed

11The 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 pier directory.

13+For more information on Clay, see the [Overview](@/docs/arvo/clay/clay.md), and

14+additional usage information at [Using Clay](@/docs/arvo/clay/using.md).

15+

13### Quickstart

16### Quickstart

15This quick-start guide will walk you through some common commands. Follow along

18This 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

19using your Dojo. When you get a `>=` message after entering a command, this means

17that the command was successful.

20that the command was successful.

22+A `desk` is something like an independently revision-controlled branch of your

23+urbit's file-system. Your urbit's system files live in the `%home` `desk`.

24+

19It's important to note that whenever you want to sync changes from your Unix

25It's important to note that whenever you want to sync changes from your Unix

20directory to your ship, you must use the `|commit %desk` command, where `%desk`

26directory to your ship, you must use the `|commit %desk` command, where `%desk`

21−is the desk that you'd like to sync to.

27+is the `desk` that you'd like to sync to.

23−When developing it's a good idea to use a separate desk. Create a `%sandbox`

29+When developing it's a good idea to use a separate `desk`. Create a `%sandbox`

24−desk based on the `%home` desk:

30+`desk` based on the `%home` `desk`:

26```

32```

27−~your-urbit:dojo> |merge %sandbox ~your-urbit %home

33+~zod:dojo> |merge %sandbox ~zod %home

28```

34```

30Running `our` produces your ship-name, meaning that you can run the following

36Running `our` produces your ship-name, meaning that you can run the following

31−command instead of typing out the entire thing. Useful for comets due to their

37+command instead of typing out the entire thing. This is especially useful for

32−very long names.

38+comets due to their very long names.

34```

40```

35−~your-urbit:dojo> |merge %sandbox our %home

41+~zod:dojo> |merge %sandbox our %home

36```

42```

38Most of the time we want to use Clay from Unix. Mount the entire contents of

44Most of the time we want to use Clay from Unix. Mount the entire contents of

39your `sandbox` desk to Unix:

45your `sandbox` desk to Unix:

41```

47```

42−~your-urbit:dojo> |mount /=sandbox=

48+~zod:dojo> |mount /=sandbox=

43```

49```

45To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`

51To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`

46displays files in the current directory, and `+cat` displays the contents of

52displays files in the current directory, and `+cat` displays the contents of

47a file.

53a file.

49−We can use `%` to mean "current directory." The result of the command below

55+We use `%` to mean "current directory." The result of the command below

50is just like using `ls` in a Unix terminal.

56is just like using `ls` in a Unix terminal.

52```

58```

53−~your-urbit:dojo> +ls %

59+~zod:dojo> +ls %

54```

60```

56Notice how `+cat %` does the same thing. That's because everything in Clay,

62Notice how `+cat %` does the same thing. That's because everything in Clay,

57including directories, is a file.

63including directories, is a file.

59−Sync from your friend `~some-ship`'s `%experiment` desk to your

65+Sync from your friend `~bus`'s `%experiment` desk to your `%sandbox` desk:

60−`%sandbox` desk:

62```

67```

63−~your-urbit:dojo> |sync %sandbox ~some-ship %experiment

68+~zod:dojo> |sync %sandbox ~bus %experiment

64```

69```

66If and when your sync is successful, you will receive a message:

71If and when your sync is successful, you will receive a message:

68```

73```

69−activated sync from %experiment on ~some-ship to %sandbox

74+kiln: sync succeeded from %experiment on ~bus to %sandbox

70```

75```

72The ship that you sync from will get their own message indicating that you're

77The ship that you sync from will get their own message indicating that you're

73both connected as peers:

78both connected as peers:

75```

80```

76−; ~your-urbit is your neighbor.

81+; ~zod is your neighbor.

77```

82```

79---

84---

81### Clay manual

86### Clay manual

88+The following constitutes an explanation of handy commands that most Urbit

89+pilots will want to know at some point. Reading this section will get you to the

90+point that you can navigate the file system, sync with Unix, merge your desk,

91+and other basic tasks familiar to novice users of the Unix terminal.

92+

83#### Paths

93#### Paths

85−A path in Clay is a list of URL-safe text, restricted to the characters

95+A path in Clay is a list of URL-safe text, restricted to the characters `[a

86−`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,

96+z]`,`[0 9]`, `.`, `-`, `_`, and `~`. This path is a list of strings each

87−meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.

88−In other words, paths are expressed as `/foo/bar/baz`. File extensions are

97+prepended by `/`. In other words, paths are expressed as `/foo/bar/baz`. File

89−separated from file names with `/`, not `.`. Extensions are syntactically

98+extensions are separated from file names with `/`, not `.`. Extensions are

90−identical to subdirectories, except that they must terminate the path.

99+syntactically identical to subdirectories, except that they must terminate the

100+path.

101

92−Paths begin with a piece of data called a `beak`. A beak is formally a

102+Paths begin with three strings indicating the ship, desk, and revision, and

93−`(p=ship q=desk r=case)`; it has three components, and might look like

94−`/~dozbud-namsep/home/11`.

103+might look like `/~dozbud-namsep/home/11`.

104

96−The first `beak` component is `ship`, which is, as you might guess, the name of

105+The first component is `ship`, which is, as you might guess, the name of

97an Urbit ship. The second component is `desk`, which is a workspace meant to

106an Urbit ship. The second component is `desk`, which is a workspace meant to

98−contain other directories; the default desk is `%home`. The third component is

107+contain other directories; the default `desk` is `%home`. The third component is

99−`case`, which represents version information in various ways: date and time;

108+the revision, which represents version information in various ways: date and time;

100a version sequence, which is a value incremented by one whenever a file on the

109a version sequence, which is a value incremented by one whenever a file on the

101given `desk` is modified; or an arbitrary plaintext label.

110given `desk` is modified; or an arbitrary plaintext label.

102

111

103−You can find what your `beak` is at any given moment by

112+You can find what your current ship, desk, and revision is at any given moment by

104−typing `%` in the Dojo and looking at the first three results.

113+typing `%` in the Dojo and looking at the first three results. This will display

114+as a cell rather than a path, like

115+```

116+[~.~zod ~.home ~.~2021.3.19..16.11.20..0c60]

117+```

118+Here we see that the revision consists of the date, time, and a short hash.

105

119

106−We use `beak`s because, unlike the current internet, the Urbit network uses a

120+We use this format because, unlike the current internet, the Urbit network uses a

107global namespace. That means that a file named `example.hoon` in the `/gen`

121global namespace. That means that a file named `example.hoon` in the `/gen`

108directory on the `%home` desk of your ship `~lodleb-ritrul` would have a

122directory on the `%home` desk of your ship `~lodleb-ritrul` would have a

109universal address to anyone else on the network:

123universal address to anyone else on the network:

110`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of

124`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of

111course, doesn't mean that everyone on the network has privileges to access that

125course, doesn't mean that everyone on the network has privileges to access that

112−path.

126+path. But given the revision-controlled and immutable nature of Urbit, this

127+means that if the file requested is available, it will always be the same. This

128+means that if an Urbit is serving a webpage, that exact version will always be

129+retrievable (assuming you have access to it).

113

130

114−The structure that combines a `beak` with further path information is called a

115−`beam`.

116

131

117#### Relative paths

132#### Relative paths

118

133

119The `%` command, which we gestured at in the above section, represents the

134The `%` command, which we gestured at in the above section, represents the

120−**relative path**, which is the path where you are currently working. If your

135+**relative path**, which is the path where you are currently working.

121−working directory is just your home desk, indicated by the

122−prompt `~your-planet:dojo>`, then running the command below will print your

123−working directory's `beam` information: your `beak`, and a `~` that represents

124−the empty list since no path is present.

125−

126−```

127−~your-urbit:dojo> %

128−```

129

136

130`%`s can be stacked to indicate one level further up in the hierarchy for each

137`%`s can be stacked to indicate one level further up in the hierarchy for each

131additional `%`. Try the following command:

138additional `%`. Try the following command:

132

139

133```

140```

134−~your-planet:dojo> %%%

141+~zod:dojo> %%%

135```

142```

136

143

137−You'll probably notice that it only has your ship name and the empty list. The

144+You'll notice that it only has your ship name and the empty list. The

138−two additional `%`s abandoned the `case` and the `desk` information by moving

145+two additional `%`s abandoned the revision and the `desk` information by moving

139up twice the hierarchy.

146up twice the hierarchy.

140

147

141There are no local relative paths. `/foo/bar` must be written as

148There are no local relative paths. `/foo/bar` must be written as

@@ -147,29 +154,31 @@ You don't need to write out the explicit path every time you want to reference

147somewhere outside of your working directory. You can substitute `=` for the

154somewhere outside of your working directory. You can substitute `=` for the

148segments of a path.

155segments of a path.

149

156

150−Recall that a full address in the the Urbit namespace is a `beam`: the

157+Recall that a full address in the the Urbit namespace is of the form

151−`/ship/desk/case/path`. If you've switched to another desk before, you're

158+`/ship/desk/case/path`. To switch to the `%sandbox` `desk`, you would enter

152−already familiar with substitution syntax:

153

159

154```

160```

155−~your-urbit:dojo> =dir /=sandbox=

161+~sampel-palnet:dojo> =dir /=sandbox=

156```

162```

157

163

164+`=dir` is used to change the working directory - we will see more on it

165+[below](#changing-directories.)

166+

158The above command uses substitution to use your current `ship` and

167The above command uses substitution to use your current `ship` and

159−`case`; only the `desk` argument, which is located between the other two, is

168+revision; only the `desk` argument, which is located between the other two, is

160given something new. Without substitution, you would need to write:

169given something new. Without substitution, you would need to write:

161

170

162```

171```

163−~your-urbit:dojo> =dir /~your-urbit/sandbox/85

172+~sampel-palnet:dojo> =dir /~sampel-palnet/sandbox/85

164```

173```

165

174

166−Substitutions work the same way in `beak`s (the `ship/desk/case` part) and

175+Substitutions work the same way in the `ship/desk/case` and

167paths. For example, if you are in the `/gen` directory, you can reference a file

176paths. For example, if you are in the `/gen` directory, you can reference a file

168in the `/app` directory like below. (`+cat` displays the contents of a file).

177in the `/app` directory like below. (`+cat` displays the contents of a file).

169

178

170```

179```

171−~your-urbit:dojo> =dir %/gen

180+~sampel-palnet:dojo> =dir %/gen

172−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon

181+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> +cat /===/app/curl/hoon

173```

182```

174

183

175Note what was substituted out, and note that we don't need to separate `=` with

184Note what was substituted out, and note that we don't need to separate `=` with

@@ -179,8 +188,8 @@ If we changed our working directory to something called `/gen/gmail`, we could

179access a file called

188access a file called

180

189

181```

190```

182−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail

191+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %/gmail

183−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon

192+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /===/app/=/split/hoon

184```

193```

185

194

186Because both paths share a directory named `/gmail` at the same position in the

195Because both paths share a directory named `/gmail` at the same position in the

@@ -192,11 +201,11 @@ We can do the same thing between desks. If `%sandbox` has been merged with

192command.

201command.

193

202

194```

203```

195−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon

204+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /=sandbox=/app/=/split/hoon

196```

205```

197

206

198Most commonly this is used to avoid having to know the current revision

207Most commonly this is used to avoid having to know the current revision

199−number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`

208+number in the `dojo`: `/~lodleb-ritrul/home/~2021.3.19..16.11.20..0c60/gen/example/hoon`

200

209

201#### Changing directories

210#### Changing directories

202

211

@@ -205,23 +214,23 @@ Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.

205For example, the syntax to navigate to `/home/gen/ask` is:

214For example, the syntax to navigate to `/home/gen/ask` is:

206

215

207```

216```

208−~your-urbit:dojo> =dir /=home=/gen/ask

217+~sampel-palnet:dojo> =dir /=home=/gen/ask

209```

218```

210

219

211This command will turn your prompt into something like this:

220This command will turn your prompt into something like this:

212

221

213```

222```

214−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>

223+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask>

215```

224```

216

225

217Using `=dir` without anything else uses the null path, which returns you to

226Using `=dir` without anything else uses the null path, which returns you to

218your home desk.

227your home desk.

219

228

220```

229```

221−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir

230+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask> =dir

222```

231```

223

232

224−Your dojo prompt will turn back into `~your-urbit:dojo>`.

233+Your dojo prompt will turn back into `~sampel-palnet:dojo>`.

225

234

226To go up levels in the path hierarchy, recall the relative path expression

235To go up levels in the path hierarchy, recall the relative path expression

227`%`. Stacking them represents another level higher in the hierarchy than

236`%`. Stacking them represents another level higher in the hierarchy than

@@ -229,22 +238,23 @@ the current working directory for each `%` beyond the initial. The command below

229brings you one level up:

238brings you one level up:

230

239

231```

240```

232−~your-urbit:dojo> =dir %/gen

241+~sampel-palnet:dojo> =dir %/gen

233−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%

242+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %%

234```

243```

235

244

236### Revision-control

245### Revision-control

237

246

238#### Mount

247#### Mount

239

248

240−Syntax: `|mount /clay/path [Unix-name]`

249+Syntax: `|mount %/clay/path %mount-point`

241

250

242−Mount the `clay-path` at the Unix mount point `Unix-name`.

251+Mount the `/clay/path` at the Unix mount point `mount-point` with your pier as

252+root directory.

243

253

244**Examples:**

254**Examples:**

245

255

246```

256```

247−|mount %/gen generators

257+|mount %/gen %generators

248```

258```

249

259

250Mounts `%/gen` to `/generators` inside your pier directory.

260Mounts `%/gen` to `/generators` inside your pier directory.

@@ -274,57 +284,65 @@ Unmounts the Unix path `/generators`.

274#### Merge

284#### Merge

275

285

276```

286```

277−|merge desk beak[, =gem strategy]

287+|merge %target-desk ~source-ship %source-desk

278```

288```

279

289

280−Merges a `beak` into a `desk` using an optional merge `strategy`.

290+Merges a source `desk` into a target `desk`.

281

291

282−A `beak` is a ship-desk-case triple, encoded as a

292+This can optionally include a [merge

283−path(`/~dozbud/home/2`)

293+strategy](@/docs/arvo/clay/using.md#strategies):

284

294

285−**Examples:**

295+```

296+|merge %target-desk ~source-ship %source-desk, =gem %strategy

297+```

298+

299+You may also merge a Clay path on your own ship to a `desk`, along with an

300+optional strategy.

286

301

287```

302```

288−|merge %home-work /=home=, =gem %fine

303+|merge %target-get %/clay/path, =gem %strategy

289```

304```

290

305

291−Merge `/=home=` into `%home-work` using merge strategy `%fine`.

306+**Examples:**

292

307

293```

308```

294|merge %examples ~wacbex-ribmex %examples

309|merge %examples ~wacbex-ribmex %examples

295```

310```

296

311

297−Merge the `%examples` desk from `~waxbex-ribmex`

312+Merge the `%examples` `desk` from `~waxbex-ribmex`

313+

314+```

315+|merge %home-work /=home=, =gem %fine

316+```

317+

318+Merge `/=home=` into `%home-work` using merge strategy `%fine`.

319+

298

320

299#### Sync

321#### Sync

300

322

301```

323```

302−|sync desk plot [plot-desk]

324+|sync %target-desk ~source-ship %target-desk

303```

325```

304

326

305−Subscribe to continuous updates from remote `plot` on local `desk`.

327+Subscribe to continuous updates from remote `desk` on local `desk`. Non-comet

306−`plot-desk` can specify the remote `desk` name. When omitted it defaults

307−to being the same as `desk`. Non-comet urbits have

308−`|sync %home ~parent %kids` automatically set up (where `~parent` is the

328+urbits have `|sync %home ~sponsor %kids` automatically set up (where `~sponsor`

309−planet that issued a moon, the star that issued a planet, or the galaxy

329+is the planet that issued a moon, the star that issued a planet, or the galaxy

310that issued a star).

330that issued a star).

311

331

312**Examples:**

332**Examples:**

313

333

314```

334```

315|sync %home-local ~dozbud %home

335|sync %home-local ~dozbud %home

316−

317−|sync %home ~doznec

318```

336```

319

337

320#### Unsync

338#### Unsync

321

339

322```

340```

323−|unsync desk plot [plot-desk]

341+|unsync %target-desk ~source-ship %source-desk

324```

342```

325

343

326−Unsubscribe from updates from remote `plot` on local `desk` with

344+Unsubscribe from updates from remote `desk` on local `desk`. Arguments must

327−optional `plot-desk`. Arguments must match original `|sync` command.

345+match original `|sync` command.

328

346

329Example:

347Example:

330

348

@@ -332,23 +350,7 @@ Example:

332|unsync %home-local ~dozbud %home

350|unsync %home-local ~dozbud %home

333```

351```

334

352

335−#### Label

336−

337−```

338−|label desk name

339−```

340−

341−Label the current version of `desk` `name`.

342−

343−Example:

344−

345−```

346−|label %home release

347−```

348−

349−### Merge strategies

350

353

351−See [Clay merge strategies](@/docs/arvo/clay/using.md#merging).

352### Manipulation

354### Manipulation

353

355

354#### `+cat`

356#### `+cat`

@@ -368,7 +370,7 @@ Similar to Unix `ls`. `+ls` takes a single `path`.

368Produces a list of names at the `path`.

370Produces a list of names at the `path`.

369

371

370```

372```

371−~your-urbit:dojo> +cat %/our/home/gen/curl/hoon

373+~sampel-palnet:dojo> +cat %/our/home/gen/curl/hoon

372```

374```

373

375

374#### `|rm`

376#### `|rm`