Installing the `composition` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install composition-cli

It will make the composition command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall composition-cli uninstalls.

Back to the crate overview.

Readme

composition

composition is a modular lines-of-code CLI tool to analyze and display code composition in directories

Features

Multi-language tracking - Analyze code by file extensions with customizable language groupings
Smart filtering - Respect .gitignore, exclude dotfiles/dotfolders, and apply custom ignore patterns
Global & language-specific exclusions - Define regex patterns globally or per-language for precise line filtering
Parallel processing - Efficiently analyze large codebases with parallelized file processing
Configurable analysis - TOML-based configuration with CLI overrides for flexible usage
Visual contribution bars - Scalable visual representation of code composition with optional color coding

Setup

Install Binary

crates.io

cargo install composition-cli --locked

Build from Source

git clone https://github.com/lalitm1004/composition.git
cd composition
cargo build --release
# built binary can be found at ./target/release/composition

Create config.toml at:

Linux / Unix

$HOME/.config/composition/config.toml

macOS

$HOME/Library/Application Support/composition/config.toml

Windows

%appdata%/composition/config.toml

Or the default configuration directory on your system

Populate based on configuration guidelines

NOTE: A missing/invalid config.toml results in falling back to the default

Usage

Flag / Argument	Type	Default	Description
`PATH`	`Optional<Path>`	`Path('.')`	Path to the directory of files to process.
`--scale-bar`	`Optional<float>`	`1.0`	Scale factor for the contribution bar.
`--use-color`	`Optional<bool>`	config*	Override `use_color` config setting.
`--log-scale`	`Optional<bool>`	config*	Override `log_scale` config setting.
`--respect-gitignore`	`Optional<bool>`	config*	Override `respect_gitignore` config setting.
`--ignore-dotfolders`	`Optional<bool>`	config*	Override `ignore_dotfolders` config setting.
`--ignore-dotfiles`	`Optional<bool>`	config*	Override `ignore_dotfiles` config setting.
`--ignore-empty-lines`	`Optional<bool>`	config*	Override `ignore_empty_lines` config setting.

config* : Defaults to the value defined in the config.toml file [or its default]

NOTE: command-line flags take precedence over values in config.toml

Configuration Guidelines

config.toml fields:

Field Name	Type	Default Value	Description
`use_color`	`Optional<bool>`	`false`	Enables colored output in the CLI
`log_scale`	`Optional<bool>`	`false`	Enables logarithmic scale for the contribution bar
`respect_gitignore`	`Optional<bool>`	`true`	Determines whether files/folders ignored by `.gitignore` should also be ignored by this tool
`ignore_dotfolders`	`Optional<bool>`	`true`	If `true`, folders starting with `.` are ignored
`ignored_directories`	`Optional<Array[String]>`	Check here	List of directories to explicitly ignore during analysis
`ignore_dotfiles`	`Optional<bool>`	`true`	If `true` files starting with `.` are ignored
`ignored_files`	`Optional<Array[String]>`	Check here	List of specific files to explicitly ignore
`ignore_empty_lines`	`Optional<bool>`	`true`	If `true`, empty lines are not counted in the analysis
`excluded_patterns`	`Optional<Array[String]>`	Check here	List of VALID regex patterns to exclude from analysis. A line matching ANY of these patterns results in it being discarded from analysis
`tracked`	`Optional<Array[Tracked]>`	Check here	List of `Tracked` structs defining file types/extensions to analyze and their display settings

Tracked struct fields:

Field Name	Type	Default Value	Description
`display`	`String`	required	Label or name to display for this tracked language. Must be unique across all `Tracked` structs
`extensions`	`Array[String]`	required	File extensions associated with this tracked language
`color`	`Optional<String>`	`None`	Color to use when displaying this tracked language. Only used if `use_color` is set to `true`. Must be a VALID* hex code
`excluded_patterns`	`Optional<Array[String]>`	`[]`	List of VALID regex patterns to exclude for this tracked language. A line matching ANY of these patterns results in it being discarded from analysis

Future

AWK-compatible output: Add --awk flag for structured output that can be piped to AWK scripts
Timing controls: Add option to disable timing information in output

Verbose Defaults

`ignored_directories`

