annotate rust/rhg/README.md @ 49564:b1c20e41098f stable

rhg: add `config.rhg` helptext This will make using `rhg` more user-friendly and features more discoverable.
author Raphaël Gomès <rgomes@octobus.net>
date Thu, 03 Nov 2022 15:42:33 +0100
parents 6df528ed47a9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.
49564
b1c20e41098f rhg: add `config.rhg` helptext
Raphaël Gomès <rgomes@octobus.net>
parents: 47779
diff changeset
22 It has some specific configuration in the `[rhg]` section.
47779
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
23
49564
b1c20e41098f rhg: add `config.rhg` helptext
Raphaël Gomès <rgomes@octobus.net>
parents: 47779
diff changeset
24 See `hg help config.rhg` for details.
47779
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
25
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
26 ## 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
27
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
28 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
29 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
30 `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
31
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
32 * 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
33 * 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
34 * 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
35 `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
36 * Configure `~/.hgrc` with:
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
37
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
38 ```
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
39 [rhg]
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
40 on-unsupported = fallback
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
41 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
42 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
43 ```
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
44
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
45 * 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
46 `hg notarealsubcommand`
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
47 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
48
6df528ed47a9 rhg: Add build and config instructions to the README file
Simon Sapin <simon.sapin@octobus.net>
parents: 44981
diff changeset
49 * 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
50 `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
51 starts with `unsupported feature:`.