gitignore redesign proposal

I have 4 proposed changes to the gitignore feature:

1. Integrate a hard-coded .gitignore.local option for quietly ignoring user files. Automatically ignore this file, or require users to exclude it in the main .gitignore.

2. Change .gitignore to just gitignore. This is because gitignore is not a system configuration file. Users are expected to interact with it. Dot-files are typically not user-facing files. They are expected to be hidden on Linux systems, which is inconsistent with the expectation of user interaction. They are entirely avoided on Windows systems for user-facing configuration files. When a user sees ".file" on Windows, they know they should be using a GUI to edit the config, not hand-hacking. Additionally, dot-files are ambiguous: they could contain key-value pairs or scripts. The point is, don't put essential controls in a room labeled "For personnel use only" while expecting customers to go touch it to get anything done. gitignore is fundamentally different from the .git folder in intent.

3. Implement gitignore.yaml as an alternative to basic gitignore file, for the following reasons:

  - Ability to include other YAML ignore files
  - Clearer organization

4. Every gitignore file should be initialized with a link to the gitignore templates on GitHub.

Why YAML?

Being able to include other files in a main ignore file is necessary collaborative environments. Teams need two things:

1. To be able to include templates that are provided by authoritative sources (such as next.js, zig, unity, etc). Veteran coders know to pull templates from this repository: https://github.com/github/gitignore --- a repository that is not self-evident in any respect for a beginner software developer. Beginners have to just *magically* happen upon the repository or search for gitignore templates in a search engine. This intuition is not a guarantee, so every gitignore file should be initialized by git with a link to that repository to maintain good practice.

2. To be able to organize their gitignores hierarchically. At present, people just randomly stick items in the file, so it's a visual mess that results in duplicates being added. Removing a duplicate doesn't guarantee the removal of the other in very large gitignore files, which can cause problems.

I previously requested an include feature in the existing gitignore parser, but I saw that people are afraid to implement it by modifying the normal gitignore syntax to accommodate. To deal with this, I recommend implementing a YAML alternative to the traditional gitignore file. YAML already has a usable syntax, parser, etc. This extension would exist concurrently to the current gitignore implementation so that it can be adopted gradually.

This is a totally reasonable path forward to make gitignore robust for collaborative development. You have a good idea and a fail-proof way to introduce it.

Thank you, Ryan Johnson

On 2025-11-11 at 01:02:39, Ryan Johnson wrote:

Why is this better than $XDG_CONFIG_HOME/git/ignore, which is global and works for all of the user's repositories, or .git/info/exclude, which is per repository and not checked in?

The former is the ideal place to put things one wants ignored globally, such as Vim swap files or Emacs backup files, and the latter is suitable for individual projects. The former can even be installed by one's dotfiles so that one's `git status` output is always tidy with regard to one's editor files.

Typically, we hide files and directories used by version control systems because there are several of them (.git, .gitignore, .gitmodules, and .gitattributes).

This also helps other tools easily not process VCS-specific files by providing an option to skip processing hidden files.

CVS and friends did not use hidden files and it was ugly and unwieldy. (In general, we should avoid replicating CVS's mistakes.)

We try not to prioritize any particular forge in this project and many contributors work on a variety of different forges. Even though I am employed by a major forge[0], I end up using several because various projects I would like to participate in are on other forges (even some projects that we use at work).

There's no reason that the GitHub templates are intrinsically better than any other options and if an objectively better option comes along, we would end up providing suboptimal information.

I'll also note that the GitHub templates tend to be very expansive and cover a large variety of files. The Python file, for instance, covers Django, Jupyter Notebook, IPython, Redis, SageMath, and a variety of other things that most Python projects will never use. Having a very long file with a lot of unused entries worsens performance and makes maintenance of the file much more complicated than necessary, especially when a project needs custom values as well.

I have over 13 years of professional software development experience and even more non-professional, so I think I would qualify as a veteran coder. I don't use those files, either at home or at work.

Instead, when creating a project, I add those files and directories that are build or intermediate products to .gitignore as one of my first commits and add additional entries along the way. That way, I know that my values are correct for my project.

Note that I almost always have additional custom files that are not listed in the templates, so I need to edit the file anyway. I assume that's true for most everyone, but I could be wrong.

I agree that YAML is a very popular option. However, different parsers implement different versions, so they work differently. It also has some downsides (`no` is interpreted as false, not "no", which is a frequent source of problems for Norway- and Norwegian-related information). Some parsers[1] also don't support parsing byte data encoded as base64 (the `!!binary` tag), which we would need because Git does not require filenames to be UTF-8.

Other options, such as JSON or TOML, also don't support non-UTF-8 data (and JSON doesn't support comments[2]), so those are also out.

[0] My participation in this list, unless stated otherwise, is in my personal capacity only and I neither speak for my employer nor do they speak for me. [1] In my brief few minutes of testing a handful of implementations, I found Perl's YAML::Tiny, which also does not accept `!!str`. [2] Before you say, "But there's this variant of JSON that _does_ support comments," that is not standardized and most JSON parsers don't accept it, so it is strictly worse than using YAML or TOML in terms of compatibility.