diffcore: add a pickaxe option to find a specific blob
Sometimes users are given a hash of an object and they want to
identify it further (ex.: Use verify-pack to find the largest blobs,
but what are these? or [1])
One might be tempted to extend git-describe to also work with blobs,
such that `git describe <blob-id>` gives a description as
'<commit-ish>:<path>'. This was implemented at [2]; as seen by the sheer
number of responses (>110), it turns out this is tricky to get right.
The hard part to get right is picking the correct 'commit-ish' as that
could be the commit that (re-)introduced the blob or the blob that
removed the blob; the blob could exist in different branches.
Junio hinted at a different approach of solving this problem, which this
patch implements. Teach the diff machinery another flag for restricting
the information to what is shown. For example:
$ ./git log --oneline --find-object=v2.0.0:Makefile b2feb64309 Revert the whole "ask curl-config" topic for now 47fbfded53 i18n: only extract comments marked with "TRANSLATORS:"
we observe that the Makefile as shipped with 2.0 was appeared in v1.9.2-471-g47fbfded53 and in v2.0.0-rc1-5-gb2feb6430b. The
reason why these commits both occur prior to v2.0.0 are evil
merges that are not found using this new mechanism.
Currently the check whether to perform pickaxing is done via checking
`diffopt->pickaxe`, which contains the command line argument that we
want to pickaxe for. Soon we'll introduce a new type of pickaxing, that
will not store anything in the `.pickaxe` field, so let's migrate the
check to be dependent on pickaxe_opts.
It is not enough to just replace the check for pickaxe by pickaxe_opts,
because flags might be set, but pickaxing was not requested ('-i').
To cope with that, introduce a mask to check only for the bits indicating
the modes of operation.
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
diff: migrate diff_flags.pickaxe_ignore_case to a pickaxe_opts bit
Currently flags for pickaxing are found in different places. Unify the
flags into the `pickaxe_opts` field, which will contain any pickaxe related
flags.
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
The set of paths output from "git status --ignored" was tied
closely with its "--untracked=<mode>" option, but now it can be
controlled more flexibly. Most notably, a directory that is
ignored because it is listed to be ignored in the ignore/exclude
mechanism can be handled differently from a directory that ends up
to be ignored only because all files in it are ignored.
* jm/status-ignored-files-list:
status: test ignored modes
status: document options to show matching ignored files
status: report matching ignored and normal untracked
status: add option to show ignored files differently
* js/mingw-redirect-std-handles:
mingw: document the standard handle redirection
mingw: optionally redirect stderr/stdout via the same handle
mingw: add experimental feature to redirect standard handles
The credential helper for libsecret (in contrib/) has been improved
to allow possibly prompting the end user to unlock secrets that are
currently locked (otherwise the secrets may not be loaded).
A single-word "unsigned flags" in the diff options is being split
into a structure with many bitfields.
* bw/diff-opt-impl-to-bitfields:
diff: make struct diff_flags members lowercase
diff: remove DIFF_OPT_CLR macro
diff: remove DIFF_OPT_SET macro
diff: remove DIFF_OPT_TST macro
diff: remove touched flags
diff: add flag to indicate textconv was set via cmdline
diff: convert flags to be stored in bitfields
add, reset: use DIFF_OPT_SET macro to set a diff flag
"git stash save" has been deprecated in favour of "git stash push".
* tg/deprecate-stash-save:
stash: remove now superfluos help for "stash push"
stash: mark "git stash save" deprecated in the man page
stash: replace "git stash save" with "git stash push" in the documentation
"git fetch --recurse-submodules" now knows that submodules can be
moved around in the superproject in addition to getting updated,
and finds the ones that need to be fetched accordingly.
* hv/fetch-moved-submodules-on-demand:
submodule: simplify decision tree whether to or not to fetch
implement fetching of moved submodules
fetch: add test to make sure we stay backwards compatible
"git check-ref-format --branch @{-1}" bit a "BUG()" when run
outside a repository for obvious reasons; clarify the documentation
and make sure we do not even try to expand the at-mark magic in
such a case, but still call the validation logic for branch names.
* jc/check-ref-format-oor:
check-ref-format doc: --branch validates and expands <branch>
check-ref-format --branch: strip refs/heads/ using skip_prefix
check-ref-format --branch: do not expand @{...} outside repository
Optimize the code to find shortest unique prefix of object names.
* ds/find-unique-abbrev-optim:
sha1_name: minimize OID comparisons during disambiguation
sha1_name: parse less while finding common prefix
sha1_name: unroll len loop in find_unique_abbrev_r()
p4211-line-log.sh: add log --online --raw --parents perf test
* pc/submodule-helper:
submodule: port submodule subcommand 'status' from shell to C
submodule--helper: introduce for_each_listed_submodule()
submodule--helper: introduce get_submodule_displaypath()
An early part of piece-by-piece rewrite of "git bisect".
* pb/bisect-helper:
bisect--helper: `is_expected_rev` & `check_expected_revs` shell function in C
t6030: explicitly test for bisection cleanup
bisect--helper: `bisect_clean_state` shell function in C
bisect--helper: `write_terms` shell function in C
bisect--helper: rewrite `check_term_format` shell function in C
bisect--helper: use OPT_CMDMODE instead of OPT_BOOL
A hook script that is set unexecutable is simply ignored. Git
notifies when such a file is ignored, unless the message is
squelched via advice.ignoredHook configuration.
* dm/run-command-ignored-hook-advise:
run-command: add hint when a hook is ignored
The final step to make an empty string as a pathspec element
illegal. We started this by first deprecating and warning a
pathspec that has such an element in 2.11 (Nov 2016).
Hopefully we can merge this down to the 'master' by the end of the
year? A deprecation warning period that is about 1 year does not
sound too bad.
* ex/deprecate-empty-pathspec-as-match-all:
pathspec: die on empty strings as pathspec
t0027: do not use an empty string as a pathspec element
"git status --ignored -u" did not stop at a working tree of a
separate project that is embedded in an ignored directory and
listed files in that other project, instead of just showing the
directory itself as ignored.
* js/submodule-in-excluded:
status: do not get confused by submodules in excluded directories
Instead of using custom line comparison and hashing functions to
implement "moved lines" coloring in the diff output, use the pair
of these functions from lower-layer xdiff/ code.
* sb/diff-color-moved-use-xdl-recmatch:
diff.c: get rid of duplicate implementation
xdiff-interface: export comparing and hashing strings
The experimental "color moved lines differently in diff output"
feature was buggy around "ignore whitespace changes" edges, whihch
has been corrected.
* jk/diff-color-moved-fix:
diff: handle NULs in get_string_hash()
diff: fix whitespace-skipping with --color-moved
t4015: test the output of "diff --color-moved -b"
t4015: check "negative" case for "-w --color-moved"
t4015: refactor --color-moved whitespace test
"auto" as a value for the columnar output configuration ought to
judge "is the output consumed by humans?" with the same criteria as
"auto" for coloured output configuration, i.e. either the standard
output stream is going to tty, or a pager is in use. We forgot the
latter, which has been fixed.
* kd/auto-col-with-pager-fix:
column: do not include pager.c
column: show auto columns when pager is active
An earlier update made it possible to use an on-stack in-core
lockfile structure (as opposed to having to deliberately leak an
on-heap one). Many codepaths have been updated to take advantage
of this new facility.
* ma/lockfile-fixes:
read_cache: roll back lock in `update_index_if_able()`
read-cache: leave lock in right state in `write_locked_index()`
read-cache: drop explicit `CLOSE_LOCK`-flag
cache.h: document `write_locked_index()`
apply: remove `newfd` from `struct apply_state`
apply: move lockfile into `apply_state`
cache-tree: simplify locking logic
checkout-index: simplify locking logic
tempfile: fix documentation on `delete_tempfile()`
lockfile: fix documentation on `close_lock_file_gently()`
treewide: prefer lockfiles on the stack
sha1_file: do not leak `lock_file`
The options are currently only referenced by the git-blame man page,
also explain them in git-config, which is the canonical page to
contain all config options.
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Credentials exposed by the secret service DBUS interface may be locked.
Setting the SECRET_SEARCH_UNLOCK flag will make the secret service
unlock these secrets, possibly prompting the user for credentials to do
so. Without this flag, the secret is simply not loaded.
Signed-off-by: Dennis Kaarsemaker <dennis@kaarsemaker.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Andrew Baumann reported that when called outside of any Git worktree,
`git rev-parse --is-inside-work-tree` eventually tries to access
`//HEAD`, i.e. any `HEAD` file in the root directory, but with a double
slash.
This double slash is not only unintentional, but is allowed by the POSIX
standard to have a special meaning. And most notably on Windows, it
does, where it refers to a UNC path of the form `//server/share/`.
As a consequence, afore-mentioned `rev-parse` call not only looks for
the wrong thing, but it also causes serious delays, as Windows will try
to access a server called `HEAD`. Let's simply avoid the unintended
double slash.
Signed-off-by: Jeff King <peff@peff.net> Acked-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This feature has been in Git for Windows since v2.11.0(2), as an
experimental option. Now it is considered mature, and it is high time to
document it properly.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
mingw: optionally redirect stderr/stdout via the same handle
The "2>&1" notation in Powershell and in Unix shells implies that stderr
is redirected to the same handle into which stdout is already written.
Let's use this special value to allow the same trick with
GIT_REDIRECT_STDERR and GIT_REDIRECT_STDOUT: if the former's value is
`2>&1`, then stderr will simply be written to the same handle as stdout.
The functionality was suggested by Jeff Hostetler.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
mingw: add experimental feature to redirect standard handles
Particularly when calling Git from applications, such as Visual Studio's
Team Explorer, it is important that stdin/stdout/stderr are closed
properly. However, when spawning processes on Windows, those handles
must be marked as inheritable if we want to use them, but that flag is a
global flag and may very well be used by other spawned processes which
then do not know to close those handles.
Let's introduce a set of environment variables (GIT_REDIRECT_STDIN and
friends) that specify paths to files, or even better, named pipes (which
are similar to Unix sockets) and that are used by the spawned Git
process. This helps work around above-mentioned issue: those named
pipes will be opened in a non-inheritable way upon startup, and no
handles are passed around (and therefore no inherited handles need to be
closed by any spawned child).
This feature shipped with Git for Windows (marked as experimental) since
v2.11.0(2), so it has seen some serious testing in the meantime.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
travis-ci: don't build Git for the static analysis job
The static analysis job on Travis CI builds Git ever since it was
introduced in d8245bb3f (travis-ci: add static analysis build job to
run coccicheck, 2017-04-11). However, Coccinelle, the only static
analysis tool in use, only needs Git's source code to work and it
doesn't care about built Git binaries at all.
Spare some of Travis CI's resources and don't build Git for the static
analysis job unnecessarily.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
travis-ci: fix running P4 and Git LFS tests in Linux build jobs
Linux build jobs on Travis CI skip the P4 and Git LFS tests since
commit 657343a60 (travis-ci: move Travis CI code into dedicated
scripts, 2017-09-10), claiming there are no P4 or Git LFS installed.
The reason is that P4 and Git LFS binaries are not installed to a
directory in the default $PATH, but their directories are prepended to
$PATH. This worked just fine before said commit, because $PATH was
set in a scriptlet embedded in our '.travis.yml', thus its new value
was visible during the rest of the build job. However, after these
embedded scriptlets were moved into dedicated scripts executed in
separate shell processes, any variable set in one of those scripts is
only visible in that single script but not in any of the others. In
this case, 'ci/install-dependencies.sh' downloads P4 and Git LFS and
modifies $PATH, but to no effect, because 'ci/run-tests.sh' only sees
Travis CI's default $PATH.
Move adjusting $PATH to 'ci/lib-travisci.sh', which is sourced in all
other 'ci/' scripts, so all those scripts will see the updated $PATH
value.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
With --recurse-submodules, we add each submodule that we encounter to
the list of alternate object databases. With threading, our changes to
the list are not protected against races. Indeed, ThreadSanitizer
reports a race when we call `add_to_alternates_memory()` around the same
time that another thread is reading in the list through
`read_sha1_file()`.
Take the grep read-lock while adding the submodule. The lock is used to
serialize uses of non-thread-safe parts of Git's API, including
`read_sha1_file()`.
Helped-by: Brandon Williams <bmwill@google.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Acked-by: Brandon Williams <bmwill@google.com> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
When we replaced the old shell script based interactive rebase in
commmit 18633e1a22a6 ("rebase -i: use the rebase--helper builtin",
2017-02-09) we introduced a regression of functionality in that the
GIT_DIR would be sent to the environment of the exec command as-is.
This generally meant that it would be passed as "GIT_DIR=.git", which
causes problems for any exec command that wants to run git commands in
a subdirectory.
This isn't a very large regression, since it is not that likely that the
exec command will run a git command, and even less likely that it will
need to do so in a subdir. This regression was discovered by a build
system which uses git-describe to find the current version of the build
system, and happened to do so from the src/ sub directory of the
project.
Fix this by passing in the absolute path of the git directory into the
child environment.
Signed-off-by: Jacob Keller <jacob.keller@gmail.com> Acked-by: Johannes Schindelin <Johannes.Schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Empty (length 0) usernames and/or passwords, when saved in the Windows
Credential Manager, come back as null when reading the credential.
One use case for such empty credentials is with NTLM authentication, where
empty username and password instruct libcurl to authenticate using the
credentials of the currently logged-on user (single sign-on).
When locating the relevant credentials, make empty username match null.
When outputting the credentials, handle nulls correctly.
Signed-off-by: Jakub Bereżański <kuba@berezanscy.pl> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make sure the helper does not crash when blank username and password is
provided. If the helper can save such credentials, it should be able to
read them back.
Signed-off-by: Jakub Bereżański <kuba@berezanscy.pl> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Now that the flags stored in struct diff_flags are being accessed
directly and not through macros, change all struct members from being
uppercase to lowercase.
This conversion is done using the following semantic patch:
diff: add flag to indicate textconv was set via cmdline
git-show is unique in that it wants to use textconv by default except
for when it is showing blobs. When asked to show a blob, show doesn't
want to use textconv unless the user explicitly requested that it be
used by providing the command line flag '--textconv'.
Currently this is done by using a parallel set of 'touched' flags which
get set every time a particular flag is set or cleared. In a future
patch we want to eliminate this parallel set of flags so instead of
relying on if the textconv flag has been touched, add a new flag
'TEXTCONV_SET_VIA_CMDLINE' which is only set if textconv is set to true
via the command line.
Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
We cannot add many more flags to the diff machinery due to the
limitations of the number of flags that can be stored in a single
unsigned int. In order to allow for more flags to be added to the diff
machinery in the future this patch converts the flags to be stored in
bitfields in 'struct diff_flags'.
Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
t5580 tests that specifying Windows UNC paths works with Git. Cygwin
supports UNC paths, albeit only using forward slashes, not backslashes,
so run the compatible tests on Cygwin as well as MinGW.
The only complication is Cygwin's `pwd`, which returns a *nix-style
path, and that's not suitable for calculating the UNC path to the
current directory. Instead use Cygwin's `cygpath` utility to get the
Windows-style path.
Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org> Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
The path of a loose object contains its hash value encoded into two
substrings of 2 and 38 hexadecimal digits separated by a slash. The
first part is handed to for_each_file_in_obj_subdir() in decoded form as
subdir_nr. The current code builds a full hexadecimal representation of
the hash in a temporary buffer, then uses get_oid_hex() to decode it.
Avoid the intermediate step by taking subdir_nr as-is and using
hex_to_bytes() directly on the second substring. That's shorter and
easier.
Signed-off-by: Rene Scharfe <l.s.r@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
The path of a loose object contains its hash value encoded into two
substrings of hexadecimal digits, separated by a slash. The current
code copies the pieces into a temporary buffer to get rid of the slash
and then uses get_oid_hex() to decode the hash value.
Avoid the copy by using hex_to_bytes() directly on the substrings.
That's shorter and easier.
While at it correct the length of the second substring in a comment.
Signed-off-by: Rene Scharfe <l.s.r@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
status: add option to show ignored files differently
Teach the status command more flexibility in how ignored files are
reported. Currently, the reporting of ignored files and untracked
files are linked. You cannot control how ignored files are reported
independently of how untracked files are reported (i.e. `all` vs
`normal`). This makes it impossible to show untracked files with the
`all` option, but show ignored files with the `normal` option.
This work 1) adds the ability to control the reporting of ignored
files independently of untracked files and 2) introduces the concept
of status reporting ignored paths that explicitly match an ignored
pattern. There are 2 benefits to these changes: 1) if a consumer needs
all untracked files but not all ignored files, there is a performance
benefit to not scanning all contents of an ignored directory and 2)
returning ignored files that explicitly match a path allow a consumer
to make more informed decisions about when a status result might be
stale.
This commit implements --ignored=matching with --untracked-files=all.
The following commit will implement --ignored=matching with
--untracked=files=normal.
As an example of where this flexibility could be useful is that our
application (Visual Studio) runs the status command and presents the
output. It shows all untracked files individually (e.g. using the
'--untracked-files==all' option), and would like to know about which
paths are ignored. It uses information about ignored paths to make
decisions about when the status result might have changed.
Additionally, many projects place build output into directories inside
a repository's working directory (e.g. in "bin/" and "obj/"
directories). Normal usage is to explicitly ignore these 2 directory
names in the .gitignore file (rather than or in addition to the *.obj
pattern).If an application could know that these directories are
explicitly ignored, it could infer that all contents are ignored as
well and make better informed decisions about files in these
directories. It could infer that any changes under these paths would
not affect the output of status. Additionally, there can be a
significant performance benefit by avoiding scanning through ignored
directories.
When status is set to report matching ignored files, it has the
following behavior. Ignored files and directories that explicitly
match an exclude pattern are reported. If an ignored directory matches
an exclude pattern, then the path of the directory is returned. If a
directory does not match an exclude pattern, but all of its contents
are ignored, then the contained files are reported instead of the
directory.
Signed-off-by: Jameson Miller <jamill@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
t0000: check whether the shell supports the "local" keyword
Add a test balloon to see if we get complaints from anybody who is
using a shell that doesn't support the "local" keyword. If so, this
test can be reverted. If not, we might want to consider using "local"
in shell code throughout the git code base.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
diff: fix lstat() error handling in diff_populate_filespec()
Add lstat() error handling not only for ENOENT case.
Otherwise uninitialised 'struct stat st' variable is used later in case of
lstat() non-ENOENT failure which leads to processing of rubbish values of
file mode ('S_ISLNK(st.st_mode)' check) or size ('xsize_t(st.st_size)').
Signed-off-by: Andrey Okoshkin <a.okoshkin@samsung.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
rev-list-options.txt: use correct directional reference
The descriptions of the options '--parents', '--children' and
'--graph' say "see 'History Simplification' below", although the
referred section is in fact above the description of these options.
Send readers in the right direction by saying "above" instead of
"below".
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
stash: remove now superfluos help for "stash push"
With the 'git stash save' interface, it was easily possible for users to
try to add a message which would start with "-", which 'git stash save'
would interpret as a command line argument, and fail. For this case we
added some extra help on how to create a stash with a message starting
with "-".
For 'stash push', messages are passed with the -m flag, avoiding this
potential pitfall. Now only pathspecs starting with "-" would have to
be distinguished from command line parameters by using
"-- --<pathspec>". This is fairly common in the git command line
interface, and we don't try to guess what the users wanted in the other
cases.
Because this way of passing pathspecs is quite common in other git
commands, and we don't provide any extra help there, do the same in the
error message for 'git stash push'.
Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
stash: mark "git stash save" deprecated in the man page
'git stash push' fixes a historical wart in the interface of 'git stash
save'. As 'git stash push' has all functionality of 'git stash save',
with a nicer, more consistent user interface deprecate 'git stash
save'. To do this, remove it from the synopsis of the man page, and
move it to a separate section, stating that it is deprecated.
Helped-by: Robert P. J. Day <rpjday@crashcourse.ca> Helped-by: Jeff King <peff@peff.net> Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
stash: replace "git stash save" with "git stash push" in the documentation
"git stash push" is the newer interface for creating a stash. While we
are still keeping "git stash save" around for the time being, it's better
to point new users of "git stash" to the more modern (and more feature
rich) interface, instead of teaching them the older version that we
might want to phase out in the future.
Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
status: do not get confused by submodules in excluded directories
We meticulously pass the `exclude` flag to the `treat_directory()`
function so that we can indicate that files in it are excluded rather
than untracked when recursing.
But we did not yet treat submodules the same way.
Because of that, `git status --ignored --untracked` with a submodule
`submodule` in a gitignored `tracked/` would show the submodule in the
"Untracked files" section, e.g.
On branch master
Untracked files:
(use "git add <file>..." to include in what will be committed)
tracked/submodule/
Ignored files:
(use "git add -f <file>..." to include in what will be committed)
tracked/submodule/initial.t
Instead, we would want it to show the submodule in the "Ignored files"
section:
On branch master
Ignored files:
(use "git add -f <file>..." to include in what will be committed)
tracked/submodule/
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
The implementations in diff.c to detect moved lines needs to compare
strings and hash strings, which is implemented in that file, as well
as in the xdiff library.
Remove the rather recent implementation in diff.c and rely on the well
exercised code in the xdiff lib.
With this change the hash used for bucketing the strings for the moved
line detection changes from FNV32 (that is provided via the hashmaps
memhash) to DJB2 (which is used internally in xdiff). Benchmarks found
on the web[1] do not indicate that these hashes are different in
performance for readable strings.
xdiff-interface: export comparing and hashing strings
This will turn out to be useful in a later patch.
xdl_recmatch is exported in xdiff/xutils.h, to be used by various
xdiff/*.c files, but not outside of xdiff/. This one makes it available
to the outside, too.
While at it, add documentation.
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>