From 63661dfc6ef488d4e5415bfec71c3e85f56a3c96 Mon Sep 17 00:00:00 2001 From: Arfon Smith Date: Thu, 16 Oct 2014 16:33:49 -0500 Subject: [PATCH 1/3] Docs update --- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 241b4aee..76bc0501 100644 --- a/README.md +++ b/README.md @@ -104,9 +104,72 @@ Linguist::FileBlob.new("underscore.min.js").generated? # => true See [Linguist::Generated#generated?](https://github.com/github/linguist/blob/master/lib/linguist/generated.rb). +## Overrides +Linguist now support custom overrides for language definitions and vendored paths. To make use of these you need to add a `.gitattributes` file to your project using the keys `linguist-language` and `linguist-vendored` with the standard git-style path matchers for the files you want to handle this way. + +###Language overrides + +First let's look at an example of overriding the language returned by Linguist (first without custom `.gitattributes` data): + +``` +> cd my-project +> ls -m1 -a +.git +ruby_file.rb + +> linguist --breakdown +100.00% Ruby + +Ruby: +ruby_file.rb +``` + +Now the same git repository but with the `.gitattributes` file specifying that all files ending in `.rb` are actually Java: + +``` +> cat .gitattributes +*.rb linguist-language=Java + +> linguist --breakdown +100.00% Java + +Java: +ruby_file.rb +``` + +###Custom vendored paths + +By default, Linguist treats all of the paths defined in [lib/linguist/vendor.yml](https://github.com/github/linguist/blob/master/lib/linguist/vendor.yml) as vendored and therefore doesn't include them in the language statistics for a repository. + +With the new overrides it's possible to both add additional vendored paths and override standard behavior to specify paths as _not_ vendored. + +For example, the following repository has a large Javascript file in an unusual path `special-vendored-path`: + +``` +> cat .gitattributes +special-vendored-path/* linguist-vendored=true + +> irb +> require 'linguist' +> repo = Rugged::Repository.new('.') #to read .gitattributes data we need the git repository +> sha = repo.head.target_id #current commit +> blob = Linguist::LazyBlob.new(repo, sha, 'special-vendored-path/massive-js-file.js').vendored? +=> true +``` + +To override standard behavior (i.e. un-vendor a path) the syntax is: + +``` +jquery.js linguist-vendored=false +``` + +### Feedback please! + +The custom overrides are a new feature and we'd love your feedback [here](https://github.com/github/linguist/issues/new?title=Linguist+gitattributes+feedback). + ## Installation -github.com is usually running the latest version of the `github-linguist` gem that is released on [RubyGems.org](http://rubygems.org/gems/github-linguist). +Github.com is usually running the latest version of the `github-linguist` gem that is released on [RubyGems.org](http://rubygems.org/gems/github-linguist). But for development you are going to want to checkout out the source. To get it, clone the repo and run [Bundler](http://gembundler.com/) to install its dependencies. From 843e196f00c4b502d570c5cc7c5948ee7dd4fcdf Mon Sep 17 00:00:00 2001 From: Arfon Smith Date: Thu, 16 Oct 2014 20:56:21 -0500 Subject: [PATCH 2/3] Formatting --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 76bc0501..e55a8f29 100644 --- a/README.md +++ b/README.md @@ -148,12 +148,12 @@ For example, the following repository has a large Javascript file in an unusual ``` > cat .gitattributes special-vendored-path/* linguist-vendored=true - -> irb -> require 'linguist' -> repo = Rugged::Repository.new('.') #to read .gitattributes data we need the git repository -> sha = repo.head.target_id #current commit -> blob = Linguist::LazyBlob.new(repo, sha, 'special-vendored-path/massive-js-file.js').vendored? +``` +```ruby +require 'linguist' +repo = Rugged::Repository.new('.') #to read .gitattributes data we need the git repository +sha = repo.head.target_id #current commit +blob = Linguist::LazyBlob.new(repo, sha, 'special-vendored-path/massive-js-file.js').vendored? => true ``` From b0b94182a2449c9360b2bea77fa906fa79ee579f Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Fri, 17 Oct 2014 08:41:03 -0400 Subject: [PATCH 3/3] :scissors: --- README.md | 52 ++++++---------------------------------------------- 1 file changed, 6 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index e55a8f29..2950f269 100644 --- a/README.md +++ b/README.md @@ -105,68 +105,28 @@ Linguist::FileBlob.new("underscore.min.js").generated? # => true See [Linguist::Generated#generated?](https://github.com/github/linguist/blob/master/lib/linguist/generated.rb). ## Overrides -Linguist now support custom overrides for language definitions and vendored paths. To make use of these you need to add a `.gitattributes` file to your project using the keys `linguist-language` and `linguist-vendored` with the standard git-style path matchers for the files you want to handle this way. -###Language overrides - -First let's look at an example of overriding the language returned by Linguist (first without custom `.gitattributes` data): +Linguist supports custom overrides for language definitions and vendored paths. Add a `.gitattributes` file to your project using the keys `linguist-language` and `linguist-vendored` with the standard git-style path matchers for the files you want to override. ``` -> cd my-project -> ls -m1 -a -.git -ruby_file.rb - -> linguist --breakdown -100.00% Ruby - -Ruby: -ruby_file.rb -``` - -Now the same git repository but with the `.gitattributes` file specifying that all files ending in `.rb` are actually Java: - -``` -> cat .gitattributes +$ cat .gitattributes *.rb linguist-language=Java -> linguist --breakdown +$ linguist --breakdown 100.00% Java Java: ruby_file.rb ``` -###Custom vendored paths - -By default, Linguist treats all of the paths defined in [lib/linguist/vendor.yml](https://github.com/github/linguist/blob/master/lib/linguist/vendor.yml) as vendored and therefore doesn't include them in the language statistics for a repository. - -With the new overrides it's possible to both add additional vendored paths and override standard behavior to specify paths as _not_ vendored. - -For example, the following repository has a large Javascript file in an unusual path `special-vendored-path`: - -``` -> cat .gitattributes -special-vendored-path/* linguist-vendored=true -``` -```ruby -require 'linguist' -repo = Rugged::Repository.new('.') #to read .gitattributes data we need the git repository -sha = repo.head.target_id #current commit -blob = Linguist::LazyBlob.new(repo, sha, 'special-vendored-path/massive-js-file.js').vendored? -=> true -``` - -To override standard behavior (i.e. un-vendor a path) the syntax is: +By default, Linguist treats all of the paths defined in [lib/linguist/vendor.yml](https://github.com/github/linguist/blob/master/lib/linguist/vendor.yml) as vendored and therefore doesn't include them in the language statistics for a repository. Use the `linguist-vendored` attribute to vendor or un-vendor paths. ``` +$ cat .gitattributes +special-vendored-path/* linguist-vendored jquery.js linguist-vendored=false ``` -### Feedback please! - -The custom overrides are a new feature and we'd love your feedback [here](https://github.com/github/linguist/issues/new?title=Linguist+gitattributes+feedback). - ## Installation Github.com is usually running the latest version of the `github-linguist` gem that is released on [RubyGems.org](http://rubygems.org/gems/github-linguist).