README

Linguist

 



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.

 Documentation

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

 Installation

Install the gem:

bash
gem install github-linguist


 Dependencies

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:

bash
brew install cmake pkg-config icu4c


On Ubuntu:

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


 Usage

 Application usage

Linguist can be used in your application as follows:

ruby
require 'rugged'
require 'linguist'

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


 Command line usage

The github-linguist executable operates in two distinct modes:

1. Git Repository mode - Analyzes an entire Git repository (when given a directory path or no path)
2. Single file mode - Analyzes a specific file (when given a file path)

 Git Repository

A repository's languages stats can 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.

bash
cd /path-to-repository
github-linguist


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

console
$ github-linguist
66.84%  264519     Ruby
24.68%  97685      C
6.57%   25999      Go
1.29%   5098       Lex
0.32%   1257       Shell
0.31%   1212       Dockerfile


 Additional options

 --rev REV

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.

console
$ github-linguist jekyll

70.64%  709959     Ruby
23.04%  231555     Gherkin
3.80%   38178      JavaScript
1.19%   11943      HTML
0.79%   7900       Shell
0.23%   2279       Dockerfile
0.13%   1344       Earthly
0.10%   1019       CSS
0.06%   606        S

Top issues

Discussions

Latest release

What's Changed
 Add support for 4 Ignore List/Git Config filenames by @Alhadis in https://github.com/github-linguist/linguist/pull/8020
 Speedup gem loading by @byroot in https://github.com/github-linguist/linguist/pull/8010
 Test against Ruby 3.4 and 4.0 by @byroot in https://github.com/github-linguist/linguist/pull/8011
 Add Blueprint language by @kaypes in https://github.com/github-linguist/linguist/pull/8001
 Change the C colour to purple by @violetshine in https://github.com/github-linguist/linguist/pull/8026
 Add Gno language support by @karagozemin in https://github.com/github-lin