utils-shell/lotabout.skim
1
0
Fork 0
mirror of https://github.com/lotabout/skim.git synced 2026-09-10 07:16:23 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

chore(deps): bump clap from 4.5.27 to 4.5.30 (#700)
Some checks failed
release-please / release-please (push) Has been cancelled
Details
Build & Test / unittests (linux, ubuntu-latest, stable, x86_64-unknown-linux-musl) (push) Has been cancelled
Details
Build & Test / unittests (macos, macos-latest, stable, x86_64-apple-darwin) (push) Has been cancelled
Details
Build & Test / e2e (linux, ubuntu-latest, stable, x86_64-unknown-linux-musl) (push) Has been cancelled
Details
Build & Test / e2e (macos, macos-latest, stable, x86_64-apple-darwin) (push) Has been cancelled
Details
Build & Test / clippy (push) Has been cancelled
Details
Build & Test / rustfmt (push) Has been cancelled
Details
release-please / setup-release (push) Has been cancelled
Details
release-please / publish-crate (push) Has been cancelled
Details
release-please / Build release binaries (aarch64, apple-darwin) (push) Has been cancelled
Details
release-please / Build release binaries (aarch64, unknown-linux-musl) (push) Has been cancelled
Details
release-please / Build release binaries (arm, unknown-linux-musl) (push) Has been cancelled
Details
release-please / Build release binaries (armv7, unknown-linux-musl) (push) Has been cancelled
Details
release-please / Build release binaries (x86_64, apple-darwin) (push) Has been cancelled
Details
release-please / Build release binaries (x86_64, unknown-linux-musl) (push) Has been cancelled
Details

Browse source 
* chore(deps): bump clap from 4.5.27 to 4.5.30

Bumps [clap](https://github.com/clap-rs/clap) from 4.5.27 to 4.5.30.
- [Release notes](https://github.com/clap-rs/clap/releases)
- [Changelog](https://github.com/clap-rs/clap/blob/master/CHANGELOG.md)
- [Commits](https://github.com/clap-rs/clap/compare/clap_complete-v4.5.27...clap_complete-v4.5.30)

---
updated-dependencies:
- dependency-name: clap
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* chore: migrate to clap markdown

* chore: fmt

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: LoricAndre <loric.andre@pm.me>
Co-authored-by: LoricAndre <57358788+LoricAndre@users.noreply.github.com>
This commit is contained in:
dependabot[bot] 2025-02-20 22:17:53 +01:00 committed by GitHub
parent b696fbbc1b
commit 9f02f95fbe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 737 additions and 470 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.rustfmt.toml
View file

@ -1,2 +1 @@
error_on_line_overflow = false
max_width = 120
max_width = 120

31
Cargo.lock generated
View file

@ -165,9 +165,9 @@ dependencies = [
[[package]]
name = "clap"
version = "4.5.27"
version = "4.5.30"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "769b0145982b4b48713e01ec42d61614425f27b7058bda7180a3a41f30104796"
checksum = "92b7b18d71fad5313a1e320fa9897994228ce274b60faa4d694fe0ea89cd9e6d"
dependencies = [
"clap_builder",
"clap_derive",
@ -175,9 +175,9 @@ dependencies = [
[[package]]
name = "clap_builder"
version = "4.5.27"
version = "4.5.30"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b26884eb4b57140e4d2d93652abfa49498b938b3c9179f9fc487b0acc3edad7"
checksum = "a35db2071778a7344791a4fb4f95308b5673d219dee3ae348b86642574ecc90c"
dependencies = [
"anstream",
"anstyle",
@ -216,12 +216,14 @@ dependencies = [
[[package]]
name = "clap_derive"
version = "4.5.24"
version = "4.5.28"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "54b755194d6389280185988721fffba69495eed5ee9feeee9a599b53db80318c"
checksum = "bf4ced95c6f4a675af3da73304b9ac4ed991640c36374e4b46795c49e17cf1ed"
dependencies = [
"anstyle",
"heck",
"proc-macro2",
"pulldown-cmark",
"quote",
"syn",
]
@ -700,6 +702,17 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "pulldown-cmark"
version = "0.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f86ba2052aebccc42cbbb3ed234b8b13ce76f75c3551a303cb2bcffcff12bb14"
dependencies = [
"bitflags 2.6.0",
"memchr",
"unicase",
]
[[package]]
name = "quote"
version = "1.0.37"
@ -1003,6 +1016,12 @@ dependencies = [
"unicode-width 0.1.14",
]
[[package]]
name = "unicase"
version = "2.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "75b844d17643ee918803943289730bec8aac480150456169e647ed0b576ba539"
[[package]]
name = "unicode-ident"
version = "1.0.14"

555
man/man1/sk.1
View file

@ -10,58 +10,53 @@ sk \- fuzzy finder in Rust
.PP
sk is a general purpose command\-line fuzzy finder.
.PP
.PP
ENVIRONMENT VARIABLES
.PP
SKIM_DEFAULT_COMMAND
SKIM_DEFAULT_COMMAND
.PP
Default command to use when input is tty. On *nix systems, sk runs the command with sh \-c, so make sure that
it\*(Aqs POSIX\-compliant.
Default command to use when input is tty. On *nix systems, sk runs the command with sh \-c, so make sure that it\*(Aqs POSIX\-compliant.
.PP
SKIM_DEFAULT_OPTIONS
SKIM_DEFAULT_OPTIONS
.PP
Default options. e.g. export SKIM_DEFAULT_OPTIONS="\-\-multi
Default options. e.g. export SKIM_DEFAULT_OPTIONS="\-\-multi"
.PP
EXTENDED SEARCH MODE
EXTENDED SEARCH MODE
.PP
Unless specified otherwise, sk will start in "extended\-search mode". In this mode, you can specify multiple patterns
delimited by spaces, such as: \*(Aqwild ^music .mp3$ sbtrkt !rmx
Unless specified otherwise, sk will start in "extended\-search mode". In this mode, you can specify multiple patterns delimited by spaces, such as: \*(Aqwild ^music .mp3$ sbtrkt !rmx
.PP
You can prepend a backslash to a space (\\ ) to match a literal space character.
You can prepend a backslash to a space (\\ ) to match a literal space character.
.PP
Exact\-match (quoted)
Exact\-match (quoted)
.PP
A term that is prefixed by a single\-quote character (\*(Aq) is interpreted as an "exact\-match" (or "non\-fuzzy") term. sk
will search for the exact occurrences of the string.
A term that is prefixed by a single\-quote character (\*(Aq) is interpreted as an "exact\-match" (or "non\-fuzzy") term. sk will search for the exact occurrences of the string.
.PP
Anchored\-match
Anchored\-match
.PP
A term can be prefixed by ^, or suffixed by $ to become an anchored\-match term. Then sk will search for the lines
that start with or end with the given string. An anchored\-match term is also an exact\-match term.
A term can be prefixed by ^, or suffixed by $ to become an anchored\-match term. Then sk will search for the lines that start with or end with the given string. An anchored\-match term is also an exact\-match term.
.PP
Negation
Negation
.PP
If a term is prefixed by !, sk will exclude the lines that satisfy the term from the result. In this case, sk per‐
forms exact match by default.
If a term is prefixed by !, sk will exclude the lines that satisfy the term from the result. In this case, sk per‐ forms exact match by default.
.PP
Exact\-match by default
Exact\-match by default
.PP
If you don\*(Aqt prefer fuzzy matching and do not wish to "quote" (prefixing with \*(Aq) every word, start sk with \-e or
\-\-exact option. Note that when \-\-exact is set, \*(Aq\-prefix "unquotes" the term.
If you don\*(Aqt prefer fuzzy matching and do not wish to "quote" (prefixing with \*(Aq) every word, start sk with \-e or \-\-exact option. Note that when \-\-exact is set, \*(Aq\-prefix "unquotes" the term.
.PP
OR operator
OR operator
.PP
A single bar character term acts as an OR operator. For example, the following query matches entries that start with
core and end with either go, rb, or py.
.PP
e.g. ^core go$ | rb$ | py$
A single bar character term acts as an OR operator. For example, the following query matches entries that start with core and end with either go, rb, or py.
.PP
Example: ^core go$ | rb$ | py$
.PP
EXIT STATUS
0 Normal exit
1 No match
2 Error
130 Interrupted with CTRL\-C or ESC
.PP
\- 0: Normal exit
.PP
\- 1: No match
.PP
\- 2: Error
.PP
\- 130: Interrupted with CTRL\-C or ESC
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
@ -79,19 +74,28 @@ Often used in combination with \-\-no\-sort
\fB\-\-no\-sort\fR
Do not sort the results
Often used in combination with \-\-tac Example: `history | sk \-\-tac \-\-no\-sort`
Often used in combination with \-\-tac
Example: history | sk \-\-tac \-\-no\-sort
.TP
\fB\-t\fR, \fB\-\-tiebreak\fR=\fITIEBREAK\fR [default: score,begin,end]
Comma\-separated list of sort criteria to apply when the scores are tied.
score Score of the fuzzy match algorithm
index Prefers line that appeared earlier in the input stream
begin Prefers line with matched substring closer to the beginning
end Prefers line with matched substring closer to the end
length Prefers line with shorter length
\- score: Score of the fuzzy match algorithm
\- Each criterion could be negated, e.g. (\-index)
\- Each criterion should appear only once in the list
\- index: Prefers line that appeared earlier in the input stream
\- begin: Prefers line with matched substring closer to the beginning
\- end: Prefers line with matched substring closer to the end
\- length: Prefers line with shorter length
Notes:
\- Each criterion could be negated, e.g. (\-index)
\- Each criterion should appear only once in the list
.br
.br
@ -100,23 +104,30 @@ Comma\-separated list of sort criteria to apply when the scores are tied.
\fB\-n\fR, \fB\-\-nth\fR=\fINTH\fR [default: ]
Fields to be matched
A field index expression can be a non\-zero integer or a range expression ([BEGIN]..[END]). \-\-nth
and \-\-with\-nth take a comma\-separated list of field index expressions.
A field index expression can be a non\-zero integer or a range expression ([BEGIN]..[END]). \-\-nth and \-\-with\-nth take a comma\-separated list of field index expressions.
**Examples:**
1 The 1st field
2 The 2nd field
\-1 The last field
\-2 The 2nd to last field
3..5 From the 3rd field to the 5th field
2.. From the 2nd field to the last field
..\-3 From the 1st field to the 3rd to the last field
.. All the fields
Examples:
\- 1: The 1st field
\- 2: The 2nd field
\- \-1: The last field
\- \-2: The 2nd to last field
\- 3..5: From the 3rd field to the 5th field
\- 2..: From the 2nd field to the last field
\- ..\-3: From the 1st field to the 3rd to the last field
\- ..: All the fields
.TP
\fB\-\-with\-nth\fR=\fIWITH_NTH\fR [default: ]
Fields to be transformed
See **nth** for the details
See nth for the details
.TP
\fB\-d\fR, \fB\-\-delimiter\fR=\fIDELIMITER\fR [default: [\\t\\n ]+]
Delimiter between fields
@ -132,9 +143,11 @@ Start in regex mode instead of fuzzy\-match
\fB\-\-algo\fR=\fIALGORITHM\fR [default: skim_v2]
Fuzzy matching algorithm
skim_v2 Latest skim algorithm, should be better in almost any case
skim_v1 Legacy skim algorithm
clangd Used in clangd for keyword completion
\- skim_v2: Latest skim algorithm, should be better in almost any case
\- skim_v1: Legacy skim algorithm
\- clangd: Used in clangd for keyword completion
.br
.br
@ -153,140 +166,225 @@ Determines whether or not to ignore case while matching
\fB\-b\fR, \fB\-\-bind\fR=\fIBIND\fR
Comma separated list of bindings
You can customize key bindings of sk with \-\-bind option which takes a comma\-separated list of
key binding expressions. Each key binding expression follows the following format: KEY:ACTION
You can customize key bindings of sk with \-\-bind option which takes a comma\-separated list of key binding expressions. Each key binding expression follows the following format: <key>:<action>
e.g. sk \-\-bind=ctrl\-j:accept,ctrl\-k:kill\-line
Example: sk \-\-bind=ctrl\-j:accept,ctrl\-k:kill\-line
AVAILABLE KEYS: (SYNONYMS)
ctrl\-[a\-z]
ctrl\-space
ctrl\-alt\-[a\-z]
alt\-[a\-zA\-Z]
alt\-[0\-9]
f[1\-12]
enter (ctrl\-m)
space
bspace (bs)
alt\-up
alt\-down
alt\-left
alt\-right
alt\-enter (alt\-ctrl\-m)
alt\-space
alt\-bspace (alt\-bs)
alt\-/
tab
btab (shift\-tab)
esc
del
up
down
left
right
home
end
pgup (page\-up)
pgdn (page\-down)
shift\-up
shift\-down
shift\-left
shift\-right
alt\-shift\-up
alt\-shift\-down
alt\-shift\-left
alt\-shift\-right
or any single character
ACTION: DEFAULT BINDINGS (NOTES):
abort ctrl\-c ctrl\-q esc
accept(...) enter (the argument will be printed when the binding is triggered)
append\-and\-select
backward\-char ctrl\-b left
backward\-delete\-char ctrl\-h bspace
backward\-kill\-word alt\-bs
backward\-word alt\-b shift\-left
beginning\-of\-line ctrl\-a home
clear\-screen ctrl\-l
delete\-char del
delete\-charEOF ctrl\-d
deselect\-all
down ctrl\-j ctrl\-n down
end\-of\-line ctrl\-e end
execute(...) (see below for the details)
execute\-silent(...) (see below for the details)
forward\-char ctrl\-f right
forward\-word alt\-f shift\-right
if\-non\-matched
if\-query\-empty
if\-query\-not\-empty
ignore
kill\-line
kill\-word alt\-d
next\-history (ctrl\-n on \-\-history or \-\-cmd\-history)
page\-down pgdn
page\-up pgup
half\-page\-down
half\-page\-up
preview\-up shift\-up
preview\-down shift\-down
preview\-left
preview\-right
preview\-page\-down
preview\-page\-up
previous\-history (ctrl\-p on \-\-history or \-\-cmd\-history)
reload(...)
select\-all
toggle
toggle\-all
toggle+down ctrl\-i (tab)
toggle\-in (\-\-layout=reverse* ? toggle+up : toggle+down)
toggle\-out (\-\-layout=reverse* ? toggle+down : toggle+up)
toggle\-preview
toggle\-preview\-wrap
toggle\-sort
toggle+up btab (shift\-tab)
unix\-line\-discard ctrl\-u
unix\-word\-rubout ctrl\-w
up ctrl\-k ctrl\-p up
yank ctrl\-y
\- ctrl\-[a\-z]
\- ctrl\-space
\- ctrl\-alt\-[a\-z]
\- alt\-[a\-zA\-Z]
\- alt\-[0\-9]
\- f[1\-12]
\- enter (ctrl\-m)
\- space
\- bspace (bs)
\- alt\-up
\- alt\-down
\- alt\-left
\- alt\-right
\- alt\-enter (alt\-ctrl\-m)
\- alt\-space
\- alt\-bspace (alt\-bs)
\- alt\-/
\- tab
\- btab (shift\-tab)
\- esc
\- del
\- up
\- down
\- left
\- right
\- home
\- end
\- pgup (page\-up)
\- pgdn (page\-down)
\- shift\-up
\- shift\-down
\- shift\-left
\- shift\-right
\- alt\-shift\-up
\- alt\-shift\-down
\- alt\-shift\-left
\- alt\-shift\-right
\- any single character
ACTION: DEFAULT BINDINGS [NOTES]
\- abort: ctrl\-c ctrl\-q esc
\- accept(...): enter the argument will be printed when the binding is triggered
\- append\-and\-select:
\- backward\-char: ctrl\-b left
\- backward\-delete\-char: ctrl\-h bspace
\- backward\-kill\-word: alt\-bs
\- backward\-word: alt\-b shift\-left
\- beginning\-of\-line: ctrl\-a home
\- clear\-screen: ctrl\-l
\- delete\-char: del
\- delete\-charEOF: ctrl\-d
\- deselect\-all:
\- down: ctrl\-j ctrl\-n down
\- end\-of\-line: ctrl\-e end
\- execute(...): see below for the details
\- execute\-silent(...): see below for the details
\- forward\-char: ctrl\-f right
\- forward\-word: alt\-f shift\-right
\- if\-non\-matched:
\- if\-query\-empty:
\- if\-query\-not\-empty:
\- ignore:
\- kill\-line:
\- kill\-word: alt\-d
\- next\-history: ctrl\-n with \-\-history or \-\-cmd\-history
\- page\-down: pgdn
\- page\-up: pgup
\- half\-page\-down:
\- half\-page\-up:
\- preview\-up: shift\-up
\- preview\-down: shift\-down
\- preview\-left:
\- preview\-right:
\- preview\-page\-down:
\- preview\-page\-up:
\- previous\-history: ctrl\-p with \-\-history or \-\-cmd\-history
\- reload(...):
\- select\-all:
\- toggle:
\- toggle\-all:
\- toggle+down: ctrl\-i tab
\- toggle\-in: (\-\-layout=reverse ? toggle+up: toggle+down)
\- toggle\-out: (\-\-layout=reverse ? toggle+down: toggle+up)
\- toggle\-preview:
\- toggle\-preview\-wrap:
\- toggle\-sort:
\- toggle+up: btab shift\-tab
\- unix\-line\-discard: ctrl\-u
\- unix\-word\-rubout: ctrl\-w
\- up: ctrl\-k ctrl\-p up
\- yank: ctrl\-y
Multiple actions can be chained using + separator.
sk \-\-bind \*(Aqctrl\-a:select\-all+accept\*(Aq
Example: sk \-\-bind \*(Aqctrl\-a:select\-all+accept\*(Aq
With execute(...) and reload(...) action, you can execute arbitrary commands without leaving sk. For example,
you can turn sk into a simple file browser by binding enter key to less command like follows.
Special behaviors
With execute(...) and reload(...) action, you can execute arbitrary commands without leaving sk. For example, you can turn sk into a simple file browser by binding enter key to less command like follows:
sk \-\-bind "enter:execute(less {})"
sk \-\-bind "enter:execute(less {})"
Note: if no argument is supplied to reload, the default command is run.
You can use the same placeholder expressions as in \-\-preview.
If the command contains parentheses, sk may fail to parse the expression. In that case, you can
use any of the following alternative notations to avoid parse errors.
If the command contains parentheses, sk may fail to parse the expression. In that case, you can use any of the following alternative notations to avoid parse errors.
execute[...]
execute\*(Aq...\*(Aq
execute"..."
execute:...
This is the special form that frees you from parse errors as it does not expect the clos‐
ing character. The catch is that it should be the last one in the comma\-separated list of
key\-action pairs.
\- execute[...]
sk switches to the alternate screen when executing a command. However, if the command is ex‐
pected to complete quickly, and you are not interested in its output, you might want to use exe‐
cute\-silent instead, which silently executes the command without the switching. Note that sk
will not be responsive until the command is complete. For asynchronous execution, start your
command as a background process (i.e. appending &).
\- execute\*(Aq...\*(Aq
With if\-query\-empty and if\-query\-not\-empty action, you could specify the action to execute de‐
pends on the query condition. For example
\- execute"..."
sk \-\-bind \*(Aqctrl\-d:if\-query\-empty(abort)+delete\-char\*(Aq
\- execute:...
If the query is empty, skim will execute abort action, otherwise execute delete\-char action. It
is equal to ‘delete\-char/eof‘.
This is the special form that frees you from parse errors as it does not expect the clos‐ ing character. The catch is that it should be the last one in the comma\-separated list of key\-action pairs.
sk switches to the alternate screen when executing a command. However, if the command is ex‐ pected to complete quickly, and you are not interested in its output, you might want to use exe‐ cute\-silent instead, which silently executes the command without the switching. Note that sk will not be responsive until the command is complete. For asynchronous execution, start your command as a background process (i.e. appending &).
With if\-query\-empty and if\-query\-not\-empty action, you could specify the action to execute de‐ pends on the query condition. For example:
sk \-\-bind \*(Aqctrl\-d:if\-query\-empty(abort)+delete\-char\*(Aq
If the query is empty, skim will execute abort action, otherwise execute delete\-char action. It is equal to ‘delete\-char/eof‘.
.TP
\fB\-m\fR, \fB\-\-multi\fR
Enable multiple selection
@ -302,7 +400,7 @@ Disable mouse
\fB\-c\fR, \fB\-\-cmd\fR=\fICMD\fR
Command to invoke dynamically in interactive mode
Will be invoked using `sh \-c`
Will be invoked using sh \-c
.TP
\fB\-i\fR, \fB\-\-interactive\fR
Run in interactive mode
@ -326,20 +424,16 @@ Effective only when the query string is empty
\fB\-\-skip\-to\-pattern\fR=\fISKIP_TO_PATTERN\fR
Show the matched pattern at the line start
Line will start with the start of the matched pattern. Effective only when the query
string is empty. Was designed to skip showing starts of paths of rg/grep results.
Line will start with the start of the matched pattern. Effective only when the query string is empty. Was designed to skip showing starts of paths of rg/grep results.
e.g. sk \-i \-c "rg {} \-\-color=always" \-\-skip\-to\-pattern \*(Aq[^/]*:\*(Aq \-\-ansi
Example: sk \-i \-c "rg {} \-\-color=always" \-\-skip\-to\-pattern \*(Aq[^/]*:\*(Aq \-\-ansi
.TP
\fB\-\-no\-clear\-if\-empty\fR
Do not clear previous line if the command returns an empty result
Do not clear previous items if new command returns empty result. This might be useful to
reduce flickering when typing new commands and the half\-complete commands are not valid.
Do not clear previous items if new command returns empty result. This might be useful to reduce flickering when typing new commands and the half\-complete commands are not valid.
This is not default however because similar usecases for grep and rg had already been op‐
timized where empty result of a query do mean "empty" and previous results should be
cleared.
This is not default however because similar usecases for grep and rg had already been op‐ timized where empty result of a query do mean "empty" and previous results should be cleared.
.TP
\fB\-\-no\-clear\-start\fR
Do not clear items on start
@ -356,9 +450,11 @@ Show error message if command fails
\fB\-\-layout\fR=\fILAYOUT\fR [default: default]
Set layout
default Display from the bottom of the screen
reverse Display from the top of the screen
reverse\-list Display from the top of the screen, prompt at the bottom
*default: Display from the bottom of the screen
*reverse: Display from the top of the screen
*reverse\-list: Display from the top of the screen, prompt at the bottom
.br
.br
@ -379,17 +475,24 @@ Disable height feature
Minimum height of skim\*(Aqs window
Useful when the height is set as a percentage
Ignored when \-\-height is not specified
.TP
\fB\-\-margin\fR=\fIMARGIN\fR [default: 0]
Screen margin
For each side, can be either a row count or a percentage of the terminal size
Format can be one of:
\- TRBL
\- TB,RL
\- T,RL,B
\- T,R,B,L
\- TRBL
\- TB,RL
\- T,RL,B
\- T,R,B,L
Example: 1,10%
.TP
\fB\-p\fR, \fB\-\-prompt\fR=\fIPROMPT\fR [default: > ]
@ -408,7 +511,9 @@ Number of spaces that make up a tab
\fB\-\-info\fR=\fIINFO\fR [default: default]
Set matching result count display position
hidden: do not display info inline: display info in the same row as the input default: display info in a dedicated row above the input
\- hidden: do not display info
\- inline: display info in the same row as the input
\- default: display info in a dedicated row above the input
.br
.br
@ -436,17 +541,20 @@ Run in a tmux popup
Format: sk \-\-tmux <center|top|bottom|left|right>[,SIZE[%]][,SIZE[%]]
Depending on the direction, the order and behavior of the sizes varies:
\- center: (width, height) or (size, size) if only one is provided
\- top | bottom: (height, width) or height = size, width = 100% if only one is provided
\- left | right: (width, height) or height = 100%, width = size if only one is provided
Default: center,50%
\- center: (width, height) or (size, size) if only one is provided
\- top | bottom: (height, width) or height = size, width = 100% if only one is provided
\- left | right: (width, height) or height = 100%, width = size if only one is provided
.SH HISTORY
.TP
\fB\-\-history\fR=\fIHISTORY_FILE\fR
History file
Load search history from the specified file and update the file on completion. When enabled, CTRL\-N and CTRL\-P are automatically remapped to next\-history and previous\-history.
Load search history from the specified file and update the file on completion.
When enabled, CTRL\-N and CTRL\-P are automatically remapped to next\-history and previous\-history.
.TP
\fB\-\-history\-size\fR=\fIHISTORY_SIZE\fR [default: 1000]
Maximum number of query history entries to keep
@ -454,7 +562,9 @@ Maximum number of query history entries to keep
\fB\-\-cmd\-history\fR=\fICMD_HISTORY_FILE\fR
Command history file
Load command query history from the specified file and update the file on completion. When enabled, CTRL\-N and CTRL\-P are automatically remapped to next\-history and previous\-history.
Load command query history from the specified file and update the file on completion.
When enabled, CTRL\-N and CTRL\-P are automatically remapped to next\-history and previous\-history.
.TP
\fB\-\-cmd\-history\-size\fR=\fICMD_HISTORY_SIZE\fR [default: 1000]
Maximum number of query history entries to keep
@ -463,45 +573,56 @@ Maximum number of query history entries to keep
\fB\-\-preview\fR=\fIPREVIEW\fR
Preview command
Execute the given command for the current line and display the result on the preview window. {} in the command
is the placeholder that is replaced to the single\-quoted string of the current line. To transform the replace‐
ment string, specify field index expressions between the braces (See FIELD INDEX EXPRESSION for the details).
Execute the given command for the current line and display the result on the preview window. {} in the command is the placeholder that is replaced to the single\-quoted string of the current line. To transform the replace‐ ment string, specify field index expressions between the braces (See FIELD INDEX EXPRESSION for the details).
e.g. sk \-\-preview=\*(Aqhead \-$LINES {}\*(Aq
ls \-l | sk \-\-preview="echo user={3} when={\-4..\-2}; cat {\-1}" \-\-header\-lines=1
Examples:
sk \-\-preview=\*(Aqhead \-$LINES {}\*(Aq
ls \-l | sk \-\-preview="echo user={3} when={\-4..\-2}; cat {\-1}" \-\-header\-lines=1
sk overrides $LINES and $COLUMNS so that they represent the exact size of the preview window.
A placeholder expression starting with + flag will be replaced to the space\-separated list of the selected
lines (or the current line if no selection was made) individually quoted.
A placeholder expression starting with + flag will be replaced to the space\-separated list of the selected lines (or the current line if no selection was made) individually quoted.
e.g.
sk \-\-multi \-\-preview=\*(Aqhead \-10 {+}\*(Aq
git log \-\-oneline | sk \-\-multi \-\-preview \*(Aqgit show {+1}\*(Aq
Examples:
sk \-\-multi \-\-preview=\*(Aqhead \-10 {+}\*(Aq
git log \-\-oneline | sk \-\-multi \-\-preview \*(Aqgit show {+1}\*(Aq
Note that you can escape a placeholder pattern by prepending a backslash.
Also, {q} is replaced to the current query string. {cq} is replaced to the current command query string. {n}
is replaced to zero\-based ordinal index of the line. Use {+n} if you want all index numbers when multiple
lines are selected
Also, {q} is replaced to the current query string. {cq} is replaced to the current command query string. {n} is replaced to zero\-based ordinal index of the line. Use {+n} if you want all index numbers when multiple lines are selected
Preview window will be updated even when there is no match for the current query if any of the placeholder ex‐
pressions evaluates to a non\-empty string.
Preview window will be updated even when there is no match for the current query if any of the placeholder ex‐ pressions evaluates to a non\-empty string.
.TP
\fB\-\-preview\-window\fR=\fIPREVIEW_WINDOW\fR [default: right:50%]
Preview window layout
Format: [up|down|left|right][:SIZE[%]][:hidden][:+SCROLL[\-OFFSET]] Determine the layout of the preview window. If the argument ends with :hidden, the preview window will be hidden by default until toggle\-preview action is triggered. Long lines are truncated by default. Line wrap can be enabled with :wrap flag.
Format: [up|down|left|right][:SIZE[%]][:hidden][:+SCROLL[\-OFFSET]]
Determine the layout of the preview window. If the argument ends with: hidden, the preview window will be hidden by default until toggle\-preview action is triggered. Long lines are truncated by default. Line wrap can be enabled with : wrap flag.
If size is given as 0, preview window will not be visible, but sk will still execute the command in the background.
+SCROLL[\-OFFSET] determines the initial scroll offset of the preview window. SCROLL can be either a numeric integer or a single\-field index expression that refers to a numeric integer. The optional \-OFFSET part is for adjusting the base offset so that you can see the text above it. It should be given as a numeric integer (\-INTEGER), or as a denom‐ inator form (\-/INTEGER) for specifying a fraction of the preview window height.
e.g. # Non\-default scroll window positions and sizes sk \-\-preview="head {}" \-\-preview\-window=up:30% sk \-\-preview="file {}" \-\-preview\-window=down:2
Examples:
# Initial scroll offset is set to the line number of each line of # git grep output *minus* 5 lines (\-5) git grep \-\-line\-number \*(Aq\*(Aq | sk \-\-delimiter : \-\-preview \*(Aqnl {1}\*(Aq \-\-preview\-window +{2}\-5
# Non\-default scroll window positions and sizes
sk \-\-preview="head {}" \-\-preview\-window=up:30%
sk \-\-preview="file {}" \-\-preview\-window=down:2
# Initial scroll offset is set to the line number of each line of
# git grep output *minus* 5 lines (\-5)
git grep \-\-line\-number \*(Aq\*(Aq |
sk \-\-delimiter: \-\-preview \*(Aqnl {1}\*(Aq \-\-preview\-window +{2}\-5
# Preview with bat, matching line in the middle of the window (\-/2)
git grep \-\-line\-number \*(Aq\*(Aq |
sk \-\-delimiter: \\
\-\-preview \*(Aqbat \-\-style=numbers \-\-color=always \-\-highlight\-line {2} {1}\*(Aq \\
\-\-preview\-window +{2}\-/2
# Preview with bat, matching line in the middle of the window (\-/2) git grep \-\-line\-number \*(Aq\*(Aq | sk \-\-delimiter : \\ \-\-preview \*(Aqbat \-\-style=numbers \-\-color=always \-\-highlight\-line {2} {1}\*(Aq \\ \-\-preview\-window +{2}\-/2
.SH SCRIPTING
.TP
\fB\-q\fR, \fB\-\-query\fR=\fIQUERY\fR
@ -515,13 +636,13 @@ Comma separated list of keys used to complete skim
Comma\-separated list of keys that can be used to complete sk in addition to the default enter key. When this option is set, sk will print the name of the key pressed as the first line of its output (or as the second line if \-\-print\-query is also used). The line will be empty if sk is completed with the default enter key. If \-\-expect option is specified multiple times, sk will expect the union of the keys. \-\-no\-expect will clear the list.
e.g. sk \-\-expect=ctrl\-v,ctrl\-t,alt\-s \-\-expect=f1,f2,~,@
Example: sk \-\-expect=ctrl\-v,ctrl\-t,alt\-s \-\-expect=f1,f2,~,@
.TP
\fB\-\-read0\fR
Read input delimited by ASCII NUL(\\\\0) characters
Read input delimited by ASCII NUL(\\0) characters
.TP
\fB\-\-print0\fR
Print output delimited by ASCII NUL(\\\\0) characters
Print output delimited by ASCII NUL(\\0) characters
.TP
\fB\-\-print\-query\fR
Print the query as the first line
@ -543,7 +664,7 @@ Synchronous search for multi\-staged filtering
Synchronous search for multi\-staged filtering. If specified, skim will launch ncurses finder only after the input stream is complete.
e.g. sk \-\-multi | sk \-\-sync
Example: sk \-\-multi | sk \-\-sync
.TP
\fB\-\-pre\-select\-n\fR=\fIPRE_SELECT_N\fR [default: 0]
Pre\-select the first n items in multi\-selection mode
@ -556,7 +677,7 @@ Check the doc for the detailed syntax: https://docs.rs/regex/1.4.1/regex/
\fB\-\-pre\-select\-items\fR=\fIPRE_SELECT_ITEMS\fR [default: ]
Pre\-select the items separated by newline character
Exemple: \*(Aqitem1\\nitem2\*(Aq
Example: item1\\nitem2
.TP
\fB\-\-pre\-select\-file\fR=\fIPRE_SELECT_FILE\fR
Pre\-select the items read from this file

8
shell/completion.zsh
View file

@ -15,8 +15,8 @@ _sk() {
local context curcontext="$curcontext" state line
_arguments "${_arguments_options[@]}" : \
'*-t+[Comma-separated list of sort criteria to apply when the scores are tied.]:TIEBREAK:(score -score begin -begin end -end length -length index -index)' \
'*--tiebreak=[Comma-separated list of sort criteria to apply when the scores are tied.]:TIEBREAK:(score -score begin -begin end -end length -length index -index)' \
'*-t+[Comma-separated list of sort criteria to apply when the scores are tied]:TIEBREAK:(score -score begin -begin end -end length -length index -index)' \
'*--tiebreak=[Comma-separated list of sort criteria to apply when the scores are tied]:TIEBREAK:(score -score begin -begin end -end length -length index -index)' \
'*-n+[Fields to be matched]:NTH:_default' \
'*--nth=[Fields to be matched]:NTH:_default' \
'*--with-nth=[Fields to be transformed]:WITH_NTH:_default' \
@ -83,8 +83,8 @@ _sk() {
'--ansi[Parse ANSI color codes in input strings]' \
'--no-info[Alias for --info=hidden]' \
'--inline-info[Alias for --info=inline]' \
'--read0[Read input delimited by ASCII NUL(\\\\0) characters]' \
'--print0[Print output delimited by ASCII NUL(\\\\0) characters]' \
'--read0[Read input delimited by ASCII NUL(\\0) characters]' \
'--print0[Print output delimited by ASCII NUL(\\0) characters]' \
'--print-query[Print the query as the first line]' \
'--print-cmd[Print the command as the first line (after print-query)]' \
'--print-score[Print the command as the first line (after print-cmd)]' \

3
skim/Cargo.toml
View file

@ -14,7 +14,6 @@ edition = "2021"
[lib]
name = "skim"
path = "src/lib.rs"
doctest = false
[[bin]]
name = "sk"
@ -28,7 +27,7 @@ unicode-width = "0.2.0"
log = "0.4.25"
env_logger = { version = "0.11.6", optional = true }
time = "0.3.13"
clap = { version = "4.5.27", optional = true, features = ["cargo", "derive"] }
clap = { version = "4.5.30", optional = true, features = ["cargo", "derive", "unstable-markdown"] }
tuikit = "0.5.0"
vte = "0.15.0"
fuzzy-matcher = "0.3.7"

605
skim/src/options.rs
View file

@ -17,121 +17,135 @@ use crate::{CaseMatching, FuzzyAlgorithm, Selector};
/// sk is a general purpose command-line fuzzy finder.
///
///
/// ENVIRONMENT VARIABLES
/// # ENVIRONMENT VARIABLES
///
/// SKIM_DEFAULT_COMMAND
/// ## SKIM_DEFAULT_COMMAND
///
/// Default command to use when input is tty. On *nix systems, sk runs the command with sh -c, so make sure that
/// it's POSIX-compliant.
/// Default command to use when input is tty. On *nix systems, sk runs the command with sh -c, so make sure that
/// it's POSIX-compliant.
///
/// SKIM_DEFAULT_OPTIONS
/// ## SKIM_DEFAULT_OPTIONS
///
/// Default options. e.g. export SKIM_DEFAULT_OPTIONS="--multi
/// Default options. e.g. `export SKIM_DEFAULT_OPTIONS="--multi"`
///
/// EXTENDED SEARCH MODE
/// # EXTENDED SEARCH MODE
///
/// Unless specified otherwise, sk will start in "extended-search mode". In this mode, you can specify multiple patterns
/// delimited by spaces, such as: 'wild ^music .mp3$ sbtrkt !rmx
/// Unless specified otherwise, sk will start in "extended-search mode". In this mode, you can specify multiple patterns
/// delimited by spaces, such as: 'wild ^music .mp3$ sbtrkt !rmx
///
/// You can prepend a backslash to a space (\ ) to match a literal space character.
/// You can prepend a backslash to a space (\ ) to match a literal space character.
///
/// Exact-match (quoted)
/// ## Exact-match (quoted)
///
/// A term that is prefixed by a single-quote character (') is interpreted as an "exact-match" (or "non-fuzzy") term. sk
/// will search for the exact occurrences of the string.
/// A term that is prefixed by a single-quote character (') is interpreted as an "exact-match" (or "non-fuzzy") term. sk
/// will search for the exact occurrences of the string.
///
/// Anchored-match
/// ## Anchored-match
///
/// A term can be prefixed by ^, or suffixed by $ to become an anchored-match term. Then sk will search for the lines
/// that start with or end with the given string. An anchored-match term is also an exact-match term.
/// A term can be prefixed by ^, or suffixed by $ to become an anchored-match term. Then sk will search for the lines
/// that start with or end with the given string. An anchored-match term is also an exact-match term.
///
/// Negation
/// ## Negation
///
/// If a term is prefixed by !, sk will exclude the lines that satisfy the term from the result. In this case, sk per‐
/// forms exact match by default.
/// If a term is prefixed by !, sk will exclude the lines that satisfy the term from the result. In this case, `sk` per‐
/// forms exact match by default.
///
/// Exact-match by default
/// ## Exact-match by default
///
/// If you don't prefer fuzzy matching and do not wish to "quote" (prefixing with ') every word, start sk with -e or
/// --exact option. Note that when --exact is set, '-prefix "unquotes" the term.
/// If you don't prefer fuzzy matching and do not wish to "quote" (prefixing with ') every word,
/// start `sk` with `-e` or
/// `--exact` option. Note that when `--exact` is set, '-prefix "unquotes" the term.
///
/// OR operator
/// ## OR operator
///
/// A single bar character term acts as an OR operator. For example, the following query matches entries that start with
/// core and end with either go, rb, or py.
///
/// e.g. ^core go$ | rb$ | py$
/// A single bar character term acts as an OR operator. For example, the following query matches entries that start with
/// core and end with either go, rb, or py.
///
///
/// EXIT STATUS
/// 0 Normal exit
/// 1 No match
/// 2 Error
/// 130 Interrupted with CTRL-C or ESC
/// **Example**: `^core go$ | rb$ | py$`
///
///
/// # EXIT STATUS
///
/// * 0: Normal exit
///
/// * 1: No match
///
/// * 2: Error
///
/// * 130: Interrupted with CTRL-C or ESC
#[derive(Builder)]
#[builder(build_fn(name = "final_build"))]
#[builder(default)]
#[derive(Parser)]
#[command(name = "sk", args_override_self = true, verbatim_doc_comment, version)]
#[command(name = "sk", args_override_self = true, version)]
pub struct SkimOptions {
// --- Search ---
/// Show results in reverse order
///
/// Often used in combination with --no-sort
/// *Often used in combination with `--no-sort`*
#[arg(long, help_heading = "Search")]
pub tac: bool,
/// Do not sort the results
///
/// Often used in combination with --tac
/// Example: `history | sk --tac --no-sort`
/// *Often used in combination with `--tac`*
///
/// **Example**: `history | sk --tac --no-sort`
#[arg(long, help_heading = "Search")]
pub no_sort: bool,
/// Comma-separated list of sort criteria to apply when the scores are tied.
///
/// score Score of the fuzzy match algorithm
/// index Prefers line that appeared earlier in the input stream
/// begin Prefers line with matched substring closer to the beginning
/// end Prefers line with matched substring closer to the end
/// length Prefers line with shorter length
/// * **score**: Score of the fuzzy match algorithm
///
/// - Each criterion could be negated, e.g. (-index)
/// - Each criterion should appear only once in the list
/// * **index**: Prefers line that appeared earlier in the input stream
///
/// * **begin**: Prefers line with matched substring closer to the beginning
///
/// * **end**: Prefers line with matched substring closer to the end
///
/// * **length**: Prefers line with shorter length
///
/// Notes:
///
/// * Each criterion could be negated, e.g. (-index)
///
/// * Each criterion should appear only once in the list
#[arg(
short,
long,
default_value = "score,begin,end",
value_enum,
value_delimiter = ',',
help_heading = "Search",
verbatim_doc_comment
help_heading = "Search"
)]
pub tiebreak: Vec<RankCriteria>,
/// Fields to be matched
///
/// A field index expression can be a non-zero integer or a range expression ([BEGIN]..[END]). --nth
/// and --with-nth take a comma-separated list of field index expressions.
/// A field index expression can be a non-zero integer or a range expression (`[BEGIN]..[END]`).
/// `--nth` and `--with-nth` take a comma-separated list of field index expressions.
///
/// **Examples:**
/// 1 The 1st field
/// 2 The 2nd field
/// -1 The last field
/// -2 The 2nd to last field
/// 3..5 From the 3rd field to the 5th field
/// 2.. From the 2nd field to the last field
/// ..-3 From the 1st field to the 3rd to the last field
/// .. All the fields
#[arg(
short,
long,
default_value = "",
help_heading = "Search",
verbatim_doc_comment,
value_delimiter = ','
)]
/// **Examples**:
///
/// * `1`: The 1st field
///
/// * `2`: The 2nd field
///
/// * `-1`: The last field
///
/// * `-2`: The 2nd to last field
///
/// * `3..5`: From the 3rd field to the 5th field
///
/// * `2..`: From the 2nd field to the last field
///
/// * `..-3`: From the 1st field to the 3rd to the last field
///
/// * `..`: All the fields
#[arg(short, long, default_value = "", help_heading = "Search", value_delimiter = ',')]
pub nth: Vec<String>,
/// Fields to be transformed
@ -156,16 +170,12 @@ pub struct SkimOptions {
/// Fuzzy matching algorithm
///
/// skim_v2 Latest skim algorithm, should be better in almost any case
/// skim_v1 Legacy skim algorithm
/// clangd Used in clangd for keyword completion
#[arg(
long = "algo",
default_value = "skim_v2",
value_enum,
help_heading = "Search",
verbatim_doc_comment
)]
/// * **skim_v2**: Latest skim algorithm, should be better in almost any case
///
/// * **skim_v1**: Legacy skim algorithm
///
/// * **clangd**: Used in clangd for keyword completion
#[arg(long = "algo", default_value = "skim_v2", value_enum, help_heading = "Search")]
pub algorithm: FuzzyAlgorithm,
/// Case sensitivity
@ -177,112 +187,206 @@ pub struct SkimOptions {
// --- Interface ---
/// Comma separated list of bindings
///
/// You can customize key bindings of sk with --bind option which takes a comma-separated list of
/// key binding expressions. Each key binding expression follows the following format: KEY:ACTION
/// You can customize key bindings of sk with `--bind` option which takes a comma-separated list of
/// key binding expressions. Each key binding expression follows the following format: `<key>:<action>`
///
/// e.g. sk --bind=ctrl-j:accept,ctrl-k:kill-line
/// **Example**: `sk --bind=ctrl-j:accept,ctrl-k:kill-line`
///
/// AVAILABLE KEYS: (SYNONYMS)
/// ctrl-[a-z]
/// ctrl-space
/// ctrl-alt-[a-z]
/// alt-[a-zA-Z]
/// alt-[0-9]
/// f[1-12]
/// enter (ctrl-m)
/// space
/// bspace (bs)
/// alt-up
/// alt-down
/// alt-left
/// alt-right
/// alt-enter (alt-ctrl-m)
/// alt-space
/// alt-bspace (alt-bs)
/// alt-/
/// tab
/// btab (shift-tab)
/// esc
/// del
/// up
/// down
/// left
/// right
/// home
/// end
/// pgup (page-up)
/// pgdn (page-down)
/// shift-up
/// shift-down
/// shift-left
/// shift-right
/// alt-shift-up
/// alt-shift-down
/// alt-shift-left
/// alt-shift-right
/// or any single character
/// ## AVAILABLE KEYS: (SYNONYMS)
///
/// ACTION: DEFAULT BINDINGS (NOTES):
/// abort ctrl-c ctrl-q esc
/// accept(...) enter (the argument will be printed when the binding is triggered)
/// append-and-select
/// backward-char ctrl-b left
/// backward-delete-char ctrl-h bspace
/// backward-kill-word alt-bs
/// backward-word alt-b shift-left
/// beginning-of-line ctrl-a home
/// clear-screen ctrl-l
/// delete-char del
/// delete-charEOF ctrl-d
/// deselect-all
/// down ctrl-j ctrl-n down
/// end-of-line ctrl-e end
/// execute(...) (see below for the details)
/// execute-silent(...) (see below for the details)
/// forward-char ctrl-f right
/// forward-word alt-f shift-right
/// if-non-matched
/// if-query-empty
/// if-query-not-empty
/// ignore
/// kill-line
/// kill-word alt-d
/// next-history (ctrl-n on --history or --cmd-history)
/// page-down pgdn
/// page-up pgup
/// half-page-down
/// half-page-up
/// preview-up shift-up
/// preview-down shift-down
/// preview-left
/// preview-right
/// preview-page-down
/// preview-page-up
/// previous-history (ctrl-p on --history or --cmd-history)
/// reload(...)
/// select-all
/// toggle
/// toggle-all
/// toggle+down ctrl-i (tab)
/// toggle-in (--layout=reverse* ? toggle+up : toggle+down)
/// toggle-out (--layout=reverse* ? toggle+down : toggle+up)
/// toggle-preview
/// toggle-preview-wrap
/// toggle-sort
/// toggle+up btab (shift-tab)
/// unix-line-discard ctrl-u
/// unix-word-rubout ctrl-w
/// up ctrl-k ctrl-p up
/// yank ctrl-y
/// * ctrl-[a-z]
///
/// Multiple actions can be chained using + separator.
/// * ctrl-space
///
/// sk --bind 'ctrl-a:select-all+accept'
/// * ctrl-alt-[a-z]
///
/// With execute(...) and reload(...) action, you can execute arbitrary commands without leaving sk. For example,
/// you can turn sk into a simple file browser by binding enter key to less command like follows.
/// * alt-[a-zA-Z]
///
/// * alt-[0-9]
///
/// * f[1-12]
///
/// * enter (ctrl-m)
///
/// * space
///
/// * bspace (bs)
///
/// * alt-up
///
/// * alt-down
///
/// * alt-left
///
/// * alt-right
///
/// * alt-enter (alt-ctrl-m)
///
/// * alt-space
///
/// * alt-bspace (alt-bs)
///
/// * alt-/
///
/// * tab
///
/// * btab (shift-tab)
///
/// * esc
///
/// * del
///
/// * up
///
/// * down
///
/// * left
///
/// * right
///
/// * home
///
/// * end
///
/// * pgup (page-up)
///
/// * pgdn (page-down)
///
/// * shift-up
///
/// * shift-down
///
/// * shift-left
///
/// * shift-right
///
/// * alt-shift-up
///
/// * alt-shift-down
///
/// * alt-shift-left
///
/// * alt-shift-right
///
/// * any single character
///
/// ## ACTION: DEFAULT BINDINGS [NOTES]
///
/// * abort: ctrl-c ctrl-q esc
///
/// * accept(...): enter *the argument will be printed when the binding is triggered*
///
/// * append-and-select:
///
/// * backward-char: ctrl-b left
///
/// * backward-delete-char: ctrl-h bspace
///
/// * backward-kill-word: alt-bs
///
/// * backward-word: alt-b shift-left
///
/// * beginning-of-line: ctrl-a home
///
/// * clear-screen: ctrl-l
///
/// * delete-char: del
///
/// * delete-charEOF: ctrl-d
///
/// * deselect-all:
///
/// * down: ctrl-j ctrl-n down
///
/// * end-of-line: ctrl-e end
///
/// * execute(...): *see below for the details*
///
/// * execute-silent(...): *see below for the details*
///
/// * forward-char: ctrl-f right
///
/// * forward-word: alt-f shift-right
///
/// * if-non-matched:
///
/// * if-query-empty:
///
/// * if-query-not-empty:
///
/// * ignore:
///
/// * kill-line:
///
/// * kill-word: alt-d
///
/// * next-history: ctrl-n with `--history` or `--cmd-history`
///
/// * page-down: pgdn
///
/// * page-up: pgup
///
/// * half-page-down:
///
/// * half-page-up:
///
/// * preview-up: shift-up
///
/// * preview-down: shift-down
///
/// * preview-left:
///
/// * preview-right:
///
/// * preview-page-down:
///
/// * preview-page-up:
///
/// * previous-history: ctrl-p with `--history` or `--cmd-history`
///
/// * reload(...):
///
/// * select-all:
///
/// * toggle:
///
/// * toggle-all:
///
/// * toggle+down: ctrl-i tab
///
/// * toggle-in: (--layout=reverse ? toggle+up: toggle+down)
///
/// * toggle-out: (--layout=reverse ? toggle+down: toggle+up)
///
/// * toggle-preview:
///
/// * toggle-preview-wrap:
///
/// * toggle-sort:
///
/// * toggle+up: btab shift-tab
///
/// * unix-line-discard: ctrl-u
///
/// * unix-word-rubout: ctrl-w
///
/// * up: ctrl-k ctrl-p up
///
/// * yank: ctrl-y
///
/// ## Multiple actions can be chained using + separator.
///
/// **Example**: `sk --bind 'ctrl-a:select-all+accept'`
///
/// # Special behaviors
///
/// With `execute(...)` and `reload(...)` action, you can execute arbitrary commands without leaving sk.
/// For example, you can turn sk into a simple file browser by binding enter key to less command like follows:
///
/// ```bash
/// sk --bind "enter:execute(less {})"
/// ```
///
/// sk --bind "enter:execute(less {})"
/// Note: if no argument is supplied to reload, the default command is run.
///
/// You can use the same placeholder expressions as in --preview.
@ -290,13 +394,17 @@ pub struct SkimOptions {
/// If the command contains parentheses, sk may fail to parse the expression. In that case, you can
/// use any of the following alternative notations to avoid parse errors.
///
/// execute[...]
/// execute'...'
/// execute"..."
/// execute:...
/// This is the special form that frees you from parse errors as it does not expect the clos‐
/// ing character. The catch is that it should be the last one in the comma-separated list of
/// key-action pairs.
/// * `execute[...]`
///
/// * `execute'...'`
///
/// * `execute"..."`
///
/// * `execute:...`
///
/// This is the special form that frees you from parse errors as it does not expect the clos‐
/// ing character. The catch is that it should be the last one in the comma-separated list of
/// key-action pairs.
///
/// sk switches to the alternate screen when executing a command. However, if the command is ex‐
/// pected to complete quickly, and you are not interested in its output, you might want to use exe‐
@ -305,13 +413,13 @@ pub struct SkimOptions {
/// command as a background process (i.e. appending &).
///
/// With if-query-empty and if-query-not-empty action, you could specify the action to execute de‐
/// pends on the query condition. For example
/// pends on the query condition. For example:
///
/// sk --bind 'ctrl-d:if-query-empty(abort)+delete-char'
/// `sk --bind 'ctrl-d:if-query-empty(abort)+delete-char'`
///
/// If the query is empty, skim will execute abort action, otherwise execute delete-char action. It
/// is equal to ‘delete-char/eof‘.
#[arg(short, long, help_heading = "Interface", verbatim_doc_comment, value_delimiter = ',')]
#[arg(short, long, help_heading = "Interface", value_delimiter = ',')]
pub bind: Vec<String>,
/// Enable multiple selection
@ -363,8 +471,8 @@ pub struct SkimOptions {
/// Line will start with the start of the matched pattern. Effective only when the query
/// string is empty. Was designed to skip showing starts of paths of rg/grep results.
///
/// e.g. sk -i -c "rg {} --color=always" --skip-to-pattern '[^/]*:' --ansi
#[arg(long, help_heading = "Interface", verbatim_doc_comment)]
/// **Example**: `sk -i -c "rg {} --color=always" --skip-to-pattern '[^/]*:' --ansi`
#[arg(long, help_heading = "Interface")]
pub skip_to_pattern: Option<String>,
/// Do not clear previous line if the command returns an empty result
@ -375,7 +483,7 @@ pub struct SkimOptions {
/// This is not default however because similar usecases for grep and rg had already been op‐
/// timized where empty result of a query do mean "empty" and previous results should be
/// cleared.
#[arg(long, help_heading = "Interface", verbatim_doc_comment)]
#[arg(long, help_heading = "Interface")]
pub no_clear_if_empty: bool,
/// Do not clear items on start
@ -397,9 +505,11 @@ pub struct SkimOptions {
// --- Layout ---
/// Set layout
///
/// default Display from the bottom of the screen
/// reverse Display from the top of the screen
/// reverse-list Display from the top of the screen, prompt at the bottom
/// *default: Display from the bottom of the screen
///
/// *reverse: Display from the top of the screen
///
/// *reverse-list: Display from the top of the screen, prompt at the bottom
#[arg(
long,
default_value = "default",
@ -407,7 +517,6 @@ pub struct SkimOptions {
["default", "reverse", "reverse-list"]
),
help_heading = "Layout",
verbatim_doc_comment
)]
pub layout: String,
@ -428,20 +537,27 @@ pub struct SkimOptions {
/// Minimum height of skim's window
///
/// Useful when the height is set as a percentage
/// Ignored when --height is not specified
#[arg(long, default_value = "10", help_heading = "Layout", verbatim_doc_comment)]
///
/// Ignored when `--height` is not specified
#[arg(long, default_value = "10", help_heading = "Layout")]
pub min_height: String,
/// Screen margin
///
/// For each side, can be either a row count or a percentage of the terminal size
///
/// Format can be one of:
/// - TRBL
/// - TB,RL
/// - T,RL,B
/// - T,R,B,L
/// Example: 1,10%
#[arg(long, default_value = "0", help_heading = "Layout", verbatim_doc_comment)]
///
/// * TRBL
///
/// * TB,RL
///
/// * T,RL,B
///
/// * T,R,B,L
///
/// **Example**: 1,10%
#[arg(long, default_value = "0", help_heading = "Layout")]
pub margin: String,
/// Set prompt
@ -463,9 +579,9 @@ pub struct SkimOptions {
/// Set matching result count display position
///
/// hidden: do not display info
/// inline: display info in the same row as the input
/// default: display info in a dedicated row above the input
/// * hidden: do not display info
/// * inline: display info in the same row as the input
/// * default: display info in a dedicated row above the input
#[arg(long, help_heading = "Display", value_enum, default_value = "default")]
pub info: InfoDisplay,
@ -480,14 +596,14 @@ pub struct SkimOptions {
/// Set header, displayed next to the info
///
/// The given string will be printed as the sticky header. The lines are displayed in the
/// given order from top to bottom regardless of --layout option, and are not affected by
/// --with-nth. ANSI color codes are processed even when --ansi is not set.
/// given order from top to bottom regardless of `--layout` option, and are not affected by
/// `--with-nth`. ANSI color codes are processed even when `--ansi` is not set.
#[arg(long, help_heading = "Display")]
pub header: Option<String>,
/// Number of lines of the input treated as header
///
/// The first N lines of the input are treated as the sticky header. When --with-nth is set,
/// The first N lines of the input are treated as the sticky header. When `--with-nth` is set,
/// the lines are transformed just like the other lines that follow.
#[arg(long, default_value = "0", help_heading = "Display")]
pub header_lines: usize,
@ -496,6 +612,7 @@ pub struct SkimOptions {
/// History file
///
/// Load search history from the specified file and update the file on completion.
///
/// When enabled, CTRL-N and CTRL-P are automatically remapped
/// to next-history and previous-history.
#[arg(long = "history", help_heading = "History")]
@ -508,6 +625,7 @@ pub struct SkimOptions {
/// Command history file
///
/// Load command query history from the specified file and update the file on completion.
///
/// When enabled, CTRL-N and CTRL-P are automatically remapped
/// to next-history and previous-history.
#[arg(long = "cmd-history", help_heading = "History")]
@ -524,35 +642,42 @@ pub struct SkimOptions {
/// is the placeholder that is replaced to the single-quoted string of the current line. To transform the replace‐
/// ment string, specify field index expressions between the braces (See FIELD INDEX EXPRESSION for the details).
///
/// e.g. sk --preview='head -$LINES {}'
/// ls -l | sk --preview="echo user={3} when={-4..-2}; cat {-1}" --header-lines=1
/// **Examples**:
///
/// ```bash
/// sk --preview='head -$LINES {}'
/// ls -l | sk --preview="echo user={3} when={-4..-2}; cat {-1}" --header-lines=1
/// ```
///
/// sk overrides $LINES and $COLUMNS so that they represent the exact size of the preview window.
///
/// A placeholder expression starting with + flag will be replaced to the space-separated list of the selected
/// lines (or the current line if no selection was made) individually quoted.
///
/// e.g.
/// sk --multi --preview='head -10 {+}'
/// git log --oneline | sk --multi --preview 'git show {+1}'
/// **Examples**:
/// ```bash
/// sk --multi --preview='head -10 {+}'
/// git log --oneline | sk --multi --preview 'git show {+1}'
/// ```
///
/// Note that you can escape a placeholder pattern by prepending a backslash.
///
/// Also, {q} is replaced to the current query string. {cq} is replaced to the current command query string. {n}
/// is replaced to zero-based ordinal index of the line. Use {+n} if you want all index numbers when multiple
/// Also, `{q}` is replaced to the current query string. `{cq}` is replaced to the current command query string.
/// `{n}` is replaced to zero-based ordinal index of the line. Use `{+n}` if you want all index numbers when multiple
/// lines are selected
///
/// Preview window will be updated even when there is no match for the current query if any of the placeholder ex‐
/// pressions evaluates to a non-empty string.
#[arg(long, help_heading = "Preview", verbatim_doc_comment)]
#[arg(long, help_heading = "Preview")]
pub preview: Option<String>,
/// Preview window layout
///
/// Format: [up|down|left|right][:SIZE[%]][:hidden][:+SCROLL[-OFFSET]]
/// Determine the layout of the preview window. If the argument ends with :hidden, the preview window will be hidden by
///
/// Determine the layout of the preview window. If the argument ends with: hidden, the preview window will be hidden by
/// default until toggle-preview action is triggered. Long lines are truncated by default. Line wrap can be enabled with
/// :wrap flag.
///: wrap flag.
///
/// If size is given as 0, preview window will not be visible, but sk will still execute the command in the background.
///
@ -561,21 +686,23 @@ pub struct SkimOptions {
/// base offset so that you can see the text above it. It should be given as a numeric integer (-INTEGER), or as a denom‐
/// inator form (-/INTEGER) for specifying a fraction of the preview window height.
///
/// e.g.
/// # Non-default scroll window positions and sizes
/// sk --preview="head {}" --preview-window=up:30%
/// sk --preview="file {}" --preview-window=down:2
/// **Examples**:
/// ```bash
/// # Non-default scroll window positions and sizes
/// sk --preview="head {}" --preview-window=up:30%
/// sk --preview="file {}" --preview-window=down:2
///
/// # Initial scroll offset is set to the line number of each line of
/// # git grep output *minus* 5 lines (-5)
/// git grep --line-number '' |
/// sk --delimiter : --preview 'nl {1}' --preview-window +{2}-5
/// # Initial scroll offset is set to the line number of each line of
/// # git grep output *minus* 5 lines (-5)
/// git grep --line-number '' |
/// sk --delimiter: --preview 'nl {1}' --preview-window +{2}-5
///
/// # Preview with bat, matching line in the middle of the window (-/2)
/// git grep --line-number '' |
/// sk --delimiter : \
/// --preview 'bat --style=numbers --color=always --highlight-line {2} {1}' \
/// --preview-window +{2}-/2
/// # Preview with bat, matching line in the middle of the window (-/2)
/// git grep --line-number '' |
/// sk --delimiter: \
/// --preview 'bat --style=numbers --color=always --highlight-line {2} {1}' \
/// --preview-window +{2}-/2
/// ```
#[arg(long, default_value = "right:50%", help_heading = "Preview")]
pub preview_window: String,
@ -596,7 +723,7 @@ pub struct SkimOptions {
/// --expect option is specified multiple times, sk will expect the union of the keys. --no-expect will clear the
/// list.
///
/// e.g. sk --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
/// **Example**: `sk --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@`
#[arg(long, help_heading = "Scripting", value_delimiter = ',')]
pub expect: Vec<String>,
@ -633,7 +760,7 @@ pub struct SkimOptions {
/// Synchronous search for multi-staged filtering. If specified,
/// skim will launch ncurses finder only after the input stream is complete.
///
/// e.g. sk --multi | sk --sync
/// **Example**: `sk --multi | sk --sync`
#[arg(long, help_heading = "Scripting")]
pub sync: bool,
@ -650,7 +777,7 @@ pub struct SkimOptions {
/// Pre-select the items separated by newline character
///
/// Exemple: 'item1\nitem2'
/// **Example**: `item1\nitem2`
#[arg(long, default_value = "", help_heading = "Scripting")]
pub pre_select_items: String,
@ -664,15 +791,16 @@ pub struct SkimOptions {
/// Run in a tmux popup
///
/// Format: sk --tmux <center|top|bottom|left|right>[,SIZE[%]][,SIZE[%]]
/// Format: `sk --tmux <center|top|bottom|left|right>[,SIZE[%]][,SIZE[%]]`
///
/// Depending on the direction, the order and behavior of the sizes varies:
/// - center: (width, height) or (size, size) if only one is provided
/// - top | bottom: (height, width) or height = size, width = 100% if only one is provided
/// - left | right: (width, height) or height = 100%, width = size if only one is provided
///
/// Default: center,50%
#[arg(long, verbatim_doc_comment, help_heading = "Display", default_missing_value = "center,50%", num_args=0..)]
/// * center: (width, height) or (size, size) if only one is provided
///
/// * top | bottom: (height, width) or height = size, width = 100% if only one is provided
///
/// * left | right: (width, height) or height = 100%, width = size if only one is provided
#[arg(long, help_heading = "Display", default_missing_value = "center,50%", num_args=0..)]
pub tmux: Option<String>,
/// Reserved for later use
@ -734,9 +862,10 @@ pub struct SkimOptions {
pub selector: Option<Rc<dyn Selector>>,
/// Preview Callback
///
/// Used to define a function or closure for the preview window, instead of a shell command
/// Used to define a function or closure for the preview window, instead of a shell command.
///
/// The function will take a `Vec<Arc<dyn SkimItem>>>` containing the currently selected items
/// And return a Vec<String> with the lines to display in UTF-8
/// and return a Vec<String> with the lines to display in UTF-8
#[clap(skip)]
pub preview_fn: Option<PreviewCallback>,
}

2
xtask/Cargo.toml
View file

@ -4,7 +4,7 @@ version = "0.1.1"
edition = "2021"
[dependencies]
clap = { version = "4.5.27", features = ["derive"] }
clap = { version = "4.5.30", features = ["derive", "unstable-markdown"] }
clap_complete = "4.5.45"
clap_complete_fig = "4.5.2"
clap_complete_nushell = "4.5.5"