Showing 126 of 307 total issues
Line length Open
You can find the detailed instructions on setting up Github sign in [here](doc/sso/GITHUB.md) in case you are interested in.
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Line length Open
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Line length Open
| [Stable Dependencies Principle](https://api.short-d.com/r/sdp) | Depend in the direction of stability. |
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Bare URL used Open
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
- Read upRead up
- Exclude checks
MD034 - Bare URL used
Tags: links, url
Aliases: no-bare-urls
This rule is triggered whenever a URL is given that isn't surrounded by angle brackets:
For more information, see http://www.example.com/.
To fix this, add angle brackets around the URL:
For more information, see <http:></http:>.
Rationale: Without angle brackets, the URL isn't converted into a link in many markdown parsers.
Note: if you do want a bare URL without it being converted into a link, enclose it in a code block, otherwise in some markdown parsers it will be converted:
`http://www.example.com`
Line length Open
| [Dependency Inversion Principle](https://api.short-d.com/r/dip) | Depend on abstractions, not on concretions. |
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Line length Open
where people together plan the product roadmap for Short, write design docs, build complex systems, create libraries, invent
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Headers should be surrounded by blank lines Open
## Joining the Core Team
- Read upRead up
- Exclude checks
MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
Aliases: blanks-around-headers
This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.
Lists should be surrounded by blank lines Open
- You make things happen independently. Not dreaming or talking about them. You deliver them all the way onto production!
- Read upRead up
- Exclude checks
MD032 - Lists should be surrounded by blank lines
Tags: bullet, ul, ol, blank_lines
Aliases: blanks-around-lists
This rule is triggered when lists (of any kind) are either not preceded or not followed by a blank line:
Some text
* Some
* List
1. Some
2. List
Some text
To fix this, ensure that all lists have a blank line both before and after (except where the block is at the beginning or end of the document):
Some text
* Some
* List
1. Some
2. List
Some text
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse lists that don't have blank lines before and after them.
Note: List items without hanging indents are a violation of this rule; list items with hanging indents are okay:
* This is
not okay
* This is
okay
Line length Open
| [The Common Reuse Principle](https://api.short-d.com/r/crp) | Classes that are used together are packaged together. |
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Line length Open
You can find the differences between continuous delivery & continuous deployment [here](doc/tutorial/CI-CD.md)
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Headers should be surrounded by blank lines Open
### macOS
- Read upRead up
- Exclude checks
MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
Aliases: blanks-around-headers
This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.
Headers should be surrounded by blank lines Open
## GUI Client
- Read upRead up
- Exclude checks
MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
Aliases: blanks-around-headers
This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.
Headers should be surrounded by blank lines Open
# Configure Facebook Sign In
- Read upRead up
- Exclude checks
MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
Aliases: blanks-around-headers
This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.
Double quote to prevent globbing and word splitting. Open
(echo >/dev/tcp/$WAITFORIT_HOST/$WAITFORIT_PORT) >/dev/null 2>&1
- Read upRead up
- Exclude checks
Double quote to prevent globbing and word splitting.
Problematic code:
echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done
Correct code:
echo "$1"
for i in "$@"; do :; done # or, 'for i; do'
Rationale
The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."
The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.
Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.
Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:
$HOME/$dir/dist/bin/$file # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file" # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file" # Canonical quoting (good)
When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c"
will not expand, but "$HOME/$dir/src"/*.c
will.
Note that $( )
starts a new context, and variables in it have to be quoted independently:
echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"
Exceptions
Sometimes you want to split on spaces, like when building a command line:
options="-j 5 -B"
make $options file
Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):
options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file
or a function (POSIX):
make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file
To split on spaces but not perform glob expansion, Posix has a set -f
to disable globbing. You can disable word splitting by setting IFS=''
.
Similarly, you might want an optional argument:
debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script
Quoting this doesn't work, since in the default case, "$debug"
would expand to one empty argument while $debug
would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:
debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script
This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}
.
As always, this warning can be [[ignore]]d on a case-by-case basis.
this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...
FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir
Notice
Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.
Double quote to prevent globbing and word splitting. Open
timeout $WAITFORIT_BUSYTIMEFLAG $WAITFORIT_TIMEOUT $0 --child --host=$WAITFORIT_HOST --port=$WAITFORIT_PORT --timeout=$WAITFORIT_TIMEOUT &
- Read upRead up
- Exclude checks
Double quote to prevent globbing and word splitting.
Problematic code:
echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done
Correct code:
echo "$1"
for i in "$@"; do :; done # or, 'for i; do'
Rationale
The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."
The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.
Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.
Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:
$HOME/$dir/dist/bin/$file # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file" # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file" # Canonical quoting (good)
When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c"
will not expand, but "$HOME/$dir/src"/*.c
will.
Note that $( )
starts a new context, and variables in it have to be quoted independently:
echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"
Exceptions
Sometimes you want to split on spaces, like when building a command line:
options="-j 5 -B"
make $options file
Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):
options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file
or a function (POSIX):
make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file
To split on spaces but not perform glob expansion, Posix has a set -f
to disable globbing. You can disable word splitting by setting IFS=''
.
Similarly, you might want an optional argument:
debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script
Quoting this doesn't work, since in the default case, "$debug"
would expand to one empty argument while $debug
would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:
debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script
This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}
.
As always, this warning can be [[ignore]]d on a case-by-case basis.
this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...
FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir
Notice
Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.
Trailing spaces Open
- You thrive in complexities & difficulties. Compilers, operating systems, programming languages, bitwise optimizations,
- Read upRead up
- Exclude checks
MD009 - Trailing spaces
Tags: whitespace
Aliases: no-trailing-spaces
Parameters: br_spaces (number; default: 0)
This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.
The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.
Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.
Headers should be surrounded by blank lines Open
# Contributing
- Read upRead up
- Exclude checks
MD022 - Headers should be surrounded by blank lines
Tags: headers, blank_lines
Aliases: blanks-around-headers
This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:
# Header 1
Some text
Some more text
## Header 2
To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):
# Header 1
Some text
Some more text
## Header 2
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.
Trailing spaces Open
production environment.
- Read upRead up
- Exclude checks
MD009 - Trailing spaces
Tags: whitespace
Aliases: no-trailing-spaces
Parameters: br_spaces (number; default: 0)
This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.
The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.
Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.
Line length Open
| [Release Reuse Equivalency Principle](https://api.short-d.com/r/rep) | The granule of reuse is the granule of release. |
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.
Line length Open
| [The Common Closure Principle](https://api.short-d.com/r/ccp) | Classes that change together are packaged together. |
- Read upRead up
- Exclude checks
MD013 - Line length
Tags: line_length
Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)
This rule is triggered when there are lines that are longer than the configured line length (default: 80 characters). To fix this, split the line up into multiple lines.
This rule has an exception where there is no whitespace beyond the configured line length. This allows you to still include items such as long URLs without being forced to break them in the middle.
You also have the option to exclude this rule for code blocks and tables. To
do this, set the code_blocks
and/or tables
parameters to false.
Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines.