michael/lf
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update doc

Browse Source 
Related #505
This commit is contained in:
Gokcehan 2020-12-27 03:27:33 +03:00
parent 3b78309b89
commit 72567c9237
3 changed files with 363 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
doc.go
View File

@ -1183,38 +1183,135 @@ You can add an extra call to make it run on startup as well:
Note that all shell commands are possible but `%` and `&` are usually more appropriate as `$` and `!` causes flickers and pauses respectively. Note that all shell commands are possible but `%` and `&` are usually more appropriate as `$` and `!` causes flickers and pauses respectively.
Colorschemes Colors
lf tries to automatically adapt its colors to the environment. lf tries to automatically adapt its colors to the environment.
On startup, first '$LS_COLORS' environment variable is checked. It starts with a default colorscheme and updates colors using values of existing environment variables possibly by overwriting its previous values.
This variable is used by GNU ls to configure its colors based on file types and extensions. Colors are set in the following order:
The value of this variable is often set by GNU dircolors in a shell configuration file.
dircolors program itself can be configured with a configuration file.
dircolors supports 256 colors along with common attributes such as bold and underline.
If '$LS_COLORS' variable is not set, '$LSCOLORS' variable is checked instead. 1. default
This variable is used by ls programs on unix systems such as Mac and BSDs. 2. LSCOLORS (Mac/BSD ls)
This variable has a simple syntax and supports 8 colors and bold attribute. 3. LS_COLORS (GNU ls)
4. LF_COLORS (lf specific)
If both of these environment variables are not set, then lf fallbacks to its default colorscheme. Please refer to the corresponding man pages for more information about 'LSCOLORS' and 'LS_COLORS'.
Default lf colors are taken from GNU dircolors defaults. 'LF_COLORS' is provided with the same syntax as 'LS_COLORS' in case you want to configure colors only for lf but not ls.
These defaults use 8 basic colors and bold attribute. This can be useful since there are some differences between ls and lf, though one should expect the same behavior for common cases.
It is worth noting that lf uses as many colors are advertised by your terminal's entry in your systems terminfo or infocmp database, if this is not present lf will default to an internal database. You can configure lf colors in two different ways.
For terminals supporting 24-bit (or "true") color that do not have a database entry (or one that does not advertise all capabilities), support can be enabled by either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM' is set to a value that ends with "-truecolor". First, you can only configure 8 basic colors used by your terminal and lf should pick up those colors automatically.
Keeping this in mind, you can configure lf colors in two different ways.
First, you can configure 8 basic colors used by your terminal and lf should pick up those colors automatically.
Depending on your terminal, you should be able to select your colors from a 24-bit palette. Depending on your terminal, you should be able to select your colors from a 24-bit palette.
This is the recommended approach as colors used by other programs will also match each other. This is the recommended approach as colors used by other programs will also match each other.
Second, you can set the values of environmental variables mentioned above for fine grained customization. Second, you can set the values of environmental variables mentioned above for fine grained customization.
This is useful to change colors used for different file types and extensions. Note that 'LS_COLORS/LF_COLORS' are more powerful than 'LSCOLORS' and they can be used even when GNU programs are not installed on the system.
'$LS_COLORS' is more powerful than '$LSCOLORS' and it can be used even when GNU programs are not installed on the system.
You can combine this second method with the first method for best results. You can combine this second method with the first method for best results.
Lastly, you may also want to configure the colors of the prompt line to match the rest of the colors. Lastly, you may also want to configure the colors of the prompt line to match the rest of the colors.
Colors of the prompt line can be configured using the 'promptfmt' option which can include hardcoded colors as ansi escapes. Colors of the prompt line can be configured using the 'promptfmt' option which can include hardcoded colors as ansi escapes.
See the default value of this option to have an idea about how to color this line. See the default value of this option to have an idea about how to color this line.
It is worth noting that lf uses as many colors are advertised by your terminal's entry in your systems terminfo or infocmp database, if this is not present lf will default to an internal database.
For terminals supporting 24-bit (or "true") color that do not have a database entry (or one that does not advertise all capabilities), support can be enabled by either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM' is set to a value that ends with "-truecolor".
Default lf colors are mostly taken from GNU dircolors defaults.
These defaults use 8 basic colors and bold attribute.
Default dircolors entries with background colors are simplified to avoid confusion with current file selection in lf.
Similarly, there are only file type matchings and extension matchings are left out for simplicity.
Default values are as follows given with their matching order in lf:
ln 01;36
or 31;01
tw 01;34
ow 01;34
st 01;34
di 01;34
pi 33
so 01;35
bd 33;01
cd 33;01
su 01;32
sg 01;32
ex 01;32
fi 00
Note that, lf first tries matching file names and then falls back to file types.
The full order of matchings from most specific to least are as follows:
1. Full Path (e.g. '~/.config/lf/lfrc')
2. Dir Name (e.g. '.git/') (only matches dirs with a trailing slash at the end)
3. File Name (e.g. '.git')
4. Base Name (e.g. 'README.*')
5. Extension (e.g. '*.txt')
6. File Type (e.g. 'ln')
For example, given a regular text file '/path/to/README.txt', the following entries are checked in the configuration and the first one to match is used:
1. '/path/to/README.txt'
2. 'README.txt/' (skipped since the file is not a directory)
3. 'README.txt'
4. 'README.*'
5. '*.txt'
6. 'fi'
Note that glob-like patterns do not actually perform glob matching due to performance reasons.
For example, you can set a variable as follows:
export LF_COLORS="~/Documents=01;31:~/Downloads=01;31:~/.local/share=01;31:~/.config/lf/lfrc=31:.git/=01;32:.git=32:.gitignore=32:Makefile=32:README.*=33:*.txt=34:*.md=34:ln=01;36:di=01;34:ex=01;32:"
Having all entries on a single line can make it hard to read.
You may instead divide it to multiple lines in between double quotes by escaping newlines with backslashes as follows:
export LF_COLORS="\
~/Documents=01;31:\
~/Downloads=01;31:\
~/.local/share=01;31:\
~/.config/lf/lfrc=31:\
.git/=01;32:\
.git=32:\
.gitignore=32:\
Makefile=32:\
README.*=33:\
*.txt=34:\
*.md=34:\
ln=01;36:\
di=01;34:\
ex=01;32:\
"
Having such a long variable definition in a shell configuration file might be undesirable.
You may instead put this definition in a separate file and source it in your shell configuration file as follows:
[ -f "/path/to/colors" ] && source "/path/to/colors"
See the wiki page for ansi escape codes
https://en.wikipedia.org/wiki/ANSI_escape_code.
Icons
Icons are configured using 'LF_ICONS' environment variable.
This variable uses the same syntax as 'LS_COLORS/LF_COLORS'.
Instead of colors, you should put a single characters as values of entries.
Do not forget to enable 'icons' option to see the icons.
Default values are as follows given with their matching order in lf:
ln 🗎
or 🗎
tw 🗀
ow 🗀
st 🗀
di 🗀
pi 🗎
so 🗎
bd 🗎
cd 🗎
su 🗎
sg 🗎
ex 🗎
fi 🗎
See the wiki page for an example icons configuration
https://github.com/gokcehan/lf/wiki/Icons.
*/ */
package main package main

167
docstring.go
View File

@ -1327,24 +1327,41 @@ Note that all shell commands are possible but '%' and '&' are usually more
appropriate as '$' and '!' causes flickers and pauses respectively. appropriate as '$' and '!' causes flickers and pauses respectively.
Colorschemes Colors
lf tries to automatically adapt its colors to the environment. On startup, lf tries to automatically adapt its colors to the environment. It starts
first '$LS_COLORS' environment variable is checked. This variable is used by with a default colorscheme and updates colors using values of existing
GNU ls to configure its colors based on file types and extensions. The value environment variables possibly by overwriting its previous values. Colors
of this variable is often set by GNU dircolors in a shell configuration are set in the following order:
file. dircolors program itself can be configured with a configuration file.
dircolors supports 256 colors along with common attributes such as bold and
underline.
If '$LS_COLORS' variable is not set, '$LSCOLORS' variable is checked 1. default
instead. This variable is used by ls programs on unix systems such as Mac 2. LSCOLORS (Mac/BSD ls)
and BSDs. This variable has a simple syntax and supports 8 colors and bold 3. LS_COLORS (GNU ls)
attribute. 4. LF_COLORS (lf specific)
If both of these environment variables are not set, then lf fallbacks to its Please refer to the corresponding man pages for more information about
default colorscheme. Default lf colors are taken from GNU dircolors 'LSCOLORS' and 'LS_COLORS'. 'LF_COLORS' is provided with the same syntax as
defaults. These defaults use 8 basic colors and bold attribute. 'LS_COLORS' in case you want to configure colors only for lf but not ls.
This can be useful since there are some differences between ls and lf,
though one should expect the same behavior for common cases.
You can configure lf colors in two different ways. First, you can only
configure 8 basic colors used by your terminal and lf should pick up those
colors automatically. Depending on your terminal, you should be able to
select your colors from a 24-bit palette. This is the recommended approach
as colors used by other programs will also match each other.
Second, you can set the values of environmental variables mentioned above
for fine grained customization. Note that 'LS_COLORS/LF_COLORS' are more
powerful than 'LSCOLORS' and they can be used even when GNU programs are not
installed on the system. You can combine this second method with the first
method for best results.
Lastly, you may also want to configure the colors of the prompt line to
match the rest of the colors. Colors of the prompt line can be configured
using the 'promptfmt' option which can include hardcoded colors as ansi
escapes. See the default value of this option to have an idea about how to
color this line.
It is worth noting that lf uses as many colors are advertised by your It is worth noting that lf uses as many colors are advertised by your
terminal's entry in your systems terminfo or infocmp database, if this is terminal's entry in your systems terminfo or infocmp database, if this is
@ -1354,22 +1371,110 @@ one that does not advertise all capabilities), support can be enabled by
either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM' either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM'
is set to a value that ends with "-truecolor". is set to a value that ends with "-truecolor".
Keeping this in mind, you can configure lf colors in two different ways. Default lf colors are mostly taken from GNU dircolors defaults. These
First, you can configure 8 basic colors used by your terminal and lf should defaults use 8 basic colors and bold attribute. Default dircolors entries
pick up those colors automatically. Depending on your terminal, you should with background colors are simplified to avoid confusion with current file
be able to select your colors from a 24-bit palette. This is the recommended selection in lf. Similarly, there are only file type matchings and extension
approach as colors used by other programs will also match each other. matchings are left out for simplicity. Default values are as follows given
with their matching order in lf:
Second, you can set the values of environmental variables mentioned above ln 01;36
for fine grained customization. This is useful to change colors used for or 31;01
different file types and extensions. '$LS_COLORS' is more powerful than tw 01;34
'$LSCOLORS' and it can be used even when GNU programs are not installed on ow 01;34
the system. You can combine this second method with the first method for st 01;34
best results. di 01;34
pi 33
so 01;35
bd 33;01
cd 33;01
su 01;32
sg 01;32
ex 01;32
fi 00
Lastly, you may also want to configure the colors of the prompt line to Note that, lf first tries matching file names and then falls back to file
match the rest of the colors. Colors of the prompt line can be configured types. The full order of matchings from most specific to least are as
using the 'promptfmt' option which can include hardcoded colors as ansi follows:
escapes. See the default value of this option to have an idea about how to
color this line. 1. Full Path (e.g. '~/.config/lf/lfrc')
2. Dir Name (e.g. '.git/') (only matches dirs with a trailing slash at the end)
3. File Name (e.g. '.git')
4. Base Name (e.g. 'README.*')
5. Extension (e.g. '*.txt')
6. File Type (e.g. 'ln')
For example, given a regular text file '/path/to/README.txt', the following
entries are checked in the configuration and the first one to match is used:
1. '/path/to/README.txt'
2. 'README.txt/' (skipped since the file is not a directory)
3. 'README.txt'
4. 'README.*'
5. '*.txt'
6. 'fi'
Note that glob-like patterns do not actually perform glob matching due to
performance reasons.
For example, you can set a variable as follows:
export LF_COLORS="~/Documents=01;31:~/Downloads=01;31:~/.local/share=01;31:~/.config/lf/lfrc=31:.git/=01;32:.git=32:.gitignore=32:Makefile=32:README.*=33:*.txt=34:*.md=34:ln=01;36:di=01;34:ex=01;32:"
Having all entries on a single line can make it hard to read. You may
instead divide it to multiple lines in between double quotes by escaping
newlines with backslashes as follows:
export LF_COLORS="\
~/Documents=01;31:\
~/Downloads=01;31:\
~/.local/share=01;31:\
~/.config/lf/lfrc=31:\
.git/=01;32:\
.git=32:\
.gitignore=32:\
Makefile=32:\
README.*=33:\
*.txt=34:\
*.md=34:\
ln=01;36:\
di=01;34:\
ex=01;32:\
"
Having such a long variable definition in a shell configuration file might
be undesirable. You may instead put this definition in a separate file and
source it in your shell configuration file as follows:
[ -f "/path/to/colors" ] && source "/path/to/colors"
See the wiki page for ansi escape codes
https://en.wikipedia.org/wiki/ANSI_escape_code.
Icons
Icons are configured using 'LF_ICONS' environment variable. This variable
uses the same syntax as 'LS_COLORS/LF_COLORS'. Instead of colors, you should
put a single characters as values of entries. Do not forget to enable
'icons' option to see the icons. Default values are as follows given with
their matching order in lf:
ln 🗎
or 🗎
tw 🗀
ow 🗀
st 🗀
di 🗀
pi 🗎
so 🗎
bd 🗎
cd 🗎
su 🗎
sg 🗎
ex 🗎
fi 🗎
See the wiki page for an example icons configuration
https://github.com/gokcehan/lf/wiki/Icons.
` `

118
lf.1
View File

@ -1297,17 +1297,121 @@ This command runs whenever you change directory but not on startup. You can add
.EE .EE
.PP .PP
Note that all shell commands are possible but `%` and `&` are usually more appropriate as `$` and `!` causes flickers and pauses respectively. Note that all shell commands are possible but `%` and `&` are usually more appropriate as `$` and `!` causes flickers and pauses respectively.
.SH COLORSCHEMES .SH COLORS
lf tries to automatically adapt its colors to the environment. On startup, first '$LS_COLORS' environment variable is checked. This variable is used by GNU ls to configure its colors based on file types and extensions. The value of this variable is often set by GNU dircolors in a shell configuration file. dircolors program itself can be configured with a configuration file. dircolors supports 256 colors along with common attributes such as bold and underline. lf tries to automatically adapt its colors to the environment. It starts with a default colorscheme and updates colors using values of existing environment variables possibly by overwriting its previous values. Colors are set in the following order:
.PP .PP
If '$LS_COLORS' variable is not set, '$LSCOLORS' variable is checked instead. This variable is used by ls programs on unix systems such as Mac and BSDs. This variable has a simple syntax and supports 8 colors and bold attribute. .EX
1. default
2. LSCOLORS (Mac/BSD ls)
3. LS_COLORS (GNU ls)
4. LF_COLORS (lf specific)
.EE
.PP .PP
If both of these environment variables are not set, then lf fallbacks to its default colorscheme. Default lf colors are taken from GNU dircolors defaults. These defaults use 8 basic colors and bold attribute. Please refer to the corresponding man pages for more information about 'LSCOLORS' and 'LS_COLORS'. 'LF_COLORS' is provided with the same syntax as 'LS_COLORS' in case you want to configure colors only for lf but not ls. This can be useful since there are some differences between ls and lf, though one should expect the same behavior for common cases.
.PP
You can configure lf colors in two different ways. First, you can only configure 8 basic colors used by your terminal and lf should pick up those colors automatically. Depending on your terminal, you should be able to select your colors from a 24-bit palette. This is the recommended approach as colors used by other programs will also match each other.
.PP
Second, you can set the values of environmental variables mentioned above for fine grained customization. Note that 'LS_COLORS/LF_COLORS' are more powerful than 'LSCOLORS' and they can be used even when GNU programs are not installed on the system. You can combine this second method with the first method for best results.
.PP
Lastly, you may also want to configure the colors of the prompt line to match the rest of the colors. Colors of the prompt line can be configured using the 'promptfmt' option which can include hardcoded colors as ansi escapes. See the default value of this option to have an idea about how to color this line.
.PP .PP
It is worth noting that lf uses as many colors are advertised by your terminal's entry in your systems terminfo or infocmp database, if this is not present lf will default to an internal database. For terminals supporting 24-bit (or "true") color that do not have a database entry (or one that does not advertise all capabilities), support can be enabled by either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM' is set to a value that ends with "-truecolor". It is worth noting that lf uses as many colors are advertised by your terminal's entry in your systems terminfo or infocmp database, if this is not present lf will default to an internal database. For terminals supporting 24-bit (or "true") color that do not have a database entry (or one that does not advertise all capabilities), support can be enabled by either setting the '$COLORTERM' variable to "truecolor" or ensuring '$TERM' is set to a value that ends with "-truecolor".
.PP .PP
Keeping this in mind, you can configure lf colors in two different ways. First, you can configure 8 basic colors used by your terminal and lf should pick up those colors automatically. Depending on your terminal, you should be able to select your colors from a 24-bit palette. This is the recommended approach as colors used by other programs will also match each other. Default lf colors are mostly taken from GNU dircolors defaults. These defaults use 8 basic colors and bold attribute. Default dircolors entries with background colors are simplified to avoid confusion with current file selection in lf. Similarly, there are only file type matchings and extension matchings are left out for simplicity. Default values are as follows given with their matching order in lf:
.PP .PP
Second, you can set the values of environmental variables mentioned above for fine grained customization. This is useful to change colors used for different file types and extensions. '$LS_COLORS' is more powerful than '$LSCOLORS' and it can be used even when GNU programs are not installed on the system. You can combine this second method with the first method for best results. .EX
ln 01;36
or 31;01
tw 01;34
ow 01;34
st 01;34
di 01;34
pi 33
so 01;35
bd 33;01
cd 33;01
su 01;32
sg 01;32
ex 01;32
fi 00
.EE
.PP .PP
Lastly, you may also want to configure the colors of the prompt line to match the rest of the colors. Colors of the prompt line can be configured using the 'promptfmt' option which can include hardcoded colors as ansi escapes. See the default value of this option to have an idea about how to color this line. Note that, lf first tries matching file names and then falls back to file types. The full order of matchings from most specific to least are as follows:
.PP
.EX
1. Full Path (e.g. '~/.config/lf/lfrc')
2. Dir Name (e.g. '.git/') (only matches dirs with a trailing slash at the end)
3. File Name (e.g. '.git')
4. Base Name (e.g. 'README.*')
5. Extension (e.g. '*.txt')
6. File Type (e.g. 'ln')
.EE
.PP
For example, given a regular text file '/path/to/README.txt', the following entries are checked in the configuration and the first one to match is used:
.PP
.EX
1. '/path/to/README.txt'
2. 'README.txt/' (skipped since the file is not a directory)
3. 'README.txt'
4. 'README.*'
5. '*.txt'
6. 'fi'
.EE
.PP
Note that glob-like patterns do not actually perform glob matching due to performance reasons.
.PP
For example, you can set a variable as follows:
.PP
.EX
export LF_COLORS="~/Documents=01;31:~/Downloads=01;31:~/.local/share=01;31:~/.config/lf/lfrc=31:.git/=01;32:.git=32:.gitignore=32:Makefile=32:README.*=33:*.txt=34:*.md=34:ln=01;36:di=01;34:ex=01;32:"
.EE
.PP
Having all entries on a single line can make it hard to read. You may instead divide it to multiple lines in between double quotes by escaping newlines with backslashes as follows:
.PP
.EX
export LF_COLORS="\e
~/Documents=01;31:\e
~/Downloads=01;31:\e
~/.local/share=01;31:\e
~/.config/lf/lfrc=31:\e
.git/=01;32:\e
.git=32:\e
.gitignore=32:\e
Makefile=32:\e
README.*=33:\e
*.txt=34:\e
*.md=34:\e
ln=01;36:\e
di=01;34:\e
ex=01;32:\e
"
.EE
.PP
Having such a long variable definition in a shell configuration file might be undesirable. You may instead put this definition in a separate file and source it in your shell configuration file as follows:
.PP
.EX
[ -f "/path/to/colors" ] && source "/path/to/colors"
.EE
.PP
See the wiki page for ansi escape codes https://en.wikipedia.org/wiki/ANSI_escape_code.
.SH ICONS
Icons are configured using 'LF_ICONS' environment variable. This variable uses the same syntax as 'LS_COLORS/LF_COLORS'. Instead of colors, you should put a single characters as values of entries. Do not forget to enable 'icons' option to see the icons. Default values are as follows given with their matching order in lf:
.PP
.EX
ln 🗎
or 🗎
tw 🗀
ow 🗀
st 🗀
di 🗀
pi 🗎
so 🗎
bd 🗎
cd 🗎
su 🗎
sg 🗎
ex 🗎
fi 🗎
.EE
.PP
See the wiki page for an example icons configuration https://github.com/gokcehan/lf/wiki/Icons.