ignored_directories = [
  "node_modules",
  "target",
  "build",
  "dist",
  "__venv__",
  "__pycache__",
]

`ignored_files`

ignored_files = [
  "package-lock.json",
]

`excluded_patterns`

excluded_patterns = [
  # lines starting with //
  "^\\s*//",

  # lines starting with #
  "^\\s*#",

  # lines containing only braces, commas, or semicolons
  "^\\s*[\\{\\}\\[\\]\\(\\),;]+\\s*$",
]

`tracked`

[[tracked]]
display = "Rust"
extensions = ["rs"]

[[tracked]]
display = "Python"
extensions = ["py", "pyi"]

[[tracked]]
display = "HTML"
extensions = ["html", "htm"]

[[tracked]]
display = "CSS"
extensions = ["css", "scss", "sass", "less"]

[[tracked]]
display = "JavaScript"
extensions = ["js", "jsx", "mjs", "cjs"]

[[tracked]]
display = "TypeScript"
extensions = ["ts", "tsx"]

[[tracked]]
display = "Svelte"
extensions = ["svelte"]

[[tracked]]
display = "C"
extensions = ["c", "h"]

[[tracked]]
display = "C++"
extensions = ["cpp", "cxx", "cc", "hpp", "hh"]

[[tracked]]
display = "C#"
extensions = ["cs"]

[[tracked]]
display = "Bash / Shell"
extensions = ["sh", "bash", "bashrc", "bash_profile", "zsh", "zshrc"]

[[tracked]]
display = "Java"
extensions = ["java"]

[[tracked]]
display = "Jupyter Notebook"
extensions = ["ipynb"]

[[tracked]]
display = "Assembly"
extensions = ["asm", "s", "mips"]

[[tracked]]
display = "Go"
extensions = ["go"]

[[tracked]]
display = "Prisma"
extensions = ["prisma"]

[[tracked]]
display = "Kotlin"
extensions = ["kt", "kts"]

[[tracked]]
display = "Swift"
extensions = ["swift"]

[[tracked]]
display = "Objective-C"
extensions = ["m", "mm"]

[[tracked]]
display = "PHP"
extensions = ["php", "phtml"]

[[tracked]]
display = "Ruby"
extensions = ["rb", "erb", "gemspec"]

[[tracked]]
display = "Perl"
extensions = ["pl", "pm", "t"]

[[tracked]]
display = "R"
extensions = ["r", "R"]

[[tracked]]
display = "Julia"
extensions = ["jl"]

[[tracked]]
display = "Scala"
extensions = ["scala", "sc"]

[[tracked]]
display = "Haskell"
extensions = ["hs", "lhs"]

[[tracked]]
display = "Elixir"
extensions = ["ex", "exs"]

[[tracked]]
display = "Erlang"
extensions = ["erl", "hrl"]

[[tracked]]
display = "F#"
extensions = ["fs", "fsi", "fsx"]

[[tracked]]
display = "OCaml"
extensions = ["ml", "mli"]

[[tracked]]
display = "Clojure"
extensions = ["clj", "cljs", "cljc", "edn"]

[[tracked]]
display = "Dart"
extensions = ["dart"]

[[tracked]]
display = "Makefile"
extensions = ["mk", "make", "Makefile"]

[[tracked]]
display = "Dockerfile"
extensions = ["dockerfile"]

[[tracked]]
display = "YAML"
extensions = ["yml", "yaml"]

[[tracked]]
display = "JSON"
extensions = ["json", "json5"]

[[tracked]]
display = "TOML"
extensions = ["toml"]

[[tracked]]
display = "INI / Config"
extensions = ["ini", "cfg", "conf", "env"]

[[tracked]]
display = "Markdown"
extensions = ["md", "markdown"]

[[tracked]]
display = "LaTeX"
extensions = ["tex", "sty", "cls"]

[[tracked]]
display = "SQL"
extensions = ["sql"]

[[tracked]]
display = "GraphQL"
extensions = ["graphql", "gql"]

[[tracked]]
display = "Vue"
extensions = ["vue"]

[[tracked]]
display = "Sass"
extensions = ["sass"]

Installing the composition executable

Installing the `composition` executable