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

git.iko.soy/urbit.org

on 514b5fc help sign in

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

379 lines 11 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

12mounted directory is always at the root of your pier directory.

14For more information on Clay, see the [Overview](/docs/arvo/clay/clay), and

15additional usage information at [Using Clay](/docs/arvo/clay/using).

17### Quickstart

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

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

21that the command was successful.

23A [`desk`](/docs/glossary/desk) is something like an independently

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

25files live in the `%base` desk.

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

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

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

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

32`desk` based on the `%base` `desk` (`our` produces your ship name):

34```

35~zod:dojo> |merge %sandbox our %base

36```

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

39your `%sandbox` desk to Unix:

41```

42~zod: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 use `%` to mean "current directory." The result of the command below

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

52```

53~zod: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 `~bus`'s `%experiment` desk to your `%sandbox` desk:

61```

62~zod:dojo> |sync %sandbox ~bus %experiment

63```

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

67```

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

69```

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

72both connected as peers:

74```

75; ~zod is your neighbor.

76```

78---

80### Clay manual

82The following constitutes an explanation of handy commands that most Urbit

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

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

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

87#### Paths

89A path in Clay is a list of URL-safe text, restricted to the characters `[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. This path is a list of strings each

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

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

92syntactically identical to subdirectories, except that they must terminate the

93path.

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

96might look like `/~dozbud-namsep/base/11`.

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

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

100contain other directories; the default `desk` is `%base`. The third component is

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

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

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

104

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

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

107as a cell rather than a path, like

108

109```

110[~.~zod ~.base ~.~2021.3.19..16.11.20..0c60]

111```

112

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

114

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

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

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

118universal address to anyone else on the network:

119`/~lodleb-ritrul/base/186/gen/example/hoon`. That, of

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

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

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

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

124retrievable (assuming you have access to it).

125

126#### Relative paths

127

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

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

130

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

132additional `%`. Try the following command:

133

134```

135~zod:dojo> %%%

136```

137

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

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

140up twice the hierarchy.

141

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

143`%/foo/bar`.

144

145#### Substitution

146

147You don't need to write out the explicit path every time you want to reference

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

149segments of a path.

150

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

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

153

154```

155~sampel-palnet:dojo> =dir /=sandbox=

156```

157

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

159[below](#changing-directories.)

160

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

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

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

164

165```

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

167```

168

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

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

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

172

173```

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

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

176```

177

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

179`/`.

180

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

182access a file called

183

184```

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

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

187```

188

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

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

191works!

192

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

194`%base`, the following command will produce the same results as the above

195command.

196

197```

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

199```

200

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

202number in the `dojo`: `/~lodleb-ritrul/base/~2021.3.19..16.11.20..0c60/gen/example/hoon`

203

204#### Changing directories

205

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

207

208For example, the syntax to navigate to `/base/gen/ask` is:

209

210```

211~sampel-palnet:dojo> =dir /=base=/gen/ask

212```

213

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

215

216```

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

218```

219

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

221your base desk.

222

223```

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

225```

226

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

228

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

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

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

232brings you one level up:

233

234```

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

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

237```

238

239### Revision-control

240

241#### Mount

242

243Syntax: `|mount %/clay/path %mount-point`

244

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

246root directory.

247

248**Examples:**

249

250```

251|mount %/gen %generators

252```

253

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

255

256#### Unmount

257

258```

259|unmount %mount-point

260```

261

262Unmount the the mount point from Unix.

263

264**Examples:**

265

266```

267|unmount %foo

268```

269

270Unmounts the Unix path `/foo`.

271

272#### Merge

273

274```

275|merge %target-desk ~source-ship %source-desk

276```

277

278Merges a source `desk` into a target `desk`.

279

280This can optionally include a [merge

281strategy](/docs/arvo/clay/using#strategies):

282

283```

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

285```

286

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

288optional strategy.

289

290```

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

292```

293

294**Examples:**

295

296```

297|merge %examples ~wacbex-ribmex %examples

298```

299

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

301

302```

303|merge %work /=base=, =gem %fine

304```

305

306Merge `/=base=` into `%work` using merge strategy `%fine`.

307

308#### Sync

309

310```

311|sync %target-desk ~source-ship %target-desk

312```

313

314Subscribe to continuous updates from remote `desk` on local `desk`.

315

316**Examples:**

317

318```

319|sync %foo ~dozbud %kids

320```

321

322#### Unsync

323

324```

325|unsync %target-desk ~source-ship %source-desk

326```

327

328Unsubscribe from updates from remote `desk` on local `desk`. Arguments must

329match original `|sync` command.

330

331Example:

332

333```

334|unsync %foo ~dozbud %kids

335```

336

337### Manipulation

338

339#### `+cat`

340

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

342

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

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

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

346

347#### `+ls`

348

349Syntax: `+ls path`

350

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

352

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

354

355```

356~sampel-palnet:dojo> +cat %/our/base/gen/curl/hoon

357```

358

359#### `|rm`

360

361Syntax: `|rm path`

362

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

364'directory'.

365

366#### `|cp`

367

368Syntax: `|cp to from`

369

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

371

372#### `|mv`

373

374Syntax: `|mv to from`

375

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

377

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

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