Mercurial > hg
annotate rust/rhg/README.md @ 49249:db19f6be0442
debugindex: rename to debugindex debug-revlog-index
The command dump some content of the revlog index and omit a lot of
information. I am going to make it display the missing information.
For clarity, we rename the command to explicitly mention revlog.
author | Pierre-Yves David <pierre-yves.david@octobus.net> |
---|---|
date | Mon, 30 May 2022 11:30:48 +0200 |
parents | 6df528ed47a9 |
children | b1c20e41098f |
rev | line source |
---|---|
47779
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
1 # `rhg` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
2 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
3 The `rhg` executable implements a subset of the functionnality of `hg` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
4 using only Rust, to avoid the startup cost of a Python interpreter. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
5 This subset is initially small but grows over time as `rhg` is improved. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
6 When fallback to the Python implementation is configured (see below), |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
7 `rhg` aims to be a drop-in replacement for `hg` that should behave the same, |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
8 except that some commands run faster. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
9 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
10 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
11 ## Building |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
12 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
13 To compile `rhg`, either run `cargo build --release` from this `rust/rhg/` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
14 directory, or run `make build-rhg` from the repository root. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
15 The executable can then be found at `rust/target/release/rhg`. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
16 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
17 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
18 ## Mercurial configuration |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
19 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
20 `rhg` reads Mercurial configuration from the usual sources: |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
21 the user’s `~/.hgrc`, a repository’s `.hg/hgrc`, command line `--config`, etc. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
22 It has some specific configuration in the `[rhg]` section: |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
23 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
24 * `on-unsupported` governs the behavior of `rhg` when it encounters something |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
25 that it does not support but “full” `hg` possibly does. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
26 This can be in configuration, on the command line, or in a repository. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
27 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
28 - `abort`, the default value, makes `rhg` print a message to stderr |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
29 to explain what is not supported, then terminate with a 252 exit code. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
30 - `abort-silent` makes it terminate with the same exit code, |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
31 but without printing anything. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
32 - `fallback` makes it silently call a (presumably Python-based) `hg` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
33 subprocess with the same command-line parameters. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
34 The `rhg.fallback-executable` configuration must be set. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
35 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
36 * `fallback-executable`: path to the executable to run in a sub-process |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
37 when falling back to a Python implementation of Mercurial. |
44981 | 38 |
47779
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
39 * `allowed-extensions`: a list of extension names that `rhg` can ignore. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
40 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
41 Mercurial extensions can modify the behavior of existing `hg` sub-commands, |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
42 including those that `rhg` otherwise supports. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
43 Because it cannot load Python extensions, finding them |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
44 enabled in configuration is considered “unsupported” (see above). |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
45 A few exceptions are made for extensions that `rhg` does know about, |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
46 with the Rust implementation duplicating their behavior. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
47 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
48 This configuration makes additional exceptions: `rhg` will proceed even if |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
49 those extensions are enabled. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
50 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
51 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
52 ## Installation and configuration example |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
53 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
54 For example, to install `rhg` as `hg` for the current user with fallback to |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
55 the system-wide install of Mercurial, and allow it to run even though the |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
56 `rebase` and `absorb` extensions are enabled, on a Unix-like platform: |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
57 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
58 * Build `rhg` (see above) |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
59 * Make sure the `~/.local/bin` exists and is in `$PATH` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
60 * From the repository root, make a symbolic link with |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
61 `ln -s rust/target/release/rhg ~/.local/bin/hg` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
62 * Configure `~/.hgrc` with: |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
63 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
64 ``` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
65 [rhg] |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
66 on-unsupported = fallback |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
67 fallback-executable = /usr/bin/hg |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
68 allowed-extensions = rebase, absorb |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
69 ``` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
70 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
71 * Check that the output of running |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
72 `hg notarealsubcommand` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
73 starts with `hg: unknown command`, which indicates fallback. |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
74 |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
75 * Check that the output of running |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
76 `hg notarealsubcommand --config rhg.on-unsupported=abort` |
6df528ed47a9
rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents:
44981
diff
changeset
|
77 starts with `unsupported feature:`. |