This library is used on GitHub.com to detect blob languages, ignore binary or vendored files, suppress generated files in diffs, and generate language breakdown graphs.

• How Linguist works
• Change Linguist's behaviour with overrides
• Troubleshooting
• Contributing guidelines

Install the gem:

gem install github-linguist

Linguist is a Ruby library so you will need a recent version of Ruby installed. There are known problems with the macOS/Xcode supplied version of Ruby that causes problems installing some of the dependencies. Accordingly, we highly recommend you install a version of Ruby using Homebrew, rbenv, rvm, ruby-build, asdf or other packaging system, before attempting to install Linguist and the dependencies.

Linguist uses charlock_holmes for character encoding and rugged for libgit2 bindings for Ruby. These components have their own dependencies.

1. charlock_holmes
   • cmake
   • pkg-config
   • ICU
   • zlib
2. rugged
   • libcurl
   • OpenSSL

You may need to install missing dependencies before you can install Linguist. For example, on macOS with Homebrew:

brew install cmake pkg-config icu4c

On Ubuntu:

sudo apt-get install build-essential cmake pkg-config libicu-dev zlib1g-dev libcurl4-openssl-dev libssl-dev ruby-dev

Linguist can be used in your application as follows:

require'rugged'require'linguist'repo=Rugged::Repository.new('.')project=Linguist::Repository.new(repo,repo.head.target_id)project.language#=> "Ruby"project.languages#=>{"Ruby" => 119387 }

A repository's languages stats can also be assessed from the command line using the github-linguist executable. Without any options, github-linguist will output the language breakdown by percentage and file size.

cd /path-to-repository github-linguist

You can try running github-linguist on the root directory in this repository itself:

$ github-linguist66.84% 264519 Ruby24.68% 97685 C6.57% 25999 Go1.29% 5098 Lex0.32% 1257 Shell0.31% 1212 Dockerfile

The --rev REV flag will change the git revision being analyzed to any gitrevisions(1) compatible revision you specify.

This is useful to analyze the makeup of a repo as of a certain tag, or in a certain branch.

For example, here is the popular Jekyll open source project.

$ github-linguist jekyll70.64% 709959 Ruby23.04% 231555 Gherkin3.80% 38178 JavaScript1.19% 11943 HTML0.79% 7900 Shell0.23% 2279 Dockerfile0.13% 1344 Earthly0.10% 1019 CSS0.06% 606 SCSS0.02% 234 CoffeeScript0.01% 90 Hack

And here is Jekyll's published website, from the gh-pages branch inside their repository.

$ github-linguist jekyll --rev origin/gh-pages100.00% 2568354 HTML

The --breakdown or -b flag will additionally show the breakdown of files by language.

You can try running github-linguist on the root directory in this repository itself:

$ github-linguist --breakdown66.84% 264519 Ruby24.68% 97685 C6.57% 25999 Go1.29% 5098 Lex0.32% 1257 Shell0.31% 1212 DockerfileRuby:GemfileRakefilebin/git-linguistbin/github-linguistext/linguist/extconf.rbgithub-linguist.gemspeclib/linguist.rb…

The --json or -j flag output the data into JSON format.

$ github-linguist --json{"Dockerfile":{"size":1212,"percentage":"0.31"},"Ruby":{"size":264519,"percentage":"66.84"},"C":{"size":97685,"percentage":"24.68"},"Lex":{"size":5098,"percentage":"1.29"},"Shell":{"size":1257,"percentage":"0.32"},"Go":{"size":25999,"percentage":"6.57"}}

This option can be used in conjunction with --breakdown to get a full list of files along with the size and percentage data.

$ github-linguist --breakdown --json{"Dockerfile":{"size":1212,"percentage":"0.31","files":["Dockerfile","tools/grammars/Dockerfile"]},"Ruby":{"size":264519,"percentage":"66.84","files":["Gemfile","Rakefile","bin/git-linguist","bin/github-linguist","ext/linguist/extconf.rb","github-linguist.gemspec","lib/linguist.rb",...]}}

Alternatively you can find stats for a single file using the github-linguist executable.

You can try running github-linguist on files in this repository itself:

$ github-linguist grammars.ymlgrammars.yml: 884 lines (884 sloc) type: Text mime type: text/x-yaml language: YAML

If you have Docker installed you can either build or use our pre-built images and run Linguist within a container:

$ docker run --rm -v $(pwd):$(pwd):Z -w $(pwd) -t ghcr.io/github-linguist/linguist:latest66.84% 264519 Ruby24.68% 97685 C6.57% 25999 Go1.29% 5098 Lex0.32% 1257 Shell0.31% 1212 Dockerfile

$ docker build -t linguist . $ docker run --rm -v $(pwd):$(pwd):Z -w $(pwd) -t linguist66.84% 264519 Ruby24.68% 97685 C6.57% 25999 Go1.29% 5098 Lex0.32% 1257 Shell0.31% 1212 Dockerfile $ docker run --rm -v $(pwd):$(pwd) -w $(pwd) -t linguist github-linguist --breakdown66.84% 264519 Ruby24.68% 97685 C6.57% 25999 Go1.29% 5098 Lex0.32% 1257 Shell0.31% 1212 DockerfileRuby:GemfileRakefilebin/git-linguistbin/github-linguistext/linguist/extconf.rbgithub-linguist.gemspeclib/linguist.rb…

Please check out our contributing guidelines.

The language grammars included in this gem are covered by their repositories' respective licenses. vendor/README.md lists the repository for each grammar.

All other files are covered by the MIT license, see LICENSE.