Underdocumented CODEOWNERS syntax

[rdelfin]

What article on docs.github.com is affected?

https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax

What part(s) of the article would you like to see updated?

The CODEOWNERS syntax seems to not document valid syntax properly. As we recently found on one of our repos, this is invalid:

/directory/to/code       @orgname/myteam-owners  # a comment

Because the inline comment syntax is unsupported. However, .gitignore files do seem to support these comment types. Are there any other exceptions to the .gitignore syntax that are not documented?

Additional information

N/A

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

N.B. the effect of any syntax error also appears to be that the enitre file is silently ignored, meaning these issues can persist for some time before being discovered

[janiceilene]

Does this line from the CODEOWNERS syntax section cover the information you're looking for?

If any line in your CODEOWNERS file contains invalid syntax, the file will not be detected and will not be used to request reviews. Invalid syntax includes inline comments and user or team names that do not exist on GitHub.

We could change the line at the beginning of that section from:

A CODEOWNERS file uses a pattern that follows the same rules used in gitignore files.

To something like this:

A CODEOWNERS file uses a pattern that follows most of the rules used in gitignore files.

Anyone is welcome to open a PR to update that line!

[StarTrooper08]

@janiceilene can I work on this issue #1407 ??

[rdelfin]

@janiceilene that would help clarify! Do you know where the full spec for a CODEOWNERS is? I'd be glad to put in a PR too, but I'm not sure where to look for what defines this syntax

[janiceilene]

@rdelfin I'm chatting with some folks internally to pull that together, but it'll take me until next week (lots of folks are out for the holidays). Please feel free to ping me a reminder in this issue to followup if I forget next week 💛

[rdelfin]

Appreciate you talking to people about this! I forget it's Thanksgiving over there. I'll ping you in a week as a reminder if you forget

[nitishgoukonde]

[ajsirota]

Hey there @janiceilene, any updates on this?

[janiceilene]

Thanks for the reminder ping @ajs256! After chatting with some folks in engineering who read through the gitignore syntax docs, it looks like:

• we don't support the negation operator that gitignore does, where prefacing a pattern with ! makes a negative match.
• we don't support using [] brackets to define a character range.
• we don't support starting a pattern with # by escaping it with \ (so it isn't considered a line comment.)

If you want to add those exceptions (they need a bit of a rewrite and polish 💅 ) to CODEOWNERS syntax that would be amazing!