RFC patchmaintenance: add config option for config-file

A feature request I'm submitting as an RFC since it was about the same effort to write the code to describe the behaviour I was wanting.

An actual patch for the feature would involve some docs etc., but first I just wanted to see if the feature seemed reasonable.

Matthew Hughes (1):
  maintenance: add config option for config-file

 builtin/gc.c           |  8 ++++++++
 t/t7900-maintenance.sh | 13 +++++++++++++
 2 files changed, 21 insertions(+)

This is to allow splitting out this configuration from the global config file, e.g.:

    # in ~/.config/git/config
    [include]
        path = maintenance.config
    [maintenance]
        # use a separate files for reads/writes from
        # 'git maintenance {un,}register'
        configFile = ~/.config/git/maintenance.config

    # in ~/.config/git/maintenance.config
    [maintenance]
        repo = /path/to/some/repo
        repo = /path/to/another/repo

My motivation for this is that I track my global config in git, so I'd like to avoid changes in there that depend on specific repos/workflows that I'm working with.

Signed-off-by: Matthew Hughes <matthewhughes934@gmail.com>
---
 builtin/gc.c           |  8 ++++++++
 t/t7900-maintenance.sh | 13 +++++++++++++
 2 files changed, 21 insertions(+)

On Thu, Dec 18, 2025 at 06:48:19PM +0000, Matthew Hughes wrote:

I think the idea is quite sensible, and I understand the need to split up static configuration from dynamic one. One part I'm unsure about though is the explicit need to use "include.path" for this. Ideally, git-maintenance(1) should by itself know to include the path that the user has configured in "maintenance.configFile".

Note that in our codebase this would typically be written as:

	if (!config_file)
		repo_config_get_pathname(the_repository, "maintenance.configFile", &config_file);

Note the missing curly braces around a single-line statement as well as the implicit check for NULL.

It's nice that we only need a two-line change here to make this work.

Okay, this is the equivalent for unregistering maintenance. Makes senes.

So these both are straight-forward. The question is whether we can also easily teach scheduled maintenance to respect `maintenance.configFile` so that the user doesn't have to manually include the configured file. I think the answer is "not quite".

The services that scheduled maintenance writes use git-for-each-repo(1) to iterate through all repositories. We basically execute that command via `git for-each-repo --config=maintenance.repo -- git maintenance run --schedule=%%i`. But that command does not have a way to have it read the configuration from a different file.

I think adding such a feature shouldn't be that hard though. You can use the below (completely untested) patch as a starter for this. But once we had such a feature we'd only have to adapt how we write the services files to pass the new flag in case "maintenance.configFile" is set.

There's two questions in this context:

  - Do we already know to rewrite the service files in case the commands
    that Git would write change?

  - Do we need to migrate any of the preexisting keys that exist in the
    global configuration?

Also Cc'ing Stolee for input.

Thanks!

Patrick

-- >8 --

Matthew Hughes <matthewhughes934@gmail.com> writes:

I cannot guess what "this" refers to in this sentence.

You are burdening your readers too heavily. After reading the above three times and then trying to guess what you are trying to do for several minutes, what I am guessing is:

 * maintenance.configFile specifies an additional file to which
   maintenance.repo configuration items are written out when "git
   maintenance register/unregister" works.  

 * "git config" is not affected, so "git config set --global
   --append maintenance.repo foo" would still write into the
   per-user configuration file.

 * Also, the general config API does not pay maintenance.configFile
   at all, so setting it does not affect "git config list", for
   example.

 * You'd need an extra "[include] path = maintenance.config" in the
   configuration file because of the previous point.

Am I following you well so far? Giving an explanation on your _intent_, along with the sample configuration, would help your readers, and I would expect something with a similar degree of detail as above in the log message.

I am not sure if singling out "maintenance" is the right approach to solve that issue. If we had a mechanism to have two per-user configuration file, where one is read-only (as far as Git is concerned) which is covered/overlayed with a separate read-write file, not just "maintenance register/unregister" but all other things that writes into "git config" would use that overlayed file without touching the base configuration that is read-only. Wouldn't that be closer to what you want?

 * Comparison with 0 or NULL should be spelled "if (!config_file)"
   (meaning, 'is NULL') or "if (config_file)" (meaning, 'not NULL'),
   in this project.

 * This project omits {} around a single statement block.

 * The function call is overly long. wrap to comfortably fit on
   80-column terminal after getting quoted in an e-mail review twice
   or so, which means ~72 columns is the practical width limit.

	repo_config_get_pathname(the_repository,
        			"maintenance.configFile", &config_file);

Readers would wonder "To what existing contents is this being appended? Do we have something that we care?" If not, do not use ">>" to mislead them.

Would the output of the pwd command match what "maintenance register" writes into the file even on Windows? We often see breakage between $(pwd) and $PWD and I can never get this right without looking at past discussions.

For this particular case, would it be sufficient to ask

    git config get --all --no-includes --file maintenance.config \
	maintenance.repo

    git config get --all --no-includes --file ./git/config \
	maintenance.repo

and see if the former gives output and the latter does not, or something?

Making sure the maintenance.repo file gets written is good, but for your purpose, it is equally if not more important that the base configuration file is not affected, no?

Ditto.

On Fri, Dec 19, 2025 at 05:27:33PM +0900, Junio C Hamano wrote:

 
Yep, this is a good summary of what my change looks to achieve. From Patrick's
response (https://lore.kernel.org/git/aUT8Vcevf8WiQgn0@pks.im/) I understand
the requirement of the extra "include.path" setting is likely not acceptable
for a usability point of view.

Thanks for the feedback, I'll look to be clearer with my intent in the future.

Indeed a read-only config as you described would be a more general solution, and a better one than focusing on single commands like this change does. I'm now curious if a similar idea has been discussed in the past? I'll go have a look in the history of this mailing list.

That leads me to think my proposed change is too narrow in scope, and risks dividing functionality: where some commands are taught to consider the separate types of configuration, while others are not.

For background: I singled out "maintenance" only because it's the first git command that I can remember seeing that was writing to my global config (outside of "config" itself).

On Mon, Dec 22, 2025 at 3:55 AM Matthew Hughes <matthewhughes934@gmail.com> wrote:

FWIW, I also include my gitconfig in version control, and the way I manage this is with

    [include]
            path = ~/.gitconfig.local

If I run "git maintenance register", I then move the added configuration lines to ~/.gitconfig.local. It's a bit of a hassle, but not much (I don't frequently add new repos to the set).