content/using/os/filesystem.md · urbit.org

git.iko.soy/urbit.org

on c2a28fa help sign in

urbit.org/content/using/os/filesystem.md

395 lines 10 kB history raw

1+++

2title = "Filesystem"

3template = "doc.html"

4weight = 3

5+++

7Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,

8referentially transparent namespace. An easy way to think about it is like typed

9`git`.

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### 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.

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

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

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

24desk based on the `%home` desk:

26```

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

28```

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

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

32very long names.

34```

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

36```

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

39your `sandbox` desk to Unix:

41```

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

43```

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

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

47a file.

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

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

52```

53~your-urbit:dojo> +ls %

54```

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

57including directories, is a file.

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

60`%sandbox` desk:

62```

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

64```

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

68```

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

70```

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

73both connected as peers:

75```

76; ~your-urbit is your neighbor.

77```

79---

81### Clay manual

83#### Paths

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

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

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

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

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

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

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

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

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

96The first `beak` 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

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

99`case`, 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

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

102

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

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

105

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

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

109universal address to anyone else on the network:

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

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

112path.

113

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

115`beam`.

116

117#### Relative paths

118

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

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

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

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

124the empty list since no path is present.

125

126```

127~your-urbit:dojo> %

128```

129

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

131additional `%`. Try the following command:

132

133```

134~your-planet:dojo> %%%

135```

136

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

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

139up twice the hierarchy.

140

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

142`%/foo/bar`.

143

144#### Substitution

145

146You 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

148segments of a path.

149

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

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

152already familiar with substitution syntax:

153

154```

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

156```

157

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

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

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

161

162```

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

164```

165

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

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

169

170```

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

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

173```

174

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

176`/`.

177

178If we changed our working directory to something called `/gen/gmail`, we could

179access a file called

180

181```

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

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

184```

185

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

187address hierarchy – which, if you recall, is just a `list` – the above command

188works!

189

190We can do the same thing between desks. If `%sandbox` has been merged with

191`%home`, the following command will produce the same results as the above

192command.

193

194```

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

196```

197

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

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

200

201#### Changing directories

202

203Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.

204

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

206

207```

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

209```

210

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

212

213```

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

215```

216

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

218your home desk.

219

220```

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

222```

223

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

225

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

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

228the current working directory for each `%` beyond the initial. The command below

229brings you one level up:

230

231```

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

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

234```

235

236### Revision-control

237

238#### Mount

239

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

241

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

243

244**Examples:**

245

246```

247|mount %/gen generators

248```

249

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

251

252#### Unmount

253

254```

255|unmount [clay-path || Unix-name]

256```

257

258Unmount the path or name from Unix.

259

260**Examples:**

261

262```

263|unmount %/gen

264```

265

266Unmounts the Clay path `%/gen` from whatever name it was mounted as.

267

268```

269|unmount %generators

270```

271

272Unmounts the Unix path `/generators`.

273

274#### Merge

275

276```

277|merge desk beak[, =gem strategy]

278```

279

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

281

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

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

284

285**Examples:**

286

287```

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

289```

290

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

292

293```

294|merge %examples ~wacbex-ribmex %examples

295```

296

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

298

299#### Sync

300

301```

302|sync desk plot [plot-desk]

303```

304

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

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

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

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

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

310that issued a star).

311

312**Examples:**

313

314```

315|sync %home-local ~dozbud %home

316

317|sync %home ~doznec

318```

319

320#### Unsync

321

322```

323|unsync desk plot [plot-desk]

324```

325

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

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

328

329Example:

330

331```

332|unsync %home-local ~dozbud %home

333```

334

335#### Label

336

337```

338|label desk name

339```

340

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

342

343Example:

344

345```

346|label %home release

347```

348

349### Merge strategies

350

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

352

353### Manipulation

354

355#### `+cat`

356

357Syntax: `+cat path [path ...]`

358

359Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their

360contents. If that `path` is a file, the contents of the file is printed. If the

361`path` terminates in a directory, the list of names at that path is produced.

362

363#### `+ls`

364

365Syntax: `+ls path`

366

367Similar to Unix `ls`. `+ls` takes a single `path`.

368

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

370

371```

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

373```

374

375#### `|rm`

376

377Syntax: `|rm path`

378

379Remove the data at `path`. `Path` must be a path to the actual node, not a

380'directory'.

381

382#### `|cp`

383

384Syntax: `|cp to from`

385

386Copy the file at `from` into the path `to`.

387

388#### `|mv`

389

390Syntax: `|mv to from`

391

392Move the file at `from` into the path `to`.

393

394In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`

395doesn't happen unless the `|cp` succeeds.