git/Documentation/git-rev-parse.txt, branch v2.41.2

fetch: support hideRefs to speed up connectivity checks

2023-02-27T17:27:03Z

With roughly 800 remotes all fetching into their own refs/remotes/$REMOTE/* island, the connectivity check[1] gets expensive for each fetch on systems which lack sufficient RAM to cache objects. To do a no-op fetch on one $REMOTE out of hundreds, hideRefs now allows the no-op fetch to take ~30 seconds instead of ~20 minutes on a noisy, RAM-constrained machine (localhost, so no network latency): git -c fetch.hideRefs=refs \ -c fetch.hideRefs='!refs/remotes/$REMOTE/' \ fetch $REMOTE [1] `git rev-list --objects --stdin --not --all --quiet --alternate-refs' Signed-off-by: Eric Wong Signed-off-by: Junio C Hamano

rev-parse: add `--exclude-hidden=` option

2022-11-17T21:22:52Z

Add a new `--exclude-hidden=` option that is similar to the one we just added to git-rev-list(1). Given a section name `uploadpack` or `receive` as argument, it causes us to exclude all references that would be hidden by the respective `$section.hideRefs` configuration. Signed-off-by: Patrick Steinhardt Signed-off-by: Taylor Blau

rev-parse: add option for absolute or relative path formatting

2020-12-13T07:35:51Z

git rev-parse has several options which print various paths. Some of these paths are printed relative to the current working directory, and some are absolute. Normally, this is not a problem, but there are times when one wants paths entirely in one format or another. This can be done trivially if the paths are canonical, but canonicalizing paths is not possible on some shell scripting environments which lack realpath(1) and also in Go, which lacks functions that properly canonicalize paths on Windows. To help out the scripter, let's provide an option which turns most of the paths printed by git rev-parse to be either relative to the current working directory or absolute and canonical. Document which options are affected and which are not so that users are not confused. This approach is cleaner and tidier than providing duplicates of existing options which are either relative or absolute. Note that if the user needs both forms, it is possible to pass an additional option in the middle of the command line which changes the behavior of subsequent operations. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

rev-parse: handle --end-of-options

2020-11-10T21:46:27Z

We taught rev-list a new way to separate options from revisions in 19e8789b23 (revision: allow --end-of-options to end option parsing, 2019-08-06), but rev-parse uses its own parser. It should know about --end-of-options not only for consistency, but because it may be presented with similarly ambiguous cases. E.g., if a caller does: git rev-parse "$rev" -- "$path" to parse an untrusted input, then it will get confused if $rev contains an option-like string like "--local-env-vars". Or even "--not-real", which we'd keep as an option to pass along to rev-list. Or even more importantly: git rev-parse --verify "$rev" can be confused by options, even though its purpose is safely parsing untrusted input. On the plus side, it will always fail the --verify part, as it will not have parsed a revision, so the caller will generally "fail closed" rather than continue to use the untrusted string. But it will still trigger whatever option was in "$rev"; this should be mostly harmless, since rev-parse options are all read-only, but I didn't carefully audit all paths. This patch lets callers write: git rev-parse --end-of-options "$rev" -- "$path" and: git rev-parse --verify --end-of-options "$rev" which will both treat "$rev" always as a revision parameter. The latter is a bit clunky. It would be nicer if we had defined "--verify" to require that its next argument be the revision. But we have not historically done so, and: git rev-parse --verify -q "$rev" does currently work. I added a test here to confirm that we didn't break that. A few implementation notes: - We don't document --end-of-options explicitly in commands, but rather in gitcli(7). So I didn't give it its own section in git-rev-parse(1). But I did call it out specifically in the --verify section, and include it in the examples, which should show best practices. - We don't have to re-indent the main option-parsing block, because we can combine our "did we see end of options" check with "does it start with a dash". The exception is the pre-setup options, which need their own block. - We do however have to pull the "--" parsing out of the "does it start with dash" block, because we want to parse it even if we've seen --end-of-options. - We'll leave "--end-of-options" in the output. This is probably not technically necessary, as a careful caller will do: git rev-parse --end-of-options $revs -- $paths and anything in $revs will be resolved to an object id. However, it does help a slightly less careful caller like: git rev-parse --end-of-options $revs_or_paths where a path "--foo" will remain in the output as long as it also exists on disk. In that case, it's helpful to retain --end-of-options to get passed along to rev-list, s it would otherwise see just "--foo". Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

rev-parse: make --show-toplevel without a worktree an error

2019-11-20T01:19:58Z

Ever since it was introduced in 7cceca5ccc (Add 'git rev-parse --show-toplevel' option., 2010-01-12), the --show-toplevel option has treated a missing working tree as a quiet success: it neither prints a toplevel path, but nor does it report any kind of error. While a caller could distinguish this case by looking for an empty response, the behavior is rather confusing. We're better off complaining that there is no working tree, as other internal commands would do in similar cases (e.g., "git status" or any builtin with NEED_WORK_TREE set would just die()). So let's do the same here. While we're at it, let's clarify the documentation and add some tests, both for the new behavior and for the more mundane case (which was not covered). Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

rev-parse: add a --show-object-format option

2019-10-28T02:34:57Z

Add an option to print the object format used for input, output, or storage. This allows shell scripts to discover the hash algorithm in use. Since the transition plan allows for multiple input algorithms, document that we may provide multiple results for input, and the format that the results may take. While we don't support this now, documenting it early means that script authors can future-proof their scripts for when we do. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

Use proper syntax for replaceables in command docs

2018-05-25T08:16:47Z

The standard for command documentation synopses appears to be: [...] means optional <...> means replaceable [<...>] means both optional and replaceable So fix a number of doc pages that use incorrect variations of the above. Signed-off-by: Robert P. J. Day Signed-off-by: Junio C Hamano

Merge branch 'sb/rev-parse-show-superproject-root'

2017-10-28T01:18:40Z

Doc markup fix. * sb/rev-parse-show-superproject-root: docs: fix formatting of rev-parse's --show-superproject-working-tree

docs: fix formatting of rev-parse's --show-superproject-working-tree

2017-10-27T01:31:46Z

Signed-off-by: Sebastian Schuberth Signed-off-by: Junio C Hamano

rev-parse: rev-parse: add --is-shallow-repository

2017-09-19T03:16:28Z

Running `git fetch --unshallow` on a repo that is not in fact shallow produces a fatal error message. Add a helper to rev-parse that scripters can use to determine whether a repo is shallow or not. Signed-off-by: Øystein Walle Reviewed-by: Jonathan Nieder Signed-off-by: Junio C Hamano