Linguist is a Ruby library that detects programming languages in source code files and generates language statistics for repositories.
The tool solves the problem of accurately identifying which programming languages are present in a codebase, which GitHub uses to ignore binary or vendored files, suppress generated files in diffs, and create language breakdown visualizations. It works by analyzing file contents and metadata to determine language, using character encoding detection and Git repository analysis to process entire codebases or individual files.
Linguist is essential for any project that needs accurate language detection and reporting, particularly those integrated with GitHub or requiring automated language statistics. It suits repositories of any size where correct language identification matters for documentation, metrics, or tooling. The tool operates in two modes: analyzing entire Git repositories to produce language breakdowns by percentage and file size, or examining single files for language detection. Users can inspect how the tool determined a file's language using the strategies flag, which shows the detection method and whether gitattributes overrides affected the result. The library can analyze repositories at specific Git revisions, making it useful for tracking language composition across branches or tags.
Development on the project is active and community-driven, with the README explicitly inviting pull requests when language detection is incorrect. The tool maintains comprehensive documentation covering how language detection works, how to override Linguist's behavior, and troubleshooting guidance. Installation requires careful attention to dependencies, particularly the native extensions charlock_holmes and rugged, which depend on system libraries including ICU, zlib, libcurl, and OpenSSL, with documented setup instructions for multiple platforms. The project provides both a Ruby API for programmatic use and a command-line interface with multiple output formats including JSON, making it accessible to different integration patterns.
