config: allow disabling config includes

From: Derrick Stolee <[email protected]>

The config keys 'include.path' and 'includeIf.*' allow users to specify config stored in a location outside of the typical list of config files (system, global, local, etc.). For example, users who accept the risk can specify helpful aliases via a file checked into the repo by pointing 'include.path' to the position of that file in the working directory. This is dangerous, but people do it.

What becomes tricky is that this modifies all Git behavior, including operations that are intended to be limited in activity or sandboxed in some way. These include directives can provide surprising changes to behavior, especially when expecting a specific list of allowed file accesses. This could lead to failed builds, for instance.

To allow for these user-desired features when they are running commands, add a new GIT_CONFIG_INCLUDES environment variable that disables these redirections of config when set to zero. This variable can be set by automation, such as build tooling, to avoid these strange behaviors. This could be considered a recommended option for tools executing Git commands, the same as GIT_ADVICE=0.

Quoted 8 lines · Derrick Stolee via GitGitGadget

From: Derrick Stolee <[email protected]>

The config keys 'include.path' and 'includeIf.*' allow users to specify config stored in a location outside of the typical list of config files (system, global, local, etc.). For example, users who accept the risk can specify helpful aliases via a file checked into the repo by pointing 'include.path' to the position of that file in the working directory. This is dangerous, but people do it.

Huh, I never even considered this use case. But of course, this is possible, even though it's quite scary.

Quoted 6 lines

What becomes tricky is that this modifies all Git behavior, including operations that are intended to be limited in activity or sandboxed in some way. These include directives can provide surprising changes to behavior, especially when expecting a specific list of allowed file accesses. This could lead to failed builds, for instance.

Quoted 6 lines

To allow for these user-desired features when they are running commands, add a new GIT_CONFIG_INCLUDES environment variable that disables these redirections of config when set to zero. This variable can be set by automation, such as build tooling, to avoid these strange behaviors. This could be considered a recommended option for tools executing Git commands, the same as GIT_ADVICE=0.

I don't know about this part though. I could see use cases where the tools _should_ read the project-relative configuration. It might also be the case that the user may want to evaluate some includes, but not all of them.

That raises the question whether we can introduce the configuration in a way that it allows a bit more flexibility than just "yes"/"no", like for example an allow-list of locations that should be evaluated. But maybe I'm overthinking this.

This series introduces a new way to ignore config include directives via two mechanisms:

* GIT_CONFIG_INCLUDES=0 in the environment.
* git --no-includes ... in the command line.

My motivation is from a tricky situation where users want to do the risky thing and include a repo-tracked file for sharing aliases and other recommended config. They are then struggling in a later build step that is running Git commands (under a tool we don't control and can't change) that then cause filesystem accesses outside of the build system's sandbox.

One thing I do worry about is whether or not this would cause a significant break in behavior, or if this is a relatively safe thing to allow.

Quoted 5 lines · Patrick Steinhardt

On Mon, Jun 08, 2026 at 01:57:05PM +0000, Derrick Stolee via GitGitGadget wrote:
That raises the question whether we can introduce the configuration in a way that it allows a bit more flexibility than just "yes"/"no", like for example an allow-list of locations that should be evaluated. But maybe I'm overthinking this.

I see. So we can say "avoid including into the repository worktree" but that will probably be incomplete.

There is room for nuance in future expansions, if we can find a creative way to handle that nuance. For now, I think I would still want an ability to turn the entire feature off, at least for certain tools that care.

Quoted 11 lines · Derrick Stolee via GitGitGadget

This series introduces a new way to ignore config include directives via two mechanisms:

* GIT_CONFIG_INCLUDES=0 in the environment.
* git --no-includes ... in the command line.

My motivation is from a tricky situation where users want to do the risky thing and include a repo-tracked file for sharing aliases and other recommended config. They are then struggling in a later build step that is running Git commands (under a tool we don't control and can't change) that then cause filesystem accesses outside of the build system's sandbox.

I'm not opposed to global control of includes, but this is just one way in which config can escape the sandbox. They can always point to files (e.g., core.attributesFile) or even commands that totally leave the sandbox (e.g., ext diff or textconv commands). Fundamentally git config is equivalent to arbitrary code execution, so pointing an include at a repo-tracked file carries the risk of confusion both malicious and accidental.

So I dunno. From the described motivation, this feels like a band-aid that fixes only one narrow instance of a greater problem.

The notion of enabling/disabling includes per-command is itself a flexible building block. So it's possible that it has other uses in general. But it's also a fairly broad hammer that covers more than your use case. If you're planning to use "git --no-includes" in some script, then it breaks the config of anybody who uses includes in their user-level ~/.gitconfig file.

So you may need some more directed limiting.

Quoted 2 lines

One thing I do worry about is whether or not this would cause a significant break in behavior, or if this is a relatively safe thing to allow.

Yeah. Consider something like:

  $ cat ~/.gitconfig
  [user]
  name = My Name
  email = [email protected]
  [includeIf "gitdir:/path/to/work/stuff"]
  path = .gitconfig-work

  $ cat ~/.gitconfig-work
  [user]
  email = [email protected]

Using "git --no-include" will silently use the wrong user.email value. That's OK if the user is asking for it, but if you are planning to sprinkle "--no-include" inside scripts, that's likely to cause confusion.

Quoted 10 lines

So I dunno. From the described motivation, this feels like a band-aid that fixes only one narrow instance of a greater problem.

The notion of enabling/disabling includes per-command is itself a flexible building block. So it's possible that it has other uses in general. But it's also a fairly broad hammer that covers more than your use case. If you're planning to use "git --no-includes" in some script, then it breaks the config of anybody who uses includes in their user-level ~/.gitconfig file.

Quoted 1 line

So you may need some more directed limiting.

Are you suggesting some kind of internal sandbox to limit Git from accessing repository paths from config includes and other config-set keys? That would be a more complete solution, but I'm not sure how we could plug all of those holes at once. I'll think on it, though.

This is exactly the kind of case I was worried about. This specific case only impacts write operations, but some tools do those things. And this email case is a common one that users do in their global config to isolate personal and professional identities.

I'm trying to think if there's a place where we'd have some config that is critical to the repo functioning not in its local config (like the repo format version or extensions). Perhaps borrowing from your work/personal example, a user could use a different credential helper for work than they use for personal repositories.

Or: are we venturing into territory where we don't even want to create a new foot-gun? If there were another way to solve the situation that I'm facing without these risks, then I'd be open to it. Any ideas?

On Tue, Jun 09, 2026 at 08:59:22AM -0400, Derrick Stolee wrote:

I'm not sure I entirely understand the problematic case, though. The user points to in-repo config (which we already tell people is a bad idea), and then that config breaks for some reason? Because the include is relative and git is run from another directory?

Quoted 3 lines

Or: are we venturing into territory where we don't even want to create a new foot-gun? If there were another way to solve the situation that I'm facing without these risks, then I'd be open to it. Any ideas?

Yeah, the more I think on it, the more it seems like a foot-gun. Like I said, I'm not sure I entirely understand the use-case. If you could flesh out an example, that might help.

Quoted 7 lines · Jeff King

On Tue, Jun 09, 2026 at 08:59:22AM -0400, Derrick Stolee wrote:

I'm not sure I entirely understand the problematic case, though. The user points to in-repo config (which we already tell people is a bad idea), and then that config breaks for some reason? Because the include is relative and git is run from another directory?

Quoted 7 lines

Quoted 3 lines

Or: are we venturing into territory where we don't even want to create a new foot-gun? If there were another way to solve the situation that I'm facing without these risks, then I'd be open to it. Any ideas?

Yeah, the more I think on it, the more it seems like a foot-gun. Like I said, I'm not sure I entirely understand the use-case. If you could flesh out an example, that might help.

The case I'm struggling with is that our build system has sandboxing restrictions to make sure the build is deterministic based on a certain number of inputs. A tool we don't control is calling Git commands and these users with included config are getting errors because the build is looking at files in the repo that are not registered as build inputs.

Files within $SRCROOT/.git/ are ignored as "internal to Git" but when the users update their config to include other files, this error occurs.

I'd much rather that this tool doesn't call Git at all, but I'm unable to make that change to a third-party tool. But this environment variable would make it possible to disable this behavior. And I'd also rather that these users don't use includes in this way, but they are using a checked-in file to share aliases and other quality-of-life things when a human uses Git, not "critical" settings.

This series is my attempt to see if we can find a solution that enables this behavior, but maybe we've found enough concerns with the idea that we can push back on the users to say "stop doing that."

Quoted 31 lines · Derrick Stolee

Quoted 7 lines · Jeff King

On Tue, Jun 09, 2026 at 08:59:22AM -0400, Derrick Stolee wrote:

I'm not sure I entirely understand the problematic case, though. The user points to in-repo config (which we already tell people is a bad idea), and then that config breaks for some reason? Because the include is relative and git is run from another directory?

Quoted 7 lines

Quoted 3 lines

Or: are we venturing into territory where we don't even want to create a new foot-gun? If there were another way to solve the situation that I'm facing without these risks, then I'd be open to it. Any ideas?

Yeah, the more I think on it, the more it seems like a foot-gun. Like I said, I'm not sure I entirely understand the use-case. If you could flesh out an example, that might help.

The case I'm struggling with is that our build system has sandboxing restrictions to make sure the build is deterministic based on a certain number of inputs. A tool we don't control is calling Git commands and these users with included config are getting errors because the build is looking at files in the repo that are not registered as build inputs.

Files within $SRCROOT/.git/ are ignored as "internal to Git" but when the users update their config to include other files, this error occurs.

I'd much rather that this tool doesn't call Git at all, but I'm unable to make that change to a third-party tool. But this environment variable would make it possible to disable this behavior. And I'd also rather that these users don't use includes in this way, but they are using a checked-in file to share aliases and other quality-of-life things when a human uses Git, not "critical" settings.

Quoted 3 lines

This series is my attempt to see if we can find a solution that enables this behavior, but maybe we've found enough concerns with the idea that we can push back on the users to say "stop doing that."

It seems that the thread went dark after this message. Should I take silence as an agreement, and mark the topic as retracted?

Thanks for an interesting discussion.

Quoted 40 lines · Junio C Hamano

Quoted 31 lines · Derrick Stolee

Quoted 7 lines · Jeff King

On Tue, Jun 09, 2026 at 08:59:22AM -0400, Derrick Stolee wrote:

I'm not sure I entirely understand the problematic case, though. The user points to in-repo config (which we already tell people is a bad idea), and then that config breaks for some reason? Because the include is relative and git is run from another directory?

Quoted 7 lines

Quoted 3 lines

Or: are we venturing into territory where we don't even want to create a new foot-gun? If there were another way to solve the situation that I'm facing without these risks, then I'd be open to it. Any ideas?

Yeah, the more I think on it, the more it seems like a foot-gun. Like I said, I'm not sure I entirely understand the use-case. If you could flesh out an example, that might help.

The case I'm struggling with is that our build system has sandboxing restrictions to make sure the build is deterministic based on a certain number of inputs. A tool we don't control is calling Git commands and these users with included config are getting errors because the build is looking at files in the repo that are not registered as build inputs.

Files within $SRCROOT/.git/ are ignored as "internal to Git" but when the users update their config to include other files, this error occurs.

I'd much rather that this tool doesn't call Git at all, but I'm unable to make that change to a third-party tool. But this environment variable would make it possible to disable this behavior. And I'd also rather that these users don't use includes in this way, but they are using a checked-in file to share aliases and other quality-of-life things when a human uses Git, not "critical" settings.

Quoted 3 lines

This series is my attempt to see if we can find a solution that enables this behavior, but maybe we've found enough concerns with the idea that we can push back on the users to say "stop doing that."

It seems that the thread went dark after this message. Should I take silence as an agreement, and mark the topic as retracted?

Quoted 1 line

Thanks for an interesting discussion.

Yes, consider this retracted. I saw you made that note in the What's Cooking email so I thought it was understood.

I believe that the risk is not worth the reward here.