--- Makefile (Revision 471352) +++ Makefile (Arbeitskopie) @@ -19,5 +19,10 @@ EXECUTABLE= shellcheck +PLIST_FILES+= man/man1/shellcheck.1.gz + +post-stage: + ${INSTALL_MAN} ${FILESDIR}/shellcheck.1 ${STAGEDIR}${MANPREFIX}/man/man1/ + .include "${.CURDIR}/../../lang/ghc/bsd.cabal.mk" .include --- files/shellcheck.1 (nicht existent) +++ files/shellcheck.1 (Arbeitskopie) @@ -0,0 +1,277 @@ +.Dd May 15, 2018 +.Dt SHELLCHECK 1 +.Os +.Sh NAME +.Nm shellcheck +.Nd Shell script analysis tool +.Sh SYNOPSIS +.Nm +.Op Fl avx, +.Op Fl C Ar when +.Op Fl e Ar code1,code2 +.Op Fl f Ar format +.Op Fl s Ar shell +.Sh DESCRIPTION +.Nm +is a static analysis and linting tool for sh/bash scripts. +It is mainly focused on handling typical beginner and intermediate +level syntax errors and pitfalls where the shell just gives a cryptic +error message or strange behavior, but it also reports on a few more +advanced issues where corner cases can cause delayed failures. +.Pp +.Nm +gives shell specific advice. +Consider this line: +.Bd -literal -offset indent +(( area = 3.14*r*r )) +.Ed +.Pp +For scripts starting with +.Li #!/bin/sh +(or when using +.Fl s Cm sh ) , +.Nm +will warn that +.Li ((\ ..\ )) +is not POSIX compliant (similar to +.Li checkbashisms ) . +.Pp +For scripts starting with +.Li #!/bin/bash +(or using +.Fl s Cm bash ) , +.Nm +will warn that decimals are not supported. +.Pp +For scripts starting with +.Li #!/bin/ksh +(or using +.Fl s Cm ksh ) , +.nm +will not warn at all, as +.Li ksh +supports decimals in arithmetic contexts. +.Sh OPTIONS +The following options are available: +.Bl -tag -width indent +.It Fl a , -check-sourced +Emit warnings in sourced files. +Normally, +.Nm +will only warn about issues in the specified files. +With this option, any issues in sourced files will also be reported. +.It Fl C Ar when , Fl -color Ns = Ns Ar when +For TTY output, enable colors with when one of +.Li always , +.Li never , +or +.Li auto . +The default is +.Li auto . +.Ar -color +without an argument is equivalent to +.Ar -color=always . +.It Fl e Ar code1,code2 , Fl -exclude Ns = Ns Ar code1,code2 +Explicitly exclude the specified codes from the report. +Subsequent +.Fl e +options are cumulative, but all the codes can be +specified at once, comma\-separated as a single argument. +.It Fl f Ar format , Fl -format Ns = Ns Ar format +Specify the output format of +.Nm , +which prints its results in the +standard output. +Subsequent +.Fl f +options are ignored, see +.Rx FORMATS +below for more information. +.It Fl s Ar shell , Fl -shell Ns = Ns Ar shell +Specify Bourne shell dialect. +Valid values are +.Ar sh , bash , dash , +and +.Ar ksh . +The default is to use the file's shebang, or +.Ar bash +if the target shell cannot be determined. +.It Fl V , Fl -version +Print version information and exit. +.It Fl x , Fl -external-sources +Follow +.Li source +statements even when the file is not specified as input. +By default, +.Nm +will only follow files specified on the command line (plus +.Pa /dev/null ) . +This option allows following any file the script may +.Li source . +.El +.Sh FORMATS +.Bl -tag -width indent +.It tty +Plain text, human readable output. +This is the default. +.It gcc +GCC compatible output. +Useful for editors that support compiling and showing syntax errors. +.Pp +For example, in +.Li vim , +.Li :set makeprg=shellcheck -f gcc % +will allow using +.Li :make +to check the script, and +.Li :cnext +to jump to the next error. +.Bd -literal -offset indent +:::\ :\ +.Ed +.It checkstyle +Checkstyle compatible XML output. +Supported directly or through plugins by many IDEs and build monitoring +systems. +.Bd -literal -offset indent + + + + + ... + + ... + +.Ed +.It json +Json is a popular serialization format that is more suitable for web +applications. +.Nm Ns 's +json is compact and contains only the bare minimum. +.Bd -literal -offset indent +[ + { + "file": "filename", + "line": lineNumber, + "column": columnNumber, + "level": "severitylevel", + "code": errorCode, + "message": "warning message" + }, + ... +] +.Sh DIRECTIVES +.Nm +directives can be specified as comments in the shell script +before a command or block: +.Bd -literal -offset indent +# shellcheck key=value key=value +command-or-structure +.Ed + +For example, to suppress SC2035 about using +.Li ./*.jpg : +.Bd -literal -offset indent +# shellcheck disable=SC2035 +echo "Files: " *.jpg +.Ed + +To tell +.Nm +where to look for an otherwise dynamically determined +file: +.Bd .Bd -literal -offset indent +# shellcheck\ source=./lib.sh +source "$(find_install_dir)/lib.sh" +.Ed + +Here a shell brace group is used to suppress a warning on multiple +lines: +.Bd -literal -offset indent +# shellcheck\ disable=SC2016 +{ + echo "Modifying $PATH" + echo "PATH=foo:$PATH" >> ~/.bashrc +} +.Ed +.El +Valid keys are: +.Bl -tag -width indent +.It disable +Disables a comma separated list of error codes for the following +command. +The command can be a simple command like +.Li echo , +or a compound command like a function definition, subshell block or loop. +.It source +Overrides the filename included by a +.Li source +statement. +This can be used to tell +.Nm +where to look for a file whose name +is determined at runtime, or to skip a source by telling it to use +.Pa /dev/null . +.It shell +Overrides the shell detected from the shebang. +This is useful for files meant to be included (and thus lacking a +shebang), or possibly as a more targeted alternative to +.Li "disable=2039" . +.Sh ENVIRONMENT VARIABLES +The environment variable +.Ev SHELLCHECK_OPTS +can be set with default flags: +.Bd -literal -offset indent +export SHELLCHECK_OPTS="--shell=bash --exclude=SC2016" +.Ed + +Its value will be split on spaces and prepended to the command line on +each invocation. +.El +.Sh EXIT STATUS +.Nm +uses the follow exit codes: +.Bl -tag -width indent +.It 0 : +All files successfully scanned with no issues. +.It 1 : +All files successfully scanned with some issues. +.It 2 : +Some files could not be processed (e.g., file not found). +.It 3 : +.Nm +was invoked with bad syntax (e.g., unknown flag). +.It 4 : +.Nm +was invoked with bad options (e.g., unknown formatter). +.El +.Sh LOCALE +This version of +.Nm +is only available in English. +All files are leniently decoded as UTF\-8, with a fallback of +ISO\-8859\-1 for invalid sequences. +.Ev LC_CTYPE +is respected for output, and defaults to UTF\-8 for locales where encoding +is unspecified (such as the +.Li C +locale). +.Sh AUTHOR +.Nm +is written and maintained by Vidar Holen. +.Sh REPORTING BUGS +Bugs and issues can be reported on GitHub: +.Pp +.Lk https://github.com/koalaman/shellcheck/issues +.Sh COPYRIGHT +Copyright 2012\-2015, Vidar Holen. +Licensed under the GNU General Public License version 3 or later, see +http://gnu.org/licenses/gpl.html +.Sh SEE ALSO +.Xr bash 1 , +.Xr sh 1