Skip to content

Add .gitattributes override mention when returning the strategy #7600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add .gitattributes override mention when returning the strategy #7600

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2c0e922
Record gitattribute override as a strategy with unit and integration …
DecimalTurn Sep 23, 2025
e879628
Force strategy detection when instrumenter is definded
DecimalTurn Sep 23, 2025
09c25d6
Improve command line docs and info on --strategies flag
DecimalTurn Oct 9, 2025
00d12b7
Adjust examples
DecimalTurn Oct 9, 2025
ff81bd8
Add "confirmed by gitattributes"
DecimalTurn Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,14 @@ project.languages #=> { "Ruby" => 119387 }

### Command line usage

The `github-linguist` executable operates in two distinct modes:

1. **[Git Repository mode](#git-repository)** - Analyzes an entire Git repository (when given a directory path or no path)
2. **[Single file mode](#single-file)** - Analyzes a specific file (when given a file path)

#### Git Repository

A repository's languages stats can also be assessed from the command line using the `github-linguist` executable.
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
Expand Down Expand Up @@ -151,6 +156,41 @@ lib/linguist.rb
…
```

##### `--strategies`

The `--strategies` or `-s` flag will show the language detection strategy used for each file. This is useful for understanding how Linguist determined the language of specific files. Note that unless the `--json` flag is specified, this flag will set the `--breakdown` flag implicitly.

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

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

Ruby:
Gemfile [Filename]
Rakefile [Filename]
bin/git-linguist [Extension]
bin/github-linguist [Extension]
lib/linguist.rb [Extension]
…
```

If a file's language was overridden using `.gitattributes`, the strategy will show the original detection method along with an override note:
Copy link
Member

@lildude lildude Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"strategy will show the original detection method along with an override note"

🤔 this is confusing with the output below. devcontainer.json is already JSONC but the output suggests it's overridden to JSONC by an override. Why would you override to the same language?

I think it would be better to use an example where there is a clear difference in languages.

Copy link
Contributor Author

@DecimalTurn DecimalTurn Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would you override to the same language?

I don't know why, but it's the only "override" in the linguist repo 🤷

image

Copy link
Contributor Author

@DecimalTurn DecimalTurn Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be better to use an example where there is a clear difference in languages.

Ok, I'll change it for a better example... I'm thinking of using .bas file override in https://github.com/tannerhelland/PhotoDemon

Copy link
Member

@lildude lildude Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know why, but it's the only "override" in the linguist repo 🤷

Whoops. I'm not sure how that slipped past. We shouldn't need that override.

As an aside, we use the test/attributes branch for testing overrides. The .gitattributes in that branch has a lot more overrides.

Copy link
Contributor Author

@DecimalTurn DecimalTurn Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This discussion makes me think that maybe the implementation of the --strategies flag should make the note appears different if the detection gives the same language as the override.

Copy link
Contributor Author

@DecimalTurn DecimalTurn Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like:

          # Get the original strategy by calling super (which calls Linguist.detect)
          original_language = super
          original_strategy_info = Linguist.instrumenter.detected_info[self.name]
          original_strategy = original_strategy_info ? original_strategy_info[:strategy] : "Unknown"

          # Determine if gitattributes actually changed the result
          if original_language == detected_language
            strategy_name = "#{original_strategy} (confirmed by .gitattributes)"
          else
            strategy_name = "#{original_strategy} (overridden by .gitattributes)"
          end


```console
$ github-linguist --strategies .devcontainer/devcontainer.json
.devcontainer/devcontainer.json: 27 lines (27 sloc)
type: Text
mime type: application/json
language: JSON with Comments
strategy: Filename (overridden by .gitattributes)
```

##### `--json`

The `--json` or `-j` flag output the data into JSON format.
Expand All @@ -168,6 +208,8 @@ $ github-linguist --breakdown --json

```

NB. The `--strategies` flag has no effect, when the `--json` flag is present.

#### Single file

Alternatively you can find stats for a single file using the `github-linguist` executable.
Expand All @@ -182,6 +224,36 @@ grammars.yml: 884 lines (884 sloc)
language: YAML
```

#### Additional options

##### `--breakdown`

This flag has no effect in *Single file* mode.

##### `--strategies`

When using the `--strategies` or `-s` flag with a single file, you can see which detection method was used:

```console
$ github-linguist --strategies lib/linguist.rb
lib/linguist.rb: 105 lines (96 sloc)
type: Text
mime type: application/x-ruby
language: Ruby
strategy: Extension
```

##### `--json`

Using the `--json` flag will give you the output for a single file in JSON format:

```console
$ github-linguist --strategies --json lib/linguist.rb
{"lib/linguist.rb":{"lines":105,"sloc":96,"type":"Text","mime_type":"application/x-ruby","language":"Ruby","large":false,"generated":false,"vendored":false}}
```

NB. The `--strategies` has no effect, when the `--json` flag is present.

#### Docker

If you have Docker installed you can either build or use
Expand Down