Git Attribute overrides examples - why are some linguist override examples prefixed with -?

[aSemy]

Some example usages are prefixed with a minus sign. I'm not sure why this is. I couldn't find any explanation in the docs

• https://github.com/github/linguist/blob/37e08a91ac3e845e308f42a1284e8ae276bb94c4/docs/overrides.md?plain=1#L47
• https://github.com/github/linguist/blob/37e08a91ac3e845e308f42a1284e8ae276bb94c4/docs/overrides.md?plain=1#L61
• https://github.com/github/linguist/blob/37e08a91ac3e845e308f42a1284e8ae276bb94c4/docs/overrides.md?plain=1#L90

tools/export_bom.py -linguist-detectable
#                   ↑ is this minus correct?

# or should there be no minus?
tools/export_bom.py linguist-detectable

If there is a difference between linguist-detectable and -linguist-detectable, what is it? I couldn't see any explanation.

[lildude]

I couldn't find any explanation in the docs

You're probably not looking in the right docs 😉.

This is standard .gitattributes notation so you should be looking at that documentation. From the .gitattributes documentation:

Unset

The path has the attribute with special value "false"; this is specified by listing the name of the attribute prefixed with a dash - in the attribute list.

So the - is correct. Linguist also supports a non-standard Linguist-specific approach of linguist-detectable=false but we're discouraging this use in favour of the use people expect from their other .gitattributes usage.

If there is a difference between linguist-detectable and -linguist-detectable, what is it? I couldn't see any explanation.

Yup. The former sets the attribute (documented just above the "Unset" mentioned above) and the latter unsets the attribute as detailed above.

[aSemy]

Thanks for the explanation! I didn't realise that unsetting was even an option in .gitattributes

If I could make a suggestion, then I would have found it easier to understand with a slight rephrasing

https://github.com/github/linguist/blob/37e08a91ac3e845e308f42a1284e8ae276bb94c4/docs/overrides.md?plain=1#L42-L48

Use the `linguist-detectable` attribute to mark or unmark (by prefixing with `-`) paths as detectable:

```gitattributes
# mark any matching files as detectable
*.kicad_pcb linguist-detectable
*.sch linguist-detectable

# unmark a specific file as detectable
tools/export_bom.py -linguist-detectable
```