Subject: Re: gitignore redesign proposal

From: "brian m. carlson" <[email-masked]>
Date: Tue, 11 Nov 2025 02:04:51 +0000

On 2025-11-11 at 01:02:39, Ryan Johnson wrote:
> 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.

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.

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

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

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

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.

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

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.

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

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.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA