d2e0a35 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Merge pull request #572 from urbit/filesystem-fix

d2e0a35poprox6 years ago

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

@@ -10,132 +10,140 @@ 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`](@/docs/glossary/desk.md) is something like an independently

23+revision-controlled branch of your urbit's file-system. Your urbit's system

24+files live in the `%home` `desk`.

25+

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

26It'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`

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

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

28+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`

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

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

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

26```

33```

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

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

28```

35```

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

37Running `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

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

32−very long names.

39+comets due to their very long names.

34```

41```

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

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

36```

43```

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

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

39your `sandbox` desk to Unix:

46your `sandbox` desk to Unix:

41```

48```

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

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

43```

50```

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

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

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

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

47a file.

54a file.

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

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

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

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

52```

59```

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

60+~zod:dojo> +ls %

54```

61```

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

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

57including directories, is a file.

64including directories, is a file.

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

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

60−`%sandbox` desk:

62```

68```

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

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

64```

70```

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

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

68```

74```

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

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

70```

76```

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

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

73both connected as peers:

79both connected as peers:

75```

81```

76−; ~your-urbit is your neighbor.

82+; ~zod is your neighbor.

77```

83```

79---

85---

81### Clay manual

87### Clay manual

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

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

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

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

93+

83#### Paths

94#### Paths

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

96+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)`,

97+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

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

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

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

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

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

101+path.

102

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

103+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`.

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

105

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

106+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

107an 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

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

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

109+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

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

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

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

102

112

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

113+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.

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

115+as a cell rather than a path, like

116+```

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

118+```

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

105

120

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

121+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`

122global 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

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

109universal address to anyone else on the network:

124universal address to anyone else on the network:

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

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

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

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

112−path.

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

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

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

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

113

131

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

115−`beam`.

116

132

117#### Relative paths

133#### Relative paths

118

134

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

135The `%` 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

136+**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

137

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

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

131additional `%`. Try the following command:

139additional `%`. Try the following command:

132

140

133```

141```

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

142+~zod:dojo> %%%

135```

143```

136

144

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

145+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

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

139up twice the hierarchy.

147up twice the hierarchy.

140

148

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

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

@@ -147,29 +155,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

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

148segments of a path.

156segments of a path.

149

157

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

158+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

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

152−already familiar with substitution syntax:

153

160

154```

161```

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

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

156```

163```

157

164

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

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

167+

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

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

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

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

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

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

161

171

162```

172```

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

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

164```

174```

165

175

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

176+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

177paths. 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).

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

169

179

170```

180```

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

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

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

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

173```

183```

174

184

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

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

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

179access a file called

189access a file called

180

190

181```

191```

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

192+~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

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

184```

194```

185

195

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

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

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

192command.

202command.

193

203

194```

204```

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

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

196```

206```

197

207

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

208Most 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`

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

200

210

201#### Changing directories

211#### Changing directories

202

212

@@ -205,23 +215,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:

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

206

216

207```

217```

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

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

209```

219```

210

220

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

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

212

222

213```

223```

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

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

215```

225```

216

226

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

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

218your home desk.

228your home desk.

219

229

220```

230```

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

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

222```

232```

223

233

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

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

225

235

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

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

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

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

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

229brings you one level up:

239brings you one level up:

230

240

231```

241```

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

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

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

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

234```

244```

235

245

236### Revision-control

246### Revision-control

237

247

238#### Mount

248#### Mount

239

249

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

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

241

251

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

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

253+root directory.

243

254

244**Examples:**

255**Examples:**

245

256

246```

257```

247−|mount %/gen generators

258+|mount %/gen %generators

248```

259```

249

260

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

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

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

274#### Merge

285#### Merge

275

286

276```

287```

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

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

278```

289```

279

290

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

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

281

292

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

293+This can optionally include a [merge

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

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

284

295

285−**Examples:**

296+```

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

298+```

299+

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

301+optional strategy.

286

302

287```

303```

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

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

289```

305```

290

306

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

307+**Examples:**

292

308

293```

309```

294|merge %examples ~wacbex-ribmex %examples

310|merge %examples ~wacbex-ribmex %examples

295```

311```

296

312

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

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

314+

315+```

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

317+```

318+

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

320+

298

321

299#### Sync

322#### Sync

300

323

301```

324```

302−|sync desk plot [plot-desk]

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

303```

326```

304

327

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

328+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

329+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

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

310that issued a star).

331that issued a star).

311

332

312**Examples:**

333**Examples:**

313

334

314```

335```

315|sync %home-local ~dozbud %home

336|sync %home-local ~dozbud %home

316−

317−|sync %home ~doznec

318```

337```

319

338

320#### Unsync

339#### Unsync

321

340

322```

341```

323−|unsync desk plot [plot-desk]

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

324```

343```

325

344

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

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

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

346+match original `|sync` command.

328

347

329Example:

348Example:

330

349

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

332|unsync %home-local ~dozbud %home

351|unsync %home-local ~dozbud %home

333```

352```

334

353

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

354

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

352### Manipulation

355### Manipulation

353

356

354#### `+cat`

357#### `+cat`

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

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

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

369

372

370```

373```

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

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

372```

375```

373

376

374#### `|rm`

377#### `|rm`