Configuration

clocscan is configured with a JSON file that describes which file extensions are considered “code”, which files and folders to ignore, and how comments are recognised when counting source lines of code (SLOC).

extension — the file extension without a leading dot (for example rs, py, js). Important: the extension must not include a leading .. The CLI accepts extensions with or without a leading dot (e.g. -e rs or -e .rs), but values in the JSON must be plain extension names.
file_type — a short, human-readable label for that extension (for example Rust, Python, JavaScript). This label is shown in the output table.

When clocscan runs it builds a simple suffix regular expression from the listed extensions and matches file paths against it. Matching is case-sensitive.

"code_file_extensions": [
    { "extension": "rs", "file_type": "Rust" },
    { "extension": "py", "file_type": "Python" },
    { "extension": "js", "file_type": "JavaScript" }
]

CLI precedence. Extensions supplied on the command line (-e, --ext) override the extensions in the JSON config. The CLI accepts multiple -e flags and also accepts comma-separated lists (for example -e rs -e py or -e rs,py). When provided, the CLI normalises extensions by removing a leading dot.

What to ignore

You can instruct clocscan to skip files and folders. The ignore rules are simple substring matches against the file path.

Folders

Provide a list of folder name substrings. If any part of a file’s path contains one of these substrings, that file is ignored.

"ignore": {
    "folders": ["target", "node_modules", ".git"]
}

Examples:

target will ignore ./target/debug/whatever.rs.
node_modules will ignore anything under a node_modules path segment.

This is not a glob or regular expression: the program checks path_str.contains(folder).

Files

Provide a list of filename substrings. If a file path contains any of these substrings, the file is ignored.

"ignore": {
    "files": ["README.md", "LICENSE", "bundle.js"]
}

As with folders, matching is a substring check, not a glob or regular expression.

Comment patterns

The JSON config controls how single-line and multi-line comments are recognised while counting SLOC. The program applies these rules to each trimmed line of a file:

single_line — a list of single-line comment prefixes. A line is treated as a comment if trimmed_line.starts_with(pattern).
- Examples: "#", "//", ";".
multi_line_start — a list of opening tokens that begin a multi-line comment if a trimmed line starts with the token. When such a token is found, clocscan enters a multi-line comment state and treats the current line as a comment.
- Examples: "/*", "{-", R\"\"\"".
multi_line_end — a list of closing tokens. While in the multi-line comment state, clocscan checks whether the trimmed line ends with any of these tokens; if so, it exits the multi-line comment state after treating that line as a comment.
- Examples: "*/", "-}", "\"\"\"".

"comment_patterns": {
    "single_line": ["//", "#"],
    "multi_line_start": ["/*"],
    "multi_line_end": ["*/"]
}

Important behaviour notes and limitations:

The matching uses starts_with for multi_line_start and single_line, and ends_with for multi_line_end. Patterns should be provided exactly as they appear in source code (for example /* and */).
If a line both starts with a multi-line start token and also contains a matching end token on the same line, the implementation sets the in_multiline_comment flag and returns true (the line is treated as a comment) but does not detect a same-line end token to immediately toggle the flag back. In other words, multi-line comment pairs that open and close on the same line are not handled special-case and may leave the scanner in the multi-line state until an explicit multi_line_end is found on a later line. Keep this limitation in mind when defining tokens.
The comment detection is deliberately simple and language-agnostic. It does not attempt to parse language grammar, so edge cases (strings containing comment markers, nested comment syntaxes, etc.) may require careful choice of patterns.

Behaviour and notes

Default config: If the JSON config file is not present, clocscan falls back to an embedded default config (the sample config shipped in docs/sample.json).
Config file path: The CLI flag --config (default config.json) controls which file is read; if that file cannot be read, the embedded default is used.
Extension matching: The program constructs a suffix regular expression from configured extensions and applies it to file paths. The extension strings in JSON must not include a leading dot. Matching is case-sensitive.
Ignore matching: Ignore rules are substring checks against the file path. They are not globs or regular expressions.
How SLOC is computed: Lines that are empty after trimming or that match single-line comment prefixes or fall within a recognised multi-line comment block are excluded. All other lines are counted as SLOC.
File type labels: The file_type field in each extension entry is only a label used for display in the summary table; it has no semantic effect on counting.
CLI flags that affect behaviour:
- -e, --ext overrides extensions in the config (CLI values accept a leading dot and are normalised).
- --sloc-only prints only the total SLOC count and exits.
- -v/-vv/-vvv control logging verbosity.

Example configuration

A minimal, ready-to-use config:

{
  "code_file_extensions": [
    { "extension": "rs", "file_type": "Rust" },
    { "extension": "py", "file_type": "Python" },
    { "extension": "js", "file_type": "JavaScript" }
  ],
  "ignore": {
    "folders": ["target", "node_modules", ".git"],
    "files": ["README.md", "LICENSE"]
  },
  "comment_patterns": {
    "single_line": ["//", "#"],
    "multi_line_start": ["/*", "\"\"\""],
    "multi_line_end": ["*/", "\"\"\""]
  }
}

This configuration treats rs, py and js files as source files, ignores common build and repository folders, and recognises // and # single-line comments as well as /* ... */ and Python/JS triple-quote style blocks as multi-line comments.

Navigation Menu

Repository navigation

Configuration

Table of Contents

File extensions