patch, 4 partsrepo: add support for path-related fields

Hi!

This patch series adds support for path-related fields in repo-info, based on what we already have in git-rev-parse:

1. The two first patches moves the path formatting used by git-rev-parse to
   path.c. This will allow us to reuse this code in git-repo-info
2. The second patch add a new flag --path-format to git-repo-info, similar to
   the flag of git-rev-parse with the same name
3. Add the new field `path.toplevel` as a proof of concept.

This arises from the fact that I didn't know what should be the default behavior of git-repo-info when dealing with paths. Some ideas were:

1. Add --path-format, just like we have in git-rev-parse
2. Use what rev-parse uses by default
3. Add keys for both relative and absolute formats

In this case, I'm using 1, but I'm not sure if it's the best option. One downside that I see here is that git-repo-info won't be able to return a relative and an absolute path for different keys in the same call.

Since there are many people interested in contributing to git-repo-info, I'll leave the remaining path-related fields to them :-)

I'm CC'ing here:

- brian, who was the original author of the `print_path` [1]
- Ayush, Tian, Jayatheerth, Soutrik and Pushkar, since they expressed interested
  in contributing to git-repo-info in GSoC. (I hope that I didn't forget anyone)

This patch is based on top of master 2cc7191751 (The 8th batch, 2026-02-27) with lo/repo-leftover-bits merged.

[1] fac60b8925 (rev-parse: add option for absolute or relative path formatting, 2020-12-13)

Lucas Seiki Oshiro (4):
  rev-parse: prepend `path_` to path-related enums
  path: add new function strbuf_add_path
  repo: add the --format-path flag
  repo: add the field path.toplevel

 Documentation/git-repo.adoc |  8 ++-
 builtin/repo.c              | 67 +++++++++++++++++++------
 builtin/rev-parse.c         | 98 +++++++------------------------------
 path.c                      | 51 +++++++++++++++++++
 path.h                      | 23 +++++++++
 t/t1900-repo-info.sh        | 69 ++++++++++++++++++++++++++
 6 files changed, 221 insertions(+), 95 deletions(-)

There are two enums used in rev-parse for deciding how paths will be printed by the function `print_path`: `format_type` and `default_type`. Even though there aren't any ambiguities yet, their names aren't clear that those "types" are path types.

Rename both enums and their values by prepending the word `path_`, to clarify that they are used for choosing path types.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 builtin/rev-parse.c | 56 ++++++++++++++++++++++-----------------------
 1 file changed, 28 insertions(+), 28 deletions(-)

The function `print_path`, introduced in fac60b8925 (rev-parse: add option for absolute or relative path formatting, 2020-12-13), is used by git-rev-parse for printing paths, deciding between using relative or absolute paths. This decision, however, could benefit other commands, notably git-repo-info.

Encapsulate this logic into a new function called `strbuf_add_path`, located in `path.c`. Move to path.c the two enums used for deciding the path format, i.e. `path_default_type` and `path_format_type`.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 builtin/rev-parse.c | 72 ++++-----------------------------------------
 path.c              | 51 ++++++++++++++++++++++++++++++++
 path.h              | 23 +++++++++++++++
 3 files changed, 80 insertions(+), 66 deletions(-)

Some paths handled by Git are better presented in their absolute format and others are better presented relative to the current working directory.

Add a `--format-path` flag to git-repo-info, allowing the user to force the outputted paths to be either in the absolute or in the relative format. This flag is similar to its homonymous in git-rev-parse, introduced in fac60b8925 (rev-parse: add option for absolute or relative path formatting, 2020-12-13).

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 Documentation/git-repo.adoc |  8 ++++++--
 builtin/repo.c              | 24 +++++++++++++++++++-----
 t/t1900-repo-info.sh        |  7 +++++++
 3 files changed, 32 insertions(+), 7 deletions(-)

The flag `--show-toplevel` from git-rev-parse is used for retrieving the top level directory path of the repository. This way, it is used for querying repository metadata, fitting in the purpose of git-repo-info.

Add a new field `path.toplevel` to the git-repo-info subcommand containing that information.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 builtin/repo.c       | 47 +++++++++++++++++++++++++--------
 t/t1900-repo-info.sh | 62 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 11 deletions(-)

Hi Lucas,

 > I'm CC'ing here:
 >
 > - brian, who was the original author of the `print_path` [1]
 > - Ayush, Tian, Jayatheerth, Soutrik and Pushkar, since they expressed 
 >   interested in contributing to git-repo-info in GSoC. (I hope that I
 >   didn't forget anyone)

Thank you for your thoughtful consideration!

 > 1. Add --path-format, just like we have in git-rev-parse
 > 2. Use what rev-parse uses by default
 > 3. Add keys for both relative and absolute formats

It makes me wonder if we can use Format Modifiers as in ref-filter.c...

	https://git-scm.com/docs/git-for-each-ref

...which allow us to control the output precisely. For example:

	%(path:relative)
	%(path:absolute)
	%(path:short)
	%(path:strip=2)...

Just a thought.

 > There are two enums used in rev-parse for deciding how paths will
 > be printed by the function `print_path`: `format_type` and
 > `default_type`. Even though there aren't any ambiguities yet, their
 > names aren't clear that those "types" are path types.

This one makes sense to me. Also reduce naming conflicts.

 > +void strbuf_add_path(struct strbuf *sb, const char *path, const char 
 > *prefix, enum path_format_type format, enum path_default_type def)

Isn't it a bit inappropriate for a generic character concatenation function to know about format and def? I don't think this should be the responsibility of a low-level function, at least not str_buf_add_path().

All functions starting with strbuf_add.. listed by git grep strbuf_add are mostly pure string concatenation operations. I believe this should be the case here as well.

 > +	if (!prefix && (format != PATH_FORMAT_DEFAULT || def != 
PATH_DEFAULT_RELATIVE_IF_SHARED))
 > +		prefix = cwd = xgetcwd();

I think the logic here shouldn't be tied to PATH_DEFAULT_RELATIVE_IF_SHARED, I believe the attribution here is the same as above.

 > +		prefix = cwd = xgetcwd()

Will there be a performance regression? Since xgetcwd() here is a system call, right? If prefix == NULL and the get repo info command is used to locate the top-level path among a large number of submodules, and this command will be executed multiple times.

In my opinion, upper-level commands should call xgetcwd() only once before entering the loop, then pass the obtained prefix as an argument to the underlying implementation.

I don't think we should add the two new parameters to all get_ functions here. As changed in your patch, functions like get_object_format don't really, need to know about prefix or format, so the corresponding parameters are marked as UNUSED. Imagine if more and more data needs to be retrieved by these get_ series functions in the future — is it really advisable to add unnecessary parameters to all remaining functions just for the sake of a few?

I'm not entirely sure about the above content either; I'm just throwing out ideas to spark discussion. (´～`)

Thanks again for starting this discussion!

Regards,

Yuchen

Hi, Tian!

I don't think it can be considered a low-level function, but I agree that its name can be misleading.

In this case, no, it is defined in wrapper.h.

In this case, we need to add them to match the signature of get_value_fn. Those values will be useful for all the path.*, but if we start to add more than that I agree that we'll need to think in a better solution.

Thanks, it's also good to see more points of view. I'm also not sure about it :-)

Hi Lucas

Hummm...If a function is solely responsible for string concatenation and resides in like path.c, why isn't it a low level function?

I think the key issue lies in the fact that this function's responsibilities are not quite appropriate, rather than merely the name. Does a string buffer need to understand Git's path formatting rules? It should only know how to append bytes, right? Maybe it would be better suited as a domain-specific formatter like 'format_path_output()' in a higher level module? I am quite uncertain about it.

Yes it is defined in wrapper.h. However in wrapper.c we have:

char *xgetcwd(void)
{
	struct strbuf sb = STRBUF_INIT;
	if (strbuf_getcwd(&sb))
		die_errno(_("unable to get current working directory"));
	return strbuf_detach(&sb, NULL);
}

and the for the stfbuf_getcwd(), in strbuf.c we have:

int strbuf_getcwd(struct strbuf *sb)
{
	size_t oldalloc = sb->alloc;
	size_t guessed_len = 128;

	for (;; guessed_len *= 2) {
		strbuf_grow(sb, guessed_len);
		if (getcwd(sb->buf, sb->alloc)) {
			strbuf_setlen(sb, strlen(sb->buf));
			return 0;
...

Notice the getcwd() function, which is indeed a system call, which you can check with 'man 2 getcwd' in terminal. Wrapping it in wrapper.c is just providing a shortcut, right?

But I don't think using system calls is inherently problematic. The issue lies in where this xgetbuf() is placed:

In builtin/rev-parse.c, the print_path() function is inside of cmd_rev_parse(), which is like:

int cmd_rev_parse(....){
	for (i = 1; i < argc; i++){
	...
	if (....){
		print_path(....)
	}
	...
}

And your print_path() implement was:

So this system call is indeed invoked in the loop. Specifically, it gets called every time 'git rev-parse' is invoked, and as far as I know it should be a command used extensively in like shell scripts...?

Maybe cache-up approach is more robust? For example in builtin/rev-parse.c:

const char *cached_cwd = ...->original_cwd;
if (!cached_cwd)
	cached_cwd = xgetcwd();

for (...) {
	if (...) {
		print_path_with_cwd(..., cached_cwd, ...);
	}
}

Yes indeed.

Thank you for the patch again!

Regards,

Yuchen

On Sun, Mar 1, 2026 at 4:14 AM Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> wrote:

Hey Lucas,

Option 1 feels like the cleanest approach. Even though it means git-repo-info can't return both a relative and absolute path in the exact same call, it keeps the API highly predictable for scripting without bloating the key namespace (which Option 3 would do).

The behaviour is different when compared to the command itself where we have to use --all, but I think in this area this is the right approach.

Thank you ;)

This provides a fantastic foundation. I have updated my GSoC proposal based on these patches to build out the remaining path.* keys, alongside category-based querying and global state removal.

I will be sending that in a completely new thread shortly.

Regards
- Jayatheerth

Hi Lucas,

Thanks for sharing this series — moving the path formatting logic into path.c makes a lot of sense and avoids duplication with rev-parse.

Regarding the limitation you mentioned about not being able to mix relative and absolute paths within the same invocation, I was wondering whether it might be worth considering making the path format part of the key itself, rather than controlled by a global flag.

For example, something along the lines of: path.toplevel path.absolute.toplevel path.relative.toplevel

This could allow users to request different formats in a single call without introducing global state into the command output. That said, I’m not sure whether this would complicate the key namespace too much, or whether maintaining parity with rev-parse semantics is preferable for consistency.

I’d be interested to hear your thoughts on this trade-off.

Best, Ayush

On Sun, Mar 1, 2026 at 8:28 AM JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> wrote:

Hi Ayush,

On Sun, Mar 1, 2026 at 11:15 AM Ayush Jha <kumarayushjha123@gmail.com> wrote:

I think this idea works for individual retrieval It still won't work when the request is for --all The main problem of absolute vs relative would arrive from the --all perspective, no?

If a script specifically needs both formats for a set of paths, the caller can easily just invoke the command twice: i.e git repo info --path-format=absolute <keys...> git repo info --path-format=relative <keys...>

It would still work for individual path terms

I think adding the absolute or relative terms in key is more of a "user" friendly one.

What do you think about it?

Regards,
- Jayatheerth

Hi, Ayush!

Yeah, but since git-repo-info was written as a better home for some features currently in git-rev-parse, now we can think in better solutions.

I also thought about that, but what would happen with --all? If --all returns both absolute and relative, then we would have the third solution.

Hi Lucas,

I completely agree that having --all dump three variants of every path (default, relative, absolute) would be far too noisy and defeat the purpose of a clean metadata dump.

My thought is that the path.absolute.* and path.relative.* keys could be treated as "virtual" or computed keys.

If a user runs --all, the command would only iterate over and print the base keys (e.g., path.toplevel, path.git-dir). The specific format variants would simply be hidden from the iteration list, much like how some APIs only return expensive or highly-specific fields if they are explicitly requested.

This way, --all stays perfectly clean and concise, but scripts that need mixed granular control can still invoke git repo info path.absolute.git-dir path.relative.toplevel in a single pass without relying on global state flags.

Do you think treating them as explicit-request-only fields strikes the right balance between a clean --all output and a stateless API?

On Mon, Mar 2, 2026 at 1:25 AM Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> wrote:

Yeah. I think that in the future most of them will be path.*, and 3 would double them...

Hi Lucas

On 28/02/2026 22:05, Lucas Seiki Oshiro wrote:

How does this effort relate to similar effort at at https://lore.kernel.org/pull.2208.v5.git.git.1772220640.gitgitgadget@gmail.com ? Also note the suggestion from Junio in that thread to use "path.working-tree" rather than copying the name from "git rev-parse"

I think that's the best solution. Having different defaults for different paths like rev-parse is confusing and having different keys for absolute and relative versions of the same path gets rather verbose.

Thanks

Phillip

Hi, Phillip!

I have this patch series started since July, but I could only send this after having my two previous changes in git-repo-info accepted.

I think that patch series you mentioned is based on some previous message (or the GSoC project ideas) where I listed what was still need to be implemented. It uses a similar --path-format flag, but without dealing with the multiple possibilities currently used by git-rev-parse (see [1]).

The original print_path from git-rev-parse has four possible default formats (relative, relative if there's a shared root, canonical (absolute), and unmodified), and we can force it to use the relative or absolute formats. If I understood it correctly, this complex logic was added ([1]) to allow the user to force one of these two formats without breaking the default behavior. Since git-repo-info is a new command, we are free from being compatible with that, and perhaps this doesn't make sense.

Since there are many people interested in contributing to git-repo-info, especially in the path-* fields, I just wanted to finish what I have here and leave the rest for them :-)

I agree, but I still think that it feels weird that we won't be able return absolute and relative paths in a single git-repo-info call. But it also won't cost too much to call it twice.

Thanks, Phillip! Phillip

PS: I'm also CC'ing:

- Eslam (the author of the patch mentioned by Phillip)
- Karthik, Justin, Ayush, and Siddhart (possible mentors for
  "Improve the new git repo command")
- Patrick, who was my GSoC mentor and the person I first
  discussed with about --path-format

[1] fac60b8925 (rev-parse: add option for absolute or relative path formatting, 2020-12-13)

On 2026-02-28 at 22:05:54, Lucas Seiki Oshiro wrote:

I think you should provide both. I originally added this for things like `--git-common-dir`, which Git LFS would really like to have as an absolute path in the way that Git canonicalizes it, as well as potentially a relative path.

The reason is that the way Git canonicalizes things on Windows is not easily accessible on all systems or in all languages. For instance, Go has steadfastly refused to provide functionality for `GetFinalPathnameByHandle`, despite that being necessary to canonicalize the way Git does, so it's important to be able to get that information both in a relative way and as an absolute path.

On Unix, things are easier since there are fewer special file system objects and `realpath` or its equivalent are usually present in most languages.

With `git rev-parse`, you can change `--path-format` on the command line between options, so if you want both, you just request one thing, use `--path-format`, and then request the other. However, that can't be done with `git repo` and `--path-format`.

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Hmph, that is one advantage of that incremental option handling done by "rev-parse", which often is a source of confusion and complaints, though ;-)

On 3/3/26 00:38, Junio C Hamano wrote:

Short question: Is using format modifier like (%path:relative), (%path:absolute) a good solution here? I think it can be implemented by simply adding a path parsing function in ref-filter.c (and some other work that aren't particularly challenging).

It should be user-friendly, readable and free of global flags, right? :-]

Regards,

Yuchen

Tian Yuchen <a3205153416@gmail.com> writes:

What command are we talking about now? Is it a plumbing where predictability, simplicity and performance matters more than end-user friendliness?

I see your point here. but wouldn't this effectively be the same as Ayush's suggestion, just with a different syntax? Whether we use distinct keys (path.absolute.toplevel) or format modifiers (%(path:absolute)) It would still result in almost the same internals.

I don't think the syntax is a concern, even if both of them are equally verbose.

Coming to user friendliness I believe Junio has already raised an appropriate question.

Hi JAYATHEERTH,

In my view, this issue is actually to choose the most suitable tool for the job. After all, we don't want to use something like rev-parse, which is riddled with *ancient* technical debt, nor do we want to write an even more verbose parsing function from scratch for what you call verbose user input, right?

If I'm not mistaken, using different parsing functions to parse input is absolutely not just a matter of syntax differences. Instead, this will directly result in differences in data structures.

In ref-filter.c, we can easily see how Git parses format modifiers.

After the user input is parse by parse_ref_filter_atom(), it is then passed to the atom_valid[] static registry, which is like;

static struct {
	const char *name;
	info_source source;
	cmp_type cmp_type;
	int (*parser)(struct ref_format *format, struct used_atom *atom,
		      const char *arg, struct strbuf *err);
} valid_atom[] = {
	[ATOM_REFNAME] = { "refname", SOURCE_NONE, FIELD_STR, 
refname_atom_parser },
	[ATOM_OBJECTTYPE] = { "objecttype", SOURCE_OTHER, FIELD_STR, 
objecttype_atom_parser },
	[ATOM_OBJECTSIZE] = { "objectsize", SOURCE_OTHER, FIELD_ULONG, 
objectsize_atom_parser },
	[ATOM_OBJECTNAME] = { "objectname", SOURCE_OTHER, FIELD_STR, 
oid_atom_parser },
...

As you can see, each mapping relationship points to a parsing function (..._parser()). This parsing function is solely responsible for handling the state arg, fundamentally resolving the issue of function responsibility/naming confusion.

The reason I recommend this approach is because its implementation is incredibly clear and concise. To achieve the functionality we desire, all we need to do is add the following to the registry:

[ATOM_PATH] = { "path", SOURCE_NONE, FIELD_STR, path_atom_parser }

And the corresponding path_atom_parser().

This approach also offers strong scalability: If one day I decide to add a new feature like %(path:commondir,relative) output, all it would take is adding a switch statement in the parser() function (along with a few other minor tweaks).

*I'm not saying this approach is better than the solution you've discussed. I'm simply presenting a possible implementation for reference. (´～`)

This isn't a case of “you can't have your cake and eat it too,” right? I think user-friendliness can be achieved without compromising maintainability, predictability, or high performance in this case.

Regards,

Yuchen

On Tue, Mar 3, 2026 at 10:02 AM Tian Yuchen <a3205153416@gmail.com> wrote:

Hi Tian,

I agree that it provides a clean and scalable mechanism, especially in terms of extensibility and per-field formatting without relying on global flags.

To clarify my earlier comment: I wasn't arguing against ref-filter. In fact, I’m more inclined toward using the best tool for the job. My earlier point was mainly about behavioral similarity and how both belong to the same camp even though they might seem different.

That is a detailed mail, thanks for taking time

When I said similar I meant

something like this:

static const struct repo_info_field repo_info_field[] = {
    { "layout.bare", get_layout_bare },
    { "layout.shallow", get_layout_shallow },
    { "object.format", get_object_format },
    { "path.toplevel", get_path_toplevel },
};

This array contains all the keys You do not need to hardcode path.absolute.toplevel, path.relative.toplevel, etc., in the array...

Instead,

If the user asks for path.absolute.toplevel: You detect the absolute. middle part. strip it out to find the base key path.toplevel. You find path.toplevel in the aray, the array works with default values when entered --all

/*
 * Helper to parse the key variant.
 * Takes "path.absolute.git-dir" -> returns "path.git-dir" and sets
opts->format.
 */
static char *normalize_key(const char *raw_key, struct repo_info_opts *opts)
{
    const char *suffix;

    /* Check for "path.absolute." prefix */
    if (skip_prefix(raw_key, "path.absolute.", &suffix)) {
        opts->path_format = PATH_FORMAT_ABSOLUTE;
        return xstrfmt("path.%s", suffix);
    }

    /* Check for "path.relative." prefix */
    if (skip_prefix(raw_key, "path.relative.", &suffix)) {
        opts->path_format = PATH_FORMAT_RELATIVE;
        return xstrfmt("path.%s", suffix);
    }

    /* No variant found, return raw key as-is */
    return xstrdup(raw_key);
}

Structurally, this mimics the ref-filter parsing phase almost exactly. Just as ref-filter splits a compound atom like %(refname:short) into an identity (refname) and a modifier (short) to populate the handler's state, normalize_key splits path.absolute.git-dir into the identity (path.git-dir) and the modifier (absolute).

I just meant both the ideas are in the same camp just unrealized.

What do you think?

Regards
- Jayatheerth

Hi JAYATHEERTH,

Thanks for the reply.

 > I just meant both the ideas are in the same camp just unrealized.

That's exactly right. I was just reminding that there's a ready-made solution available that seems to work very well. Wouldn't reinventing something that already exists, with only minor differences, cause confusion? (´;ω;`)

I see. What you've written matches what you described — it essentially replicates the functionality of ref-filter.c. While I understand this is just a simple code implementation demo:

 >          opts->path_format = PATH_FORMAT_ABSOLUTE;

This implementation appears unable to support input like 'git repo-info --keys=path.absolute.toplevel,path.relative.gitdir', meaning it cannot handle multiple paths output from a single call as previously mentioned by Brain. The 'opts' here should be a global shared state, right?

I think it's better for the parser to allocate a separate memory for each arg it encounters. But then we'd be back to implementing something like struct used_atom, hahaha (ゝ∀･)

Thank you again for your email.

Yuchen

(I feel like we've been on this topic for too long. If you don't want to reply, you don't have to :-)

We create a fresh local_opts copy from the global_opts defaults for every single key:

for (int i = 0; i < argc; i++) {
    struct repo_info_opts local_opts = global_opts; /* Fresh reset */
    char *base_key = normalize_key(argv[i], &local_opts);

    /* ... find_field and get_value logic ... */
}

Since local_opts is local to the loop iteration, path.absolute.toplevel only modifies the state for that specific turn. When the loop moves to path.relative.gitdir, it gets a brand-new local_opts and starts over. It handles mixed formats in a single call perfectly, without any persistent _pollution_ or the need for complex heap allocations.

I agree we've covered a lot of ground here, so I'll leave it at that. Thanks for the great discussion ;)

Regards, Jayatheerth

Thanks for your input, brian!

It makes sense. If we use the key format suggested by Ayush [1] we could retrieve both values with something like

   $ git repo info path.git-dir.absolute path.git-dir.relative

I'll stop by now. Since many people are interested in contributing to git-repo-info in GSoC, I'll leave this decision to the person who will work on it, if there is one.

[1] B46AA932-28EF-4A2C-96B9-0F05D9641C1C@gmail.com