ok/jj
1
0
Fork 0
forked from mirrors/jj

docs: use fenced code blocks and enable syntax highlighting of toml snippets

This commit is contained in:
Yuya Nishihara 2023-01-27 10:18:08 +09:00
parent c5cc2e6d46
commit a7d02e66de

View file

@ -12,8 +12,10 @@ See the [TOML site](https://toml.io/en/) for more on syntax. One thing to
remember is that anything under a heading can be dotted
e.g. `user.name = "YOUR NAME"` is equivalent to:
```toml
[user]
name = "YOUR NAME"
```
Headings only need to be set once in the real config file but Jujutsu favors the
dotted style in these instructions, if only because it's easier to write down in
@ -28,8 +30,10 @@ short if you ever need to check.
## User settings
```toml
user.name = "YOUR NAME"
user.email = "YOUR_EMAIL@example.com"
```
Don't forget to change these to your own details!
@ -42,18 +46,24 @@ Possible values are `always`, `never` and `auto` (default: `auto`).
This setting overrides the `NO_COLOR` environment variable (if set).
```toml
ui.color = "never" # Turn off color
```
### Shortest unique prefixes for ids
```toml
ui.unique-prefixes = "none"
```
Whether to highlight a unique prefix for commit & change ids. Possible values
are `brackets` and `none` (default: `brackets`).
### Relative timestamps
```toml
ui.relative-timestamps = true
```
False by default, but setting to true will change timestamps to be rendered
as `x days/hours/seconds ago` instead of being rendered as a full timestamp.
@ -72,9 +82,11 @@ a `$`):
You can define aliases for commands, including their arguments. For example:
```toml
# `jj l` shows commits on the working-copy commit's (anonymous) branch
# compared to the `main` branch
aliases.l = ["log", "-r", "(main..@): | (main..@)-"]
```
## Editor
@ -87,14 +99,19 @@ a `$`):
Pico is the default editor in the absence of any other setting, but you could
set it explicitly too.
```toml
ui.editor = "pico"
```
To use NeoVim instead:
```toml
ui.editor = "nvim"
```
For GUI editors you possibly need to use a `-w` or `--wait`. Some examples:
```toml
ui.editor = "code -w" # VS Code
ui.editor = "bbedit -w" # BBEdit
ui.editor = "subl -n -w" # Sublime Text
@ -102,6 +119,7 @@ For GUI editors you possibly need to use a `-w` or `--wait`. Some examples:
ui.editor = ["C:/Program Files/Notepad++/notepad++.exe",
"-multiInst", "-notabbar", "-nosession", "-noPlugin"] # Notepad++
ui.editor = "idea --temp-project --wait" #IntelliJ
```
Obviously, you would only set one line, don't copy them all in!
@ -113,12 +131,16 @@ directories to diff are passed as the first and second argument respectively.
For example:
```toml
ui.diff-editor = "kdiff3"
```
Custom arguments can be added, and will be inserted before the paths to diff:
```toml
# merge-tools.kdiff3.program = "kdiff3" # Defaults to the name of the tool if not specified
merge-tools.kdiff3.edit-args = ["--merge", "--cs", "CreateBakFiles=0"]
```
### Using Vim as a diff editor
@ -135,7 +157,9 @@ the [`DirDiff` Vim plugin].
The `ui.merge-editor` key specifies the tool used for three-way merge tools
by `jj resolve`. For example:
```toml
ui.merge-editor = "meld" # Or "kdiff3" or "vimdiff"
```
The "meld", "kdiff3", and "vimdiff" tools can be used out of the box, as long as
they are installed.
@ -146,6 +170,7 @@ this key and other tool configuration options, here is the out-of-the-box
configuration of the three default tools. (There is no need to copy it to your
config file verbatim, but you are welcome to customize it.)
```toml
# merge-tools.kdiff3.program = "kdiff3" # Defaults to the name of the tool if not specified
merge-tools.kdiff3.merge-args = ["$base", "$left", "$right", "-o", "$output", "--auto"]
merge-tools.meld.merge-args = ["$left", "$base", "$right", "-o", "$output", "--auto-merge"]
@ -156,6 +181,7 @@ config file verbatim, but you are welcome to customize it.)
"-c", "set write"]
merge-tools.vimdiff.program = "vim"
merge-tools.vimdiff.merge-tool-edits-conflict-markers = true # See below for an explanation
```
`jj` replaces the following arguments with the appropriate file names:
@ -200,13 +226,17 @@ The location of the `jj` config file can also be overriden with the
to a TOML file that will be used instead of any configuration file in the
default locations. For example,
```shell
env JJ_CONFIG=/dev/null jj log # Ignores any settings specified in the config file.
```
You can use one or more `--config-toml` options on the command line to specify
additional configuration settings. This overrides settings defined in config
files or environment variables. For example,
```shell
jj --config-toml='ui.color="always"' --config-toml='ui.difftool="kdiff3"' split
```
Config specified this way must be valid TOML. In particular, string values must
be surrounded by quotes. To pass these quotes to `jj`, most shells require
@ -215,5 +245,6 @@ surrounding those quotes with single quotes as shown above.
In `sh`-compatible shells, `--config-toml` can be used to merge entire TOML
files with the config specified in `.jjconfig.toml`:
```shell
jj --config-toml="$(cat extra-config.toml)" log
```