KevinMidboe/linguist
1
0
Fork 0
mirror of https://github.com/KevinMidboe/linguist.git synced 2025-10-29 09:40:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs update

Browse Source
This commit is contained in:
Arfon Smith
2014-10-16 16:33:49 -05:00
parent f100dc91c2
commit 63661dfc6e
1 changed files with 64 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@@ -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.