Subject: Re: [RFC] Support UTF-8 characters in Git alias names

From: Jeff King <[email-masked]>
Date: Mon, 9 Feb 2026 02:36:02 -0500

On Sun, Feb 08, 2026 at 04:30:02PM +0100, Jonatan Holmgren wrote:

> I think the best approach is to support UTF-8 specifically for alias.*
> variables, which would mean modifying the git_config_parse_key() fn to allow
> UTF-8 bytes and make non-ascii aliases case-sensitive to avoid complex
> locale-dependent case folding.
> 
> The main pain point would be making sure all platforms handle this nicely,
> esp since mac uses NFD and not NFC Unicode.
> 
> Before implementing this, I'd like to hear:
> 
> 1. Is this a feature the project would like?
> 2. Is my implementation approach reasonable?
> 3. What concerns should be addressed in said design?
> 4. Any compat requirements I should be aware of?

I think supporting non-ascii aliases is a good goal.

However, I'm not sure that special-casing the parsing of alias config
keys is the best direction. Since it's a syntactic change, the special
case would have to be understand by all code that reads or writes
config, not just git_config_parse_key(). And then you'd potentially run
into problems with older versions of Git, or alternate implementations
(of which there are several).

Plus it doesn't solve all of the issues. E.g., should we allow new
characters like "_" (for a potential "git foo_bar")? That is doable, but
what about "." (for "git foo.bar")? I think that introduces new
ambiguities into the syntax.

Taking a step back, I think the root of the issue is that the schema for
alias keys is poorly designed. Git's config syntax allows for three
levels: section, subsection, and key. The section and key fields are
restricted to alnum and dash, but the subsection is designed to be
unrestricted (modulo NUL bytes).

And that's why we have:

  [branch "foo/bar"]
  remote = origin

for example, because branch names don't follow the same syntax rules as
config keys. And it's the same issue here: the alias.* schema is trying
to use one syntax (alnum config keys) to store another (command names).
They _usually_ overlap, but not always. The pager.* config has the same
problem.

We've discussed this before, e.g., in:

  https://lore.kernel.org/git/[email-masked]/

There the immediate problem was that "git foo_bar" caused an error
message. We hacked around it by suppressing the error, but it was still
impossible to add an alias or pager config. We knew that was a
limitation, but punted until somebody came along who actually cared
about making it work. Now you get to be that somebody. ;)

So what I'd propose instead is introducing a new schema like:

  - setting "alias.foo.command" to "bar" would alias "git foo" to "bar";
    this should work for any command name, as it is just a byte stream

  - a given command subsection is matched verbatim. So alias.foo.command
    matches "git foo" but not "git Foo". Likewise, we do not do any
    normalization. You put what you want into your config, and it should
    match the command you invoke. This is perhaps less friendly, but it
    punts on any normalization or case-folding that we have to do, and
    matches how the rest of Git works (paths are likewise streams of
    bytes, and it is mostly up to the user to use them consistently).

  - leave "alias.foo" as a historical synonym for "alias.foo.command",
    so that existing config continues working

  - optionally add new keys within alias.foo.* sections. For example, we
    could allow alias.foo.help to provide text shown during "git help
    foo". For the most part that could come later, so I'm just
    illustrating possible eventual directions that the new schema would
    allow. But it might be worth pondering a little now to avoid
    painting ourselves into a corner. E.g., you could imagine a schema
    where alias.foo.shell is set to "true" instead of sticking a "!" at
    the front of the value of alias.foo.command. I don't know if that's
    a good idea or not, but if we were going to do stuff like that, we'd
    want to decide now before setting the alias.foo.command behavior in
    stone.

  - likewise, optionally do the same for pager.*

I hacked together some illustrative code below. Note that we do use
strcasecmp() currently to match command names (which kind of makes
sense, since if you had "alias.Foo" in your config, the parser would
downcase it to "alias.foo"). So probably that historical code should
continue to behave like that, but the new "alias.Foo.command" should be
more verbatim (the patch below just feeds them both to strcasecmp).

-Peff

---
diff --git a/alias.c b/alias.c
index 1a1a141a0a..44bdde58af 100644
--- a/alias.c
+++ b/alias.c
@@ -17,19 +17,30 @@ static int config_alias_cb(const char *key, const char *value,
 			   const struct config_context *ctx UNUSED, void *d)
 {
 	struct config_alias_data *data = d;
-	const char *p;
+	const char *cmd, *p;
+	size_t cmd_len;
 
-	if (!skip_prefix(key, "alias.", &p))
+	if (parse_config_key(key, "alias", &cmd, &cmd_len, &p) < 0)
 		return 0;
 
+	if (cmd) {
+		/* The only 3-level key we understand is alias.*.command */
+		if (strcmp(p, "command"))
+			return 0;
+	} else {
+		/* alias.foo is the same as alias.foo.command */
+		cmd = p;
+		cmd_len = strlen(p);
+	}
+
 	if (data->alias) {
-		if (!strcasecmp(p, data->alias)) {
+		if (!strncasecmp(cmd, data->alias, cmd_len)) {
 			FREE_AND_NULL(data->v);
 			return git_config_string(&data->v,
 						 key, value);
 		}
 	} else if (data->list) {
-		string_list_append(data->list, p);
+		string_list_append_nodup(data->list, xmemdupz(cmd, cmd_len));
 	}
 
 	return 0;