Skip to content
Get packs

Guide · Open source

How to use linguist: language breakdown for any Git repo

Updated · written with AI from the project's own documentation and checked against our catalogue data

Linguist is a Ruby library and command-line tool that works out which programming language each file in a project is written in, and how much of the project each language makes up. This guide shows you how to install the github-linguist gem, run it on a Git repository or a single file, and use the main flags. By the end you will be able to read a language breakdown and correct a wrong label with a .gitattributes override.

Linguistgithub-linguist/linguist · ★ 13.8k · MIT

Quick start

  1. 1Install Ruby. Install a recent Ruby using Homebrew, rbenv, rvm, ruby-build, asdf or another packaging system. The README advises against relying on the macOS system Ruby.
  2. 2Install system dependencies. Install cmake, pkg-config, ICU and zlib, plus libcurl and OpenSSL for rugged. Use the Homebrew or apt command from the README for your system.
  3. 3Install the gem. Run gem install github-linguist.
  4. 4Run it on a repository. Change into the repository and run github-linguist to see the percentage breakdown by language.
  5. 5Add more detail. Use --breakdown to list files per language, or --strategies to see how each file was detected.
  6. 6Override wrong labels. Add linguist-language attributes to .gitattributes for any files that are detected incorrectly, then rerun with --strategies to confirm the change.

What you need before you install linguist

Linguist is a Ruby library, so you need a recent version of Ruby installed. The README warns that the version of Ruby supplied with macOS and Xcode can cause problems installing some dependencies, and recommends installing Ruby with Homebrew, rbenv, rvm, ruby-build, asdf or another packaging system first.

Linguist uses charlock_holmes for character encoding and rugged for libgit2 bindings. Each has its own dependencies: cmake, pkg-config, ICU and zlib for charlock_holmes, and libcurl and OpenSSL for rugged.

  • Ruby (recent version)
  • cmake
  • pkg-config
  • ICU
  • zlib
  • libcurl and OpenSSL (for rugged)

Install the github-linguist gem

Once Ruby is in place, install the gem. If the build fails, the README says you may need to install the missing system dependencies first. It gives two examples: Homebrew on macOS and apt on Ubuntu.

gem install github-linguist # macOS with Homebrew brew install cmake pkg-config icu4c # Ubuntu sudo apt-get install build-essential cmake pkg-config libicu-dev zlib1g-dev libcurl4-openssl-dev libssl-dev ruby-dev

Run linguist on a Git repository

Change into a repository and run the github-linguist executable with no options. It prints the language breakdown by percentage and file size. The README's example output for its own repository shows Ruby at 66.84% and C at 24.68%, with each row listing the percentage, size in bytes and language name.

Git repository mode is used when you give a directory path or no path at all. To analyse a different revision, such as a tag or branch, use the --rev flag.

  • --breakdown or -b: also lists the files in each language
  • --strategies or -s: shows how each file's language was detected (sets --breakdown automatically unless --json is used)
  • --json or -j: outputs the data as JSON
  • --rev REV: analyses any gitrevisions(1) compatible revision
cd /path-to-repository github-linguist github-linguist --breakdown github-linguist --rev origin/gh-pages

Check a single file

Pass a file path instead of a directory to analyse one file. The output shows the line count, source lines of code (sloc), file type, MIME type, language and, with --strategies, the detection strategy used. The --breakdown flag has no effect in single file mode.

github-linguist lib/linguist.rb github-linguist --strategies lib/linguist.rb

Get machine-readable output with --json

Add --json to get the results as JSON, which is useful in scripts. Combine it with --breakdown to get the list of files for each language. The README notes that --strategies has no effect when --json is present.

For a single file, --json reports fields such as lines, sloc, type, mime_type, language, large, generated and vendored.

github-linguist --json github-linguist --breakdown --json github-linguist --strategies --json lib/linguist.rb

Correct a wrong language with .gitattributes

If your repository's language is reported incorrectly, you can add per-file overrides in a .gitattributes file using the linguist-language attribute. The README's example forces .ts and .js files to be counted as JavaScript.

The --strategies output tells you what happened. It says overridden by .gitattributes when the override changed the result, and confirmed by .gitattributes when the override matched what detection would have chosen. The README links to a separate overrides guide for more detail. If the README's advice does not fix your case, it asks you to send a pull request.

*.ts linguist-language=JavaScript *.js linguist-language=JavaScript

What people use it for

  • Get a quick language breakdown of a Git repository from the command line
  • Check which languages GitHub is likely to report for a repository, using the same detection library GitHub.com uses according to the README
  • Find out why a particular file was labelled a certain way by using --strategies
  • Export language statistics as JSON for a script or report
  • Build a Ruby tool that needs to detect file languages, using the Linguist::Repository class

Frequently asked questions

Is linguist free to use?

Linguist is released under the MIT licence, as listed in the project details. The README does not describe any paid tier, so you can use and install it without a licence fee.

How do I install linguist?

Install a recent Ruby, then run gem install github-linguist. If the install fails, install the system dependencies listed in the README, such as cmake, pkg-config and ICU, using Homebrew on macOS or apt on Ubuntu.

What Ruby version does linguist need?

The README says you need a recent version of Ruby. It does not name a specific version. It recommends installing Ruby with a version manager or Homebrew rather than using the macOS system Ruby.

Why does linguist say my file is the wrong language?

Linguist uses detection strategies such as file extension, filename and heuristics. Run github-linguist --strategies to see which strategy was used. You can then fix the result with a linguist-language override in .gitattributes.

Can linguist analyse a specific branch or tag?

Yes. Use the --rev flag with any gitrevisions(1) compatible revision, such as a tag or branch name. The README gives the example github-linguist jekyll --rev origin/gh-pages.

How does linguist compare to cloc, tokei and scc?

Linguist is built around GitHub's language detection and is a Ruby library that can also be used in your own code. The README does not compare it with cloc, tokei or scc, so check each tool's documentation to compare features and speed for your project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Linguist suits developers and maintainers who want to see the language makeup of a Git repository from the command line, or who need to fix how GitHub labels their code, and who are comfortable installing Ruby and native build dependencies. If you need a non-Ruby tool, want an editor, or cannot build charlock_holmes and rugged on your system, pick a different option such as cloc, tokei or scc.

Install options & downloads