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 remember is that anything under a heading can be dotted
e.g. `user.name = "YOUR NAME"` is equivalent to: e.g. `user.name = "YOUR NAME"` is equivalent to:
```toml
[user] [user]
name = "YOUR NAME" name = "YOUR NAME"
```
Headings only need to be set once in the real config file but Jujutsu favors the 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 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 ## User settings
```toml
user.name = "YOUR NAME" user.name = "YOUR NAME"
user.email = "YOUR_EMAIL@example.com" user.email = "YOUR_EMAIL@example.com"
```
Don't forget to change these to your own details! 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). This setting overrides the `NO_COLOR` environment variable (if set).
```toml
ui.color = "never" # Turn off color ui.color = "never" # Turn off color
```
### Shortest unique prefixes for ids ### Shortest unique prefixes for ids
```toml
ui.unique-prefixes = "none" ui.unique-prefixes = "none"
```
Whether to highlight a unique prefix for commit & change ids. Possible values Whether to highlight a unique prefix for commit & change ids. Possible values
are `brackets` and `none` (default: `brackets`). are `brackets` and `none` (default: `brackets`).
### Relative timestamps ### Relative timestamps
```toml
ui.relative-timestamps = true ui.relative-timestamps = true
```
False by default, but setting to true will change timestamps to be rendered 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. 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: You can define aliases for commands, including their arguments. For example:
```toml
# `jj l` shows commits on the working-copy commit's (anonymous) branch # `jj l` shows commits on the working-copy commit's (anonymous) branch
# compared to the `main` branch # compared to the `main` branch
aliases.l = ["log", "-r", "(main..@): | (main..@)-"] aliases.l = ["log", "-r", "(main..@): | (main..@)-"]
```
## Editor ## Editor
@ -87,14 +99,19 @@ a `$`):
Pico is the default editor in the absence of any other setting, but you could Pico is the default editor in the absence of any other setting, but you could
set it explicitly too. set it explicitly too.
```toml
ui.editor = "pico" ui.editor = "pico"
```
To use NeoVim instead: To use NeoVim instead:
```toml
ui.editor = "nvim" ui.editor = "nvim"
```
For GUI editors you possibly need to use a `-w` or `--wait`. Some examples: For GUI editors you possibly need to use a `-w` or `--wait`. Some examples:
```toml
ui.editor = "code -w" # VS Code ui.editor = "code -w" # VS Code
ui.editor = "bbedit -w" # BBEdit ui.editor = "bbedit -w" # BBEdit
ui.editor = "subl -n -w" # Sublime Text 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", ui.editor = ["C:/Program Files/Notepad++/notepad++.exe",
"-multiInst", "-notabbar", "-nosession", "-noPlugin"] # Notepad++ "-multiInst", "-notabbar", "-nosession", "-noPlugin"] # Notepad++
ui.editor = "idea --temp-project --wait" #IntelliJ ui.editor = "idea --temp-project --wait" #IntelliJ
```
Obviously, you would only set one line, don't copy them all in! 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: For example:
```toml
ui.diff-editor = "kdiff3" ui.diff-editor = "kdiff3"
```
Custom arguments can be added, and will be inserted before the paths to diff: 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.program = "kdiff3" # Defaults to the name of the tool if not specified
merge-tools.kdiff3.edit-args = ["--merge", "--cs", "CreateBakFiles=0"] merge-tools.kdiff3.edit-args = ["--merge", "--cs", "CreateBakFiles=0"]
```
### Using Vim as a diff editor ### 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 The `ui.merge-editor` key specifies the tool used for three-way merge tools
by `jj resolve`. For example: by `jj resolve`. For example:
```toml
ui.merge-editor = "meld" # Or "kdiff3" or "vimdiff" ui.merge-editor = "meld" # Or "kdiff3" or "vimdiff"
```
The "meld", "kdiff3", and "vimdiff" tools can be used out of the box, as long as The "meld", "kdiff3", and "vimdiff" tools can be used out of the box, as long as
they are installed. 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 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.) 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.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.kdiff3.merge-args = ["$base", "$left", "$right", "-o", "$output", "--auto"]
merge-tools.meld.merge-args = ["$left", "$base", "$right", "-o", "$output", "--auto-merge"] 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"] "-c", "set write"]
merge-tools.vimdiff.program = "vim" merge-tools.vimdiff.program = "vim"
merge-tools.vimdiff.merge-tool-edits-conflict-markers = true # See below for an explanation merge-tools.vimdiff.merge-tool-edits-conflict-markers = true # See below for an explanation
```
`jj` replaces the following arguments with the appropriate file names: `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 to a TOML file that will be used instead of any configuration file in the
default locations. For example, default locations. For example,
```shell
env JJ_CONFIG=/dev/null jj log # Ignores any settings specified in the config file. 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 You can use one or more `--config-toml` options on the command line to specify
additional configuration settings. This overrides settings defined in config additional configuration settings. This overrides settings defined in config
files or environment variables. For example, files or environment variables. For example,
```shell
jj --config-toml='ui.color="always"' --config-toml='ui.difftool="kdiff3"' split 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 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 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 In `sh`-compatible shells, `--config-toml` can be used to merge entire TOML
files with the config specified in `.jjconfig.toml`: files with the config specified in `.jjconfig.toml`:
```shell
jj --config-toml="$(cat extra-config.toml)" log jj --config-toml="$(cat extra-config.toml)" log
```