Configuration
Fortitude will look for either a fortitude.toml, .fortitude.toml,
fpm.toml, or pyproject.toml (in order of priority) file in the current
directory, or one of its parents.
For complete documentation of the available configuration options, see Settings.
If using fortitude.toml or .fortitude.toml, settings should be under the
command name, while for fpm.toml files, this has to be additionally nested
under the extra.fortitude table, or tool.fortitude for pyproject.toml:
Support for pyproject.toml introduced in Fortitude 0.8.1
Configuration file discovery
Fortitude uses Ruff's hierarchical config file discovery
strategy,
where we use the "closest" config file in the directory hierarchy for
each individual source file being checked, with all paths in the
config file (such as exclude) relative to the directory containing
that config file.
Configuration files do not inherit from or merge with parent
configuration files. For example, if a nested fortitude.toml is closer
to a source file than the root fortitude.toml, then rule selection
settings such as select and ignore are taken from the nested file,
not from the root file.
If a config file is passed on the command line using --config, those settings
are used for all files, and any relative paths in that config file are
resolved relative to the directory where fortitude is run.
Similarly, any other options set on the command line (for example,
--select) override those in all found config files.
If there is no configuration file in the current directory or its parents,
Fortitude will look in ${config_dir}/fortitude/ for a user-specific file (see
etcetera's base
strategy for how
${config_dir} is determined).
If no config file is found, Fortitude will fall back to a default configuration.
If multiple config files are found, .fortitude.toml takes precedence
over fortitude.toml, which takes precedence over fpm.toml, with
pyproject.toml having the lowest precedence.
Discovering files
Without any other arguments, fortitude check searches the current directory
recursively for Fortran files. You can also pass an explicit list of files or
directories to search, or control which files or directories should be excluded
from this search (see check.exclude and
check.extend-exclude):
Files in your .gitignore will be excluded from the file search automatically,
though this behaviour can be deactivated (see
check.respect-gitignore). Files in certain
directories (build/, .git/, .venv/, etc.) will also be excluded by
default. An additional comma-separated list of excluded files and directories
can be set using the check.extend-exclude option. For example,
to exclude all files in the directories benchmarks/ and tests/ in addition
to the default excluded files:
You can also use pattern matching with a glob (*) symbol:
Note that Fortitude will still check excluded files if you pass their paths
directly, so the following will still check the benchmarks/ directory:
Setting check.force-exclude to true will enforce
exclusions even in this scenario.
Default inclusions
By default, Fortitude will discover Fortran files with many common extensions,
including .f90, .F90, .f95. You can change the default selection using the
include setting:
Introduced in Fortitude 0.8.0
Fortitude currently supports free-form Fortran source. Fixed-form source files
such as .f, .for, or .ftn are not included by default, and adding them to
include will not make Fortitude parse them as fixed-form source. See the
FAQ for details.
Command-line interface
Some settings can be given or overidden explicitly on the command line, particularly those related to rule selection:
Settings on the command line always take precedence over those given in the configuration file.
The --config CLI flag
The --config flag has two uses. It is most often used to point to the
configuration file that you would like Fortitude to use, for example:
However, the --config flag can also be used to provide arbitrary
overrides of configuration settings using TOML <KEY> = <VALUE> pairs.
This is mostly useful in situations where you wish to override a configuration setting
that does not have a dedicated command-line flag.
In the below example, the --config flag is the only way of overriding the
use-statements.allow-bare-use configuration setting from the command line,
since this setting has no dedicated CLI flag. The per-file-ignores setting
could also have been overridden via the --per-file-ignores dedicated flag,
but using --config to override the setting is also fine:
$ fortitude check path/to/file --config path/to/fortitude.toml --config
"lint.use-statements.allow-bare-use = ['netcdf']" --config "lint.per-file-ignores = {'some_file.f90' = ['C001']}"
Configuration options passed to --config are parsed in the same way as
configuration options in a fortitude.toml file. As such, options specific to
the Fortitude linter need to be prefixed with check. (--config
"check.use-statements.allow-bare-use = ['netcdf']" rather than simply --config
"use-statements.allow-bare-use = ['netcdf']").
If a specific configuration option is simultaneously overridden by
a dedicated flag and by the --config flag, the dedicated flag
takes priority. In this example, the maximum permitted line length
will be set to 90, not 100:
Specifying --config "check.line-length=90" will override the
check.line-length setting from all configuration files detected by
Fortitude, including configuration files discovered in subdirectories. In this
respect, specifying --config "check.line-length=90" has the same effect as
specifying --line-length=90, which will similarly override the
check.line-length setting from all configuration files detected by Fortitude,
regardless of where a specific configuration file is located.
Full command-line interface
See fortitude help for the full list of Fortitude's top-level commands:
A Fortran linter, written in Rust and installable with Python
Usage: fortitude [OPTIONS] <COMMAND>
Commands:
check Perform static analysis on files and report issues
explain Get descriptions, rationales, and solutions for each rule
version Display Fortitude's version
config List or describe the available configuration options
server Run the language server
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
Log levels:
-v, --verbose Enable verbose logging
-q, --quiet Print diagnostics, but nothing else
-s, --silent Disable all logging (but still exit with status code "1" upon detecting diagnostics)
Global options:
--config <CONFIG_OPTION>
Either a path to a TOML configuration file (`[fpm,fortitude,pyproject].toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might find in a `fortitude.toml` configuration file) overriding a specific configuration option. Overrides of individual settings using this option always take precedence over all configuration files, including configuration files that were also specified using `--config`
--isolated
Ignore all configuration files
For help with a specific command, see: `fortitude help <command>`.
Or fortitude help check for more on the linting command:
Perform static analysis on files and report issues
Usage: fortitude check [OPTIONS] [FILES]...
Arguments:
[FILES]... List of files or directories to check [default: .]
Options:
--fix
Apply fixes to resolve lint violations. Use `--no-fix` to disable or `--unsafe-fixes` to include unsafe fixes
--unsafe-fixes
Include fixes that may not retain the original intent of the code. Use `--no-unsafe-fixes` to disable
--show-fixes
Show an enumeration of all fixed lint violations. Use `--no-show-fixes` to disable
--diff
Avoid writing any fixed files back; instead, output a diff for each changed file to stdout, and exit 0 if there are no diffs. Implies `--fix-only`
--fix-only
Apply fixes to resolve lint violations, but don't report on, or exit non-zero for, leftover violations. Implies `--fix`. Use `--no-fix-only` to disable or `--unsafe-fixes` to include unsafe fixes
--ignore-allow-comments
Ignore any `allow` comments
--output-format <OUTPUT_FORMAT>
Output serialization format for violations. The default serialization format is "full" [env: FORTITUDE_OUTPUT_FORMAT=] [possible values: concise, full, json, json-lines, junit, grouped, github, gitlab, pylint, rdjson, azure, sarif]
-o, --output-file <OUTPUT_FILE>
Specify file to write the linter output to (default: stdout) [env: FORTITUDE_OUTPUT_FILE=]
--preview
Enable preview mode; checks will include unstable rules and fixes. Use `--no-preview` to disable
--target-std <TARGET_STD>
Set minimum Fortran standard to check files against. Options are "f2023", "f2018" (default), "f2008", "f2003", "f95" [possible values: f95, f2003, f2008, f2018, f2023]
--progress-bar <PROGRESS_BAR>
Progress bar settings. Options are "off" (default), "ascii", and "fancy" [possible values: off, fancy, ascii]
--show-settings
See the settings fortitude will use to check a given Fortran file
--show-files
See the files fortitude will be run against with the current settings
--statistics
Show counts for every rule with at least one violation
-h, --help
Print help (see more with '--help')
Rule selection:
--ignore <RULE_CODE>
Comma-separated list of rules to ignore
--select <RULE_CODE>
Comma-separated list of rule codes to enable (or ALL, to enable all rules)
--extend-select <RULE_CODE>
Like --select, but adds additional rule codes on top of those already specified
--per-file-ignores <FILE_PATTERN:RULE_CODE>
List of mappings from file pattern to code to exclude
--extend-per-file-ignores <FILE_PATTERN:RULE_CODE>
Like `--per-file-ignores`, but adds additional ignores on top of those already specified
--fixable <RULE_CODE>
List of rule codes to treat as eligible for fix. Only has an effect if `--fix` is also enabled
--unfixable <RULE_CODE>
List of rule codes to treat as ineligible for fix. Only has an effect if `--fix` is also enabled
--extend-fixable <RULE_CODE>
Like `--fixable`, but adds additional rule codes on top of those already specified
File selection:
--file-extensions <EXTENSION>
File extensions to check
--exclude <FILE_PATTERN>
List of paths, used to omit files and/or directories from analysis
--extend-exclude <FILE_PATTERN>
Like --exclude, but adds additional files and directories on top of those already excluded
--force-exclude
Enforce exclusions, even for paths passed to Fortitude directly on the command-line. Use `--no-force_exclude` to disable
--respect-gitignore
Respect `.gitignore`` files when determining which files to check. Use `--no-respect-gitignore` to disable
--line-filter <LINE_FILTER>
List of files with line ranges to filter warnings. The format is JSON array of objects: [ {"name": "file1.f90", "lines": [[6, 7], [42, 45]]}, {"name": "file2.f90"} ] Line ranges include the end
--git-staged
Only run on files that have been staged in a git repository
--git-since <COMMIT>
Only run on files that differ between the files in the working directory of a git repository and `COMMIT`. `COMMIT` can be most things that look like a commit, for example `main`, `0f3abc`, `HEAD~`
Per-Rule Options:
--line-length <LINE_LENGTH> Set the maximum allowable line length
Miscellaneous:
--stdin-filename <STDIN_FILENAME>
The name of the file when passing it through stdin
-e, --exit-zero
Exit with status code "0", even upon detecting lint violations
--exit-non-zero-on-fix
Exit with a non-zero status code if any files were modified via fix, even if no lint violations remain
Log levels:
-v, --verbose Enable verbose logging
-q, --quiet Print diagnostics, but nothing else
-s, --silent Disable all logging (but still exit with status code "1" upon detecting diagnostics)
Global options:
--config <CONFIG_OPTION>
Either a path to a TOML configuration file (`[fpm,fortitude,pyproject].toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might find in a `fortitude.toml` configuration file) overriding a specific configuration option. Overrides of individual settings using this option always take precedence over all configuration files, including configuration files that were also specified using `--config`
--isolated
Ignore all configuration files
Shell autocompletion
Fortitude supports autocompletion for most shells. A shell-specific completion script can be generated
by fortitude generate-shell-completion <SHELL>, where <SHELL> is one of bash, elvish, fig, fish,
powershell, or zsh.
The exact steps required to enable autocompletion will vary by shell. For example instructions, see the Poetry or ripgrep documentation.
As an example: to enable autocompletion for Bash, run fortitude
generate-shell-completion bash > ~/.bash_completion, then reload your
shell.
Editor integration
We aim to add full Language Server Protocol (LSP) support in a future release which will enable Fortitude to run from within editors such as (Neo)Vim, Emacs and VSCode. In the meantime, it is possible to configure these editors to automate some tasks.
(NeoVim)
Adding the following to your ~/.vimrc or ~/.config/nvim/init.vim file
will set the commands :FortitudeFix and :FortitudeFixUnsafe which will
apply fixes to the current file in your buffer: