2008-06-06 07:07:32 +00:00
|
|
|
git(1)
|
2005-05-10 21:32:30 +00:00
|
|
|
======
|
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
|
|
|
git - the stupid content tracker
|
|
|
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2006-08-25 01:05:48 +00:00
|
|
|
[verse]
|
2022-03-31 21:27:09 +00:00
|
|
|
'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
|
2012-02-14 23:54:21 +00:00
|
|
|
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
|
git: add -P as a short option for --no-pager
It is possible to configure 'less', the pager, to use an alternate
screen to show the content, for example, by setting LESS=RS in the
environment. When it is closed in this configuration, it switches
back to the original screen, and all content is gone.
It is not uncommon to request that the output remains visible in
the terminal. For this, the option --no-pager can be used. But
it is a bit cumbersome to type, even when command completion is
available. Provide a short option, -P, to make the option more
easily accessible.
Signed-off-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-03 17:15:08 +00:00
|
|
|
[-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
|
2011-07-08 23:14:10 +00:00
|
|
|
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
|
read-tree: add "--super-prefix" option, eliminate global
The "--super-prefix" option to "git" was initially added in [1] for
use with "ls-files"[2], and shortly thereafter "submodule--helper"[3]
and "grep"[4]. It wasn't until [5] that "read-tree" made use of it.
At the time [5] made sense, but since then we've made "ls-files"
recurse in-process in [6], "grep" in [7], and finally
"submodule--helper" in the preceding commits.
Let's also remove it from "read-tree", which allows us to remove the
option to "git" itself.
We can do this because the only remaining user of it is the submodule
API, which will now invoke "read-tree" with its new "--super-prefix"
option. It will only do so when the "submodule_move_head()" function
is called.
That "submodule_move_head()" function was then only invoked by
"read-tree" itself, but now rather than setting an environment
variable to pass "--super-prefix" between cmd_read_tree() we:
- Set a new "super_prefix" in "struct unpack_trees_options". The
"super_prefixed()" function in "unpack-trees.c" added in [5] will now
use this, rather than get_super_prefix() looking up the environment
variable we set earlier in the same process.
- Add the same field to the "struct checkout", which is only needed to
ferry the "super_prefix" in the "struct unpack_trees_options" all the
way down to the "entry.c" callers of "submodule_move_head()".
Those calls which used the super prefix all originated in
"cmd_read_tree()". The only other caller is the "unlink_entry()"
caller in "builtin/checkout.c", which now passes a "NULL".
1. 74866d75793 (git: make super-prefix option, 2016-10-07)
2. e77aa336f11 (ls-files: optionally recurse into submodules, 2016-10-07)
3. 89c86265576 (submodule helper: support super prefix, 2016-12-08)
4. 0281e487fd9 (grep: optionally recurse into submodules, 2016-12-16)
5. 3d415425c7b (unpack-trees: support super-prefix option, 2017-01-17)
6. 188dce131fa (ls-files: use repository object, 2017-06-22)
7. f9ee2fcdfa0 (grep: recurse in-process using 'struct repository', 2017-08-02)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-12-20 12:39:56 +00:00
|
|
|
[--config-env=<name>=<envvar>] <command> [<args>]
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
2006-04-02 21:54:34 +00:00
|
|
|
Git is a fast, scalable, distributed revision control system with an
|
|
|
|
unusually rich command set that provides both high-level operations
|
|
|
|
and full access to internals.
|
|
|
|
|
2008-06-30 22:01:21 +00:00
|
|
|
See linkgit:gittutorial[7] to get started, then see
|
2014-10-10 21:25:37 +00:00
|
|
|
linkgit:giteveryday[7] for a useful minimum set of
|
2012-08-17 19:48:52 +00:00
|
|
|
commands. The link:user-manual.html[Git User's Manual] has a more
|
|
|
|
in-depth introduction.
|
2005-11-15 23:31:25 +00:00
|
|
|
|
2012-08-17 19:48:52 +00:00
|
|
|
After you mastered the basic concepts, you can come back to this
|
2013-01-21 19:17:53 +00:00
|
|
|
page to learn what commands Git offers. You can learn more about
|
|
|
|
individual Git commands with "git help command". linkgit:gitcli[7]
|
2014-05-21 18:52:26 +00:00
|
|
|
manual page gives you an overview of the command-line command syntax.
|
2006-06-07 18:43:50 +00:00
|
|
|
|
2016-06-22 17:38:25 +00:00
|
|
|
A formatted and hyperlinked copy of the latest Git documentation
|
2019-05-15 22:47:09 +00:00
|
|
|
can be viewed at https://git.github.io/htmldocs/git.html
|
|
|
|
or https://git-scm.com/docs.
|
2007-04-30 11:21:38 +00:00
|
|
|
|
2007-02-13 23:15:05 +00:00
|
|
|
|
2005-11-15 23:31:25 +00:00
|
|
|
OPTIONS
|
|
|
|
-------
|
2022-03-31 21:27:09 +00:00
|
|
|
-v::
|
2005-11-15 23:31:25 +00:00
|
|
|
--version::
|
2013-01-21 19:17:53 +00:00
|
|
|
Prints the Git suite version that the 'git' program came from.
|
2021-09-14 13:27:18 +00:00
|
|
|
+
|
2021-10-24 17:08:20 +00:00
|
|
|
This option is internally converted to `git version ...` and accepts
|
2021-09-14 13:27:18 +00:00
|
|
|
the same options as the linkgit:git-version[1] command. If `--help` is
|
|
|
|
also given, it takes precedence over `--version`.
|
2005-11-15 23:31:25 +00:00
|
|
|
|
2022-03-31 21:27:09 +00:00
|
|
|
-h::
|
2005-11-15 23:31:25 +00:00
|
|
|
--help::
|
2006-03-09 16:24:19 +00:00
|
|
|
Prints the synopsis and a list of the most commonly used
|
2016-06-28 11:40:11 +00:00
|
|
|
commands. If the option `--all` or `-a` is given then all
|
2013-01-21 19:17:53 +00:00
|
|
|
available commands are printed. If a Git command is named this
|
2007-12-04 05:44:29 +00:00
|
|
|
option will bring up the manual page for that command.
|
2007-12-04 05:44:29 +00:00
|
|
|
+
|
|
|
|
Other options are available to control how the manual page is
|
2007-12-29 06:20:38 +00:00
|
|
|
displayed. See linkgit:git-help[1] for more information,
|
2008-07-03 06:06:23 +00:00
|
|
|
because `git --help ...` is converted internally into `git
|
|
|
|
help ...`.
|
2005-11-15 23:31:25 +00:00
|
|
|
|
2013-09-09 13:47:43 +00:00
|
|
|
-C <path>::
|
|
|
|
Run as if git was started in '<path>' instead of the current working
|
|
|
|
directory. When multiple `-C` options are given, each subsequent
|
|
|
|
non-absolute `-C <path>` is interpreted relative to the preceding `-C
|
2019-06-29 08:24:57 +00:00
|
|
|
<path>`. If '<path>' is present but empty, e.g. `-C ""`, then the
|
|
|
|
current working directory is left unchanged.
|
2013-09-09 13:47:43 +00:00
|
|
|
+
|
|
|
|
This option affects options that expect path name like `--git-dir` and
|
|
|
|
`--work-tree` in that their interpretations of the path names would be
|
|
|
|
made relative to the working directory caused by the `-C` option. For
|
|
|
|
example the following invocations are equivalent:
|
|
|
|
|
|
|
|
git --git-dir=a.git --work-tree=b -C c status
|
|
|
|
git --git-dir=c/a.git --work-tree=c/b status
|
|
|
|
|
2010-03-26 22:53:57 +00:00
|
|
|
-c <name>=<value>::
|
|
|
|
Pass a configuration parameter to the command. The value
|
|
|
|
given will override values from configuration files.
|
|
|
|
The <name> is expected in the same format as listed by
|
|
|
|
'git config' (subkeys separated by dots).
|
2014-08-04 22:40:19 +00:00
|
|
|
+
|
|
|
|
Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
|
|
|
|
`foo.bar` to the boolean true value (just like `[foo]bar` would in a
|
|
|
|
config file). Including the equals but with an empty value (like `git -c
|
2017-09-28 14:06:48 +00:00
|
|
|
foo.bar= ...`) sets `foo.bar` to the empty string which `git config
|
2018-09-19 16:38:18 +00:00
|
|
|
--type=bool` will convert to `false`.
|
2010-03-26 22:53:57 +00:00
|
|
|
|
2021-01-12 12:26:45 +00:00
|
|
|
--config-env=<name>=<envvar>::
|
|
|
|
Like `-c <name>=<value>`, give configuration variable
|
|
|
|
'<name>' a value, where <envvar> is the name of an
|
|
|
|
environment variable from which to retrieve the value. Unlike
|
|
|
|
`-c` there is no shortcut for directly setting the value to an
|
|
|
|
empty string, instead the environment variable itself must be
|
|
|
|
set to the empty string. It is an error if the `<envvar>` does not exist
|
|
|
|
in the environment. `<envvar>` may not contain an equals sign
|
2021-02-17 19:56:05 +00:00
|
|
|
to avoid ambiguity with `<name>` containing one.
|
2021-01-12 12:26:45 +00:00
|
|
|
+
|
|
|
|
This is useful for cases where you want to pass transitory
|
2023-10-05 09:00:51 +00:00
|
|
|
configuration options to git, but are doing so on operating systems
|
|
|
|
where other processes might be able to read your command line
|
|
|
|
(e.g. `/proc/self/cmdline`), but not your environment
|
2021-01-12 12:26:45 +00:00
|
|
|
(e.g. `/proc/self/environ`). That behavior is the default on
|
|
|
|
Linux, but may not be on your system.
|
|
|
|
+
|
|
|
|
Note that this might add security for variables such as
|
|
|
|
`http.extraHeader` where the sensitive information is part of
|
|
|
|
the value, but not e.g. `url.<base>.insteadOf` where the
|
|
|
|
sensitive information can be part of the key.
|
|
|
|
|
2010-10-08 17:31:15 +00:00
|
|
|
--exec-path[=<path>]::
|
2013-01-21 19:17:53 +00:00
|
|
|
Path to wherever your core Git programs are installed.
|
2005-11-15 23:31:25 +00:00
|
|
|
This can also be controlled by setting the GIT_EXEC_PATH
|
2008-07-03 05:08:12 +00:00
|
|
|
environment variable. If no path is given, 'git' will print
|
2005-11-15 23:31:25 +00:00
|
|
|
the current setting and then exit.
|
|
|
|
|
2009-04-05 02:15:16 +00:00
|
|
|
--html-path::
|
2013-01-21 19:17:53 +00:00
|
|
|
Print the path, without trailing slash, where Git's HTML
|
2011-05-02 06:07:45 +00:00
|
|
|
documentation is installed and exit.
|
2009-04-05 02:15:16 +00:00
|
|
|
|
2011-05-01 08:16:25 +00:00
|
|
|
--man-path::
|
2011-05-02 06:07:45 +00:00
|
|
|
Print the manpath (see `man(1)`) for the man pages for
|
2013-01-21 19:17:53 +00:00
|
|
|
this version of Git and exit.
|
2011-05-01 08:16:25 +00:00
|
|
|
|
|
|
|
--info-path::
|
2011-05-02 06:07:45 +00:00
|
|
|
Print the path where the Info files documenting this
|
2013-01-21 19:17:53 +00:00
|
|
|
version of Git are installed and exit.
|
2009-04-05 02:15:16 +00:00
|
|
|
|
2008-06-08 01:36:09 +00:00
|
|
|
-p::
|
|
|
|
--paginate::
|
2010-02-14 12:02:35 +00:00
|
|
|
Pipe all output into 'less' (or if set, $PAGER) if standard
|
|
|
|
output is a terminal. This overrides the `pager.<cmd>`
|
|
|
|
configuration options (see the "Configuration Mechanism" section
|
|
|
|
below).
|
2006-07-25 18:24:22 +00:00
|
|
|
|
git: add -P as a short option for --no-pager
It is possible to configure 'less', the pager, to use an alternate
screen to show the content, for example, by setting LESS=RS in the
environment. When it is closed in this configuration, it switches
back to the original screen, and all content is gone.
It is not uncommon to request that the output remains visible in
the terminal. For this, the option --no-pager can be used. But
it is a bit cumbersome to type, even when command completion is
available. Provide a short option, -P, to make the option more
easily accessible.
Signed-off-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-03 17:15:08 +00:00
|
|
|
-P::
|
2007-08-19 17:24:36 +00:00
|
|
|
--no-pager::
|
2013-01-21 19:17:53 +00:00
|
|
|
Do not pipe Git output into a pager.
|
2007-08-19 17:24:36 +00:00
|
|
|
|
2006-07-25 18:24:22 +00:00
|
|
|
--git-dir=<path>::
|
2020-01-30 01:14:01 +00:00
|
|
|
Set the path to the repository (".git" directory). This can also be
|
|
|
|
controlled by setting the `GIT_DIR` environment variable. It can be
|
|
|
|
an absolute path or relative path to current working directory.
|
|
|
|
+
|
|
|
|
Specifying the location of the ".git" directory using this
|
|
|
|
option (or `GIT_DIR` environment variable) turns off the
|
|
|
|
repository discovery that tries to find a directory with
|
|
|
|
".git" subdirectory (which is how the repository and the
|
|
|
|
top-level of the working tree are discovered), and tells Git
|
|
|
|
that you are at the top level of the working tree. If you
|
|
|
|
are not at the top-level directory of the working tree, you
|
|
|
|
should tell Git where the top-level of the working tree is,
|
|
|
|
with the `--work-tree=<path>` option (or `GIT_WORK_TREE`
|
|
|
|
environment variable)
|
|
|
|
+
|
|
|
|
If you just want to run git as if it was started in `<path>` then use
|
|
|
|
`git -C <path>`.
|
2006-07-25 18:24:22 +00:00
|
|
|
|
2007-06-06 07:10:42 +00:00
|
|
|
--work-tree=<path>::
|
2011-01-23 23:49:41 +00:00
|
|
|
Set the path to the working tree. It can be an absolute path
|
|
|
|
or a path relative to the current working directory.
|
2007-06-06 07:10:42 +00:00
|
|
|
This can also be controlled by setting the GIT_WORK_TREE
|
|
|
|
environment variable and the core.worktree configuration
|
2011-01-23 23:49:41 +00:00
|
|
|
variable (see core.worktree in linkgit:git-config[1] for a
|
|
|
|
more detailed discussion).
|
2007-06-06 07:10:42 +00:00
|
|
|
|
2011-07-08 23:14:10 +00:00
|
|
|
--namespace=<path>::
|
2013-01-21 19:17:53 +00:00
|
|
|
Set the Git namespace. See linkgit:gitnamespaces[7] for more
|
2011-07-08 23:14:10 +00:00
|
|
|
details. Equivalent to setting the `GIT_NAMESPACE` environment
|
|
|
|
variable.
|
|
|
|
|
2006-07-25 18:24:22 +00:00
|
|
|
--bare::
|
2007-08-28 05:41:23 +00:00
|
|
|
Treat the repository as a bare repository. If GIT_DIR
|
|
|
|
environment is not set, it is set to the current working
|
|
|
|
directory.
|
|
|
|
|
2009-10-12 20:30:32 +00:00
|
|
|
--no-replace-objects::
|
2013-01-21 19:17:53 +00:00
|
|
|
Do not use replacement refs to replace Git objects. See
|
2009-10-12 20:30:32 +00:00
|
|
|
linkgit:git-replace[1] for more information.
|
|
|
|
|
add global --literal-pathspecs option
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-19 22:37:30 +00:00
|
|
|
--literal-pathspecs::
|
2013-07-14 08:36:07 +00:00
|
|
|
Treat pathspecs literally (i.e. no globbing, no pathspec magic).
|
|
|
|
This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
|
add global --literal-pathspecs option
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-19 22:37:30 +00:00
|
|
|
variable to `1`.
|
|
|
|
|
2013-09-23 18:54:35 +00:00
|
|
|
--glob-pathspecs::
|
2013-07-14 08:36:08 +00:00
|
|
|
Add "glob" magic to all pathspec. This is equivalent to setting
|
|
|
|
the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling
|
|
|
|
globbing on individual pathspecs can be done using pathspec
|
|
|
|
magic ":(literal)"
|
|
|
|
|
2013-09-23 18:54:35 +00:00
|
|
|
--noglob-pathspecs::
|
2013-07-14 08:36:08 +00:00
|
|
|
Add "literal" magic to all pathspec. This is equivalent to setting
|
|
|
|
the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling
|
|
|
|
globbing on individual pathspecs can be done using pathspec
|
|
|
|
magic ":(glob)"
|
2005-12-13 10:38:24 +00:00
|
|
|
|
2013-09-23 18:54:35 +00:00
|
|
|
--icase-pathspecs::
|
2013-07-14 08:36:09 +00:00
|
|
|
Add "icase" magic to all pathspec. This is equivalent to setting
|
|
|
|
the `GIT_ICASE_PATHSPECS` environment variable to `1`.
|
2005-12-13 10:38:24 +00:00
|
|
|
|
git: add --no-optional-locks option
Some tools like IDEs or fancy editors may periodically run
commands like "git status" in the background to keep track
of the state of the repository. Some of these commands may
refresh the index and write out the result in an
opportunistic way: if they can get the index lock, then they
update the on-disk index with any updates they find. And if
not, then their in-core refresh is lost and just has to be
recomputed by the next caller.
But taking the index lock may conflict with other operations
in the repository. Especially ones that the user is doing
themselves, which _aren't_ opportunistic. In other words,
"git status" knows how to back off when somebody else is
holding the lock, but other commands don't know that status
would be happy to drop the lock if somebody else wanted it.
There are a couple possible solutions:
1. Have some kind of "pseudo-lock" that allows other
commands to tell status that they want the lock.
This is likely to be complicated and error-prone to
implement (and maybe even impossible with just
dotlocks to work from, as it requires some
inter-process communication).
2. Avoid background runs of commands like "git status"
that want to do opportunistic updates, preferring
instead plumbing like diff-files, etc.
This is awkward for a couple of reasons. One is that
"status --porcelain" reports a lot more about the
repository state than is available from individual
plumbing commands. And two is that we actually _do_
want to see the refreshed index. We just don't want to
take a lock or write out the result. Whereas commands
like diff-files expect us to refresh the index
separately and write it to disk so that they can depend
on the result. But that write is exactly what we're
trying to avoid.
3. Ask "status" not to lock or write the index.
This is easy to implement. The big downside is that any
work done in refreshing the index for such a call is
lost when the process exits. So a background process
may end up re-hashing a changed file multiple times
until the user runs a command that does an index
refresh themselves.
This patch implements the option 3. The idea (and the test)
is largely stolen from a Git for Windows patch by Johannes
Schindelin, 67e5ce7f63 (status: offer *not* to lock the
index and update it, 2016-08-12). The twist here is that
instead of making this an option to "git status", it becomes
a "git" option and matching environment variable.
The reason there is two-fold:
1. An environment variable is carried through to
sub-processes. And whether an invocation is a
background process or not should apply to the whole
process tree. So you could do "git --no-optional-locks
foo", and if "foo" is a script or alias that calls
"status", you'll still get the effect.
2. There may be other programs that want the same
treatment.
I've punted here on finding more callers to convert,
since "status" is the obvious one to call as a repeated
background job. But "git diff"'s opportunistic refresh
of the index may be a good candidate.
The test is taken from 67e5ce7f63, and it's worth repeating
Johannes's explanation:
Note that the regression test added in this commit does
not *really* verify that no index.lock file was written;
that test is not possible in a portable way. Instead, we
verify that .git/index is rewritten *only* when `git
status` is run without `--no-optional-locks`.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-27 06:54:30 +00:00
|
|
|
--no-optional-locks::
|
|
|
|
Do not perform optional operations that require locks. This is
|
|
|
|
equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`.
|
|
|
|
|
2023-12-25 21:21:27 +00:00
|
|
|
--list-cmds=<group>[,<group>...]::
|
2018-05-20 18:39:57 +00:00
|
|
|
List commands by group. This is an internal/experimental
|
|
|
|
option and may change or be removed in the future. Supported
|
|
|
|
groups are: builtins, parseopt (builtin commands that use
|
2018-05-20 18:39:59 +00:00
|
|
|
parse-options), main (all commands in libexec directory),
|
2018-05-20 18:40:00 +00:00
|
|
|
others (all other commands in `$PATH` that have git- prefix),
|
2018-05-20 18:40:07 +00:00
|
|
|
list-<category> (see categories in command-list.txt),
|
2018-05-20 18:40:09 +00:00
|
|
|
nohelpers (exclude helper commands), alias and config
|
|
|
|
(retrieve command list from config variable completion.commands)
|
2018-05-20 18:39:57 +00:00
|
|
|
|
2023-05-06 04:15:29 +00:00
|
|
|
--attr-source=<tree-ish>::
|
|
|
|
Read gitattributes from <tree-ish> instead of the worktree. See
|
|
|
|
linkgit:gitattributes[5]. This is equivalent to setting the
|
|
|
|
`GIT_ATTR_SOURCE` environment variable.
|
|
|
|
|
2006-04-02 21:54:34 +00:00
|
|
|
GIT COMMANDS
|
|
|
|
------------
|
2005-12-13 10:38:24 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
We divide Git into high level ("porcelain") commands and low level
|
2006-04-02 21:54:34 +00:00
|
|
|
("plumbing") commands.
|
2005-12-10 07:41:03 +00:00
|
|
|
|
2006-04-02 21:54:34 +00:00
|
|
|
High-level commands (porcelain)
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
We separate the porcelain commands into the main commands and some
|
|
|
|
ancillary user utilities.
|
|
|
|
|
|
|
|
Main porcelain commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
2005-08-27 04:33:46 +00:00
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-mainporcelain.txt[]
|
2005-08-15 22:48:47 +00:00
|
|
|
|
2005-08-15 15:23:06 +00:00
|
|
|
Ancillary Commands
|
2006-04-02 21:54:34 +00:00
|
|
|
~~~~~~~~~~~~~~~~~~
|
2005-07-14 07:10:48 +00:00
|
|
|
Manipulators:
|
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-ancillarymanipulators.txt[]
|
2005-05-10 21:32:37 +00:00
|
|
|
|
2005-08-15 15:23:06 +00:00
|
|
|
Interrogators:
|
2005-05-10 21:32:37 +00:00
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-ancillaryinterrogators.txt[]
|
2005-08-23 08:49:47 +00:00
|
|
|
|
2007-01-19 06:32:38 +00:00
|
|
|
|
|
|
|
Interacting with Others
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
These commands are to interact with foreign SCM and with other
|
|
|
|
people via patch over e-mail.
|
|
|
|
|
|
|
|
include::cmds-foreignscminterface.txt[]
|
|
|
|
|
2019-04-25 09:45:45 +00:00
|
|
|
Reset, restore and revert
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are three commands with similar names: `git reset`,
|
|
|
|
`git restore` and `git revert`.
|
|
|
|
|
|
|
|
* linkgit:git-revert[1] is about making a new commit that reverts the
|
|
|
|
changes made by other commits.
|
|
|
|
|
|
|
|
* linkgit:git-restore[1] is about restoring files in the working tree
|
|
|
|
from either the index or another commit. This command does not
|
|
|
|
update your branch. The command can also be used to restore files in
|
|
|
|
the index from another commit.
|
|
|
|
|
|
|
|
* linkgit:git-reset[1] is about updating your branch, moving the tip
|
|
|
|
in order to add or remove commits from the branch. This operation
|
|
|
|
changes the commit history.
|
|
|
|
+
|
|
|
|
`git reset` can also be used to restore the index, overlapping with
|
|
|
|
`git restore`.
|
|
|
|
|
2007-01-19 06:32:38 +00:00
|
|
|
|
2006-10-29 20:09:48 +00:00
|
|
|
Low-level commands (plumbing)
|
|
|
|
-----------------------------
|
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
Although Git includes its
|
2006-10-29 20:09:48 +00:00
|
|
|
own porcelain layer, its low-level commands are sufficient to support
|
|
|
|
development of alternative porcelains. Developers of such porcelains
|
2007-12-29 06:20:38 +00:00
|
|
|
might start by reading about linkgit:git-update-index[1] and
|
|
|
|
linkgit:git-read-tree[1].
|
2006-10-29 20:09:48 +00:00
|
|
|
|
2007-01-19 06:32:38 +00:00
|
|
|
The interface (input, output, set of options and the semantics)
|
|
|
|
to these low-level commands are meant to be a lot more stable
|
|
|
|
than Porcelain level commands, because these commands are
|
|
|
|
primarily for scripted use. The interface to Porcelain commands
|
|
|
|
on the other hand are subject to change in order to improve the
|
|
|
|
end user experience.
|
|
|
|
|
|
|
|
The following description divides
|
|
|
|
the low-level commands into commands that manipulate objects (in
|
2006-10-29 20:09:48 +00:00
|
|
|
the repository, index, and working tree), commands that interrogate and
|
|
|
|
compare objects, and commands that move objects and references between
|
|
|
|
repositories.
|
|
|
|
|
2007-01-19 06:32:38 +00:00
|
|
|
|
2006-10-29 20:09:48 +00:00
|
|
|
Manipulation commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-plumbingmanipulators.txt[]
|
2006-10-29 20:09:48 +00:00
|
|
|
|
|
|
|
|
|
|
|
Interrogation commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-plumbinginterrogators.txt[]
|
2006-10-29 20:09:48 +00:00
|
|
|
|
|
|
|
In general, the interrogate commands do not touch the files in
|
|
|
|
the working tree.
|
|
|
|
|
|
|
|
|
2019-11-05 17:07:20 +00:00
|
|
|
Syncing repositories
|
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
2006-10-29 20:09:48 +00:00
|
|
|
|
2007-01-18 23:03:13 +00:00
|
|
|
include::cmds-synchingrepositories.txt[]
|
2006-10-29 20:09:48 +00:00
|
|
|
|
2009-08-07 14:24:21 +00:00
|
|
|
The following are helper commands used by the above; end users
|
2007-01-19 06:32:38 +00:00
|
|
|
typically do not use them directly.
|
|
|
|
|
|
|
|
include::cmds-synchelpers.txt[]
|
|
|
|
|
|
|
|
|
|
|
|
Internal helper commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
These are internal helper commands used by other commands; end
|
|
|
|
users typically do not use them directly.
|
|
|
|
|
|
|
|
include::cmds-purehelpers.txt[]
|
|
|
|
|
2020-08-05 01:19:07 +00:00
|
|
|
Guides
|
|
|
|
------
|
|
|
|
|
|
|
|
The following documentation pages are guides about Git concepts.
|
|
|
|
|
|
|
|
include::cmds-guide.txt[]
|
|
|
|
|
2022-08-04 16:28:33 +00:00
|
|
|
Repository, command and file interfaces
|
|
|
|
---------------------------------------
|
|
|
|
|
|
|
|
This documentation discusses repository and command interfaces which
|
|
|
|
users are expected to interact with directly. See `--user-formats` in
|
2022-09-20 02:45:56 +00:00
|
|
|
linkgit:git-help[1] for more details on the criteria.
|
2022-08-04 16:28:33 +00:00
|
|
|
|
|
|
|
include::cmds-userinterfaces.txt[]
|
2006-10-29 20:09:48 +00:00
|
|
|
|
2022-08-04 16:28:34 +00:00
|
|
|
File formats, protocols and other developer interfaces
|
|
|
|
------------------------------------------------------
|
|
|
|
|
|
|
|
This documentation discusses file formats, over-the-wire protocols and
|
|
|
|
other git developer interfaces. See `--developer-interfaces` in
|
|
|
|
linkgit:git-help[1].
|
|
|
|
|
|
|
|
include::cmds-developerinterfaces.txt[]
|
2006-10-29 20:09:48 +00:00
|
|
|
|
2005-10-29 21:32:56 +00:00
|
|
|
Configuration Mechanism
|
|
|
|
-----------------------
|
|
|
|
|
2013-02-14 15:36:54 +00:00
|
|
|
Git uses a simple text format to store customizations that are per
|
|
|
|
repository and are per user. Such a configuration file may look
|
|
|
|
like this:
|
2005-10-29 21:32:56 +00:00
|
|
|
|
|
|
|
------------
|
|
|
|
#
|
2005-12-08 00:05:21 +00:00
|
|
|
# A '#' or ';' character indicates a comment.
|
2005-10-29 21:32:56 +00:00
|
|
|
#
|
|
|
|
|
|
|
|
; core variables
|
|
|
|
[core]
|
|
|
|
; Don't trust file modes
|
|
|
|
filemode = false
|
|
|
|
|
|
|
|
; user identity
|
|
|
|
[user]
|
|
|
|
name = "Junio C Hamano"
|
2013-02-14 15:36:54 +00:00
|
|
|
email = "gitster@pobox.com"
|
2005-10-29 21:32:56 +00:00
|
|
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
Various commands read from the configuration file and adjust
|
2010-02-14 12:02:35 +00:00
|
|
|
their operation accordingly. See linkgit:git-config[1] for a
|
2013-02-14 15:36:54 +00:00
|
|
|
list and more details about the configuration mechanism.
|
2005-10-29 21:32:56 +00:00
|
|
|
|
|
|
|
|
2005-05-22 17:44:16 +00:00
|
|
|
Identifier Terminology
|
2005-05-10 21:32:30 +00:00
|
|
|
----------------------
|
|
|
|
<object>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates the object name for any type of object.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
<blob>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates a blob object name.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
<tree>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates a tree object name.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
<commit>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates a commit object name.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
<tree-ish>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates a tree, commit or tag object name. A
|
2005-05-22 17:44:16 +00:00
|
|
|
command that takes a <tree-ish> argument ultimately wants to
|
|
|
|
operate on a <tree> object but automatically dereferences
|
|
|
|
<commit> and <tag> objects that point at a <tree>.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2007-03-05 19:46:05 +00:00
|
|
|
<commit-ish>::
|
|
|
|
Indicates a commit or tag object name. A
|
|
|
|
command that takes a <commit-ish> argument ultimately wants to
|
|
|
|
operate on a <commit> object but automatically dereferences
|
|
|
|
<tag> objects that point at a <commit>.
|
|
|
|
|
2005-05-10 21:32:30 +00:00
|
|
|
<type>::
|
|
|
|
Indicates that an object type is required.
|
2005-12-08 00:05:21 +00:00
|
|
|
Currently one of: `blob`, `tree`, `commit`, or `tag`.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
<file>::
|
2005-12-08 00:05:21 +00:00
|
|
|
Indicates a filename - almost always relative to the
|
|
|
|
root of the tree structure `GIT_INDEX_FILE` describes.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2005-05-10 21:32:38 +00:00
|
|
|
Symbolic Identifiers
|
|
|
|
--------------------
|
2013-01-21 19:17:53 +00:00
|
|
|
Any Git command accepting any <object> can also use the following
|
2005-05-22 17:44:16 +00:00
|
|
|
symbolic notation:
|
2005-05-10 21:32:38 +00:00
|
|
|
|
|
|
|
HEAD::
|
2011-06-23 16:35:10 +00:00
|
|
|
indicates the head of the current branch.
|
2005-12-08 00:05:21 +00:00
|
|
|
|
2005-05-10 21:32:38 +00:00
|
|
|
<tag>::
|
2005-12-08 00:05:21 +00:00
|
|
|
a valid tag 'name'
|
2011-06-23 16:35:10 +00:00
|
|
|
(i.e. a `refs/tags/<tag>` reference).
|
2005-12-08 00:05:21 +00:00
|
|
|
|
2005-05-10 21:32:38 +00:00
|
|
|
<head>::
|
2005-12-08 00:05:21 +00:00
|
|
|
a valid head 'name'
|
2011-06-23 16:35:10 +00:00
|
|
|
(i.e. a `refs/heads/<head>` reference).
|
2005-12-08 00:05:21 +00:00
|
|
|
|
2006-10-25 18:33:08 +00:00
|
|
|
For a more complete list of ways to spell object names, see
|
2010-10-11 16:03:32 +00:00
|
|
|
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
|
2006-10-25 18:33:08 +00:00
|
|
|
|
2005-05-10 21:32:38 +00:00
|
|
|
|
|
|
|
File/Directory Structure
|
|
|
|
------------------------
|
|
|
|
|
2008-06-30 22:01:21 +00:00
|
|
|
Please see the linkgit:gitrepository-layout[5] document.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2008-06-30 22:01:21 +00:00
|
|
|
Read linkgit:githooks[5] for more details about each hook.
|
2006-03-25 03:21:07 +00:00
|
|
|
|
2005-05-10 21:32:38 +00:00
|
|
|
Higher level SCMs may provide and manage additional information in the
|
2005-12-08 00:05:21 +00:00
|
|
|
`$GIT_DIR`.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2005-09-01 23:56:13 +00:00
|
|
|
|
2005-05-10 21:32:30 +00:00
|
|
|
Terminology
|
|
|
|
-----------
|
2008-06-30 22:01:21 +00:00
|
|
|
Please see linkgit:gitglossary[7].
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
Environment Variables
|
|
|
|
---------------------
|
2022-09-15 16:06:56 +00:00
|
|
|
Various Git commands pay attention to environment variables and change
|
|
|
|
their behavior. The environment variables marked as "Boolean" take
|
|
|
|
their values the same way as Boolean valued configuration variables, e.g.
|
|
|
|
"true", "yes", "on" and positive numbers are taken as "yes".
|
|
|
|
|
|
|
|
Here are the variables:
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
The Git Repository
|
2005-05-10 21:32:38 +00:00
|
|
|
~~~~~~~~~~~~~~~~~~
|
2013-01-21 19:17:53 +00:00
|
|
|
These environment variables apply to 'all' core Git commands. Nb: it
|
2005-05-10 21:32:38 +00:00
|
|
|
is worth noting that they may be used/overridden by SCMS sitting above
|
2015-07-24 04:00:54 +00:00
|
|
|
Git so take care if using a foreign front-end.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_INDEX_FILE`::
|
2022-09-15 16:06:58 +00:00
|
|
|
This environment variable specifies an alternate
|
2005-11-11 01:12:27 +00:00
|
|
|
index file. If not specified, the default of `$GIT_DIR/index`
|
|
|
|
is used.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_INDEX_VERSION`::
|
2022-09-15 16:06:59 +00:00
|
|
|
This environment variable specifies what index version is used
|
|
|
|
when writing the index file out. It won't affect existing index
|
2015-03-24 00:28:33 +00:00
|
|
|
files. By default index file version 2 or 3 is used. See
|
|
|
|
linkgit:git-update-index[1] for more information.
|
2014-02-23 20:49:57 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_OBJECT_DIRECTORY`::
|
2005-05-10 21:32:38 +00:00
|
|
|
If the object storage directory is specified via this
|
|
|
|
environment variable then the sha1 directories are created
|
|
|
|
underneath - otherwise the default `$GIT_DIR/objects`
|
|
|
|
directory is used.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_ALTERNATE_OBJECT_DIRECTORIES`::
|
2013-01-21 19:17:53 +00:00
|
|
|
Due to the immutable nature of Git objects, old objects can be
|
2005-05-10 21:32:38 +00:00
|
|
|
archived into shared, read-only directories. This variable
|
2007-12-03 20:55:57 +00:00
|
|
|
specifies a ":" separated (on Windows ";" separated) list
|
2013-01-21 19:17:53 +00:00
|
|
|
of Git object directories which can be used to search for Git
|
2007-12-03 20:55:57 +00:00
|
|
|
objects. New objects will not be written to these directories.
|
alternates: accept double-quoted paths
We read lists of alternates from objects/info/alternates
files (delimited by newline), as well as from the
GIT_ALTERNATE_OBJECT_DIRECTORIES environment variable
(delimited by colon or semi-colon, depending on the
platform).
There's no mechanism for quoting the delimiters, so it's
impossible to specify an alternate path that contains a
colon in the environment, or one that contains a newline in
a file. We've lived with that restriction for ages because
both alternates and filenames with colons are relatively
rare, and it's only a problem when the two meet. But since
722ff7f87 (receive-pack: quarantine objects until
pre-receive accepts, 2016-10-03), which builds on the
alternates system, every push causes the receiver to set
GIT_ALTERNATE_OBJECT_DIRECTORIES internally.
It would be convenient to have some way to quote the
delimiter so that we can represent arbitrary paths.
The simplest thing would be an escape character before a
quoted delimiter (e.g., "\:" as a literal colon). But that
creates a backwards compatibility problem: any path which
uses that escape character is now broken, and we've just
shifted the problem. We could choose an unlikely escape
character (e.g., something from the non-printable ASCII
range), but that's awkward to use.
Instead, let's treat names as unquoted unless they begin
with a double-quote, in which case they are interpreted via
our usual C-stylke quoting rules. This also breaks
backwards-compatibility, but in a smaller way: it only
matters if your file has a double-quote as the very _first_
character in the path (whereas an escape character is a
problem anywhere in the path). It's also consistent with
many other parts of git, which accept either a bare pathname
or a double-quoted one, and the sender can choose to quote
or not as required.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-12-12 19:52:22 +00:00
|
|
|
+
|
2018-10-22 20:45:43 +00:00
|
|
|
Entries that begin with `"` (double-quote) will be interpreted
|
|
|
|
as C-style quoted paths, removing leading and trailing
|
|
|
|
double-quotes and respecting backslash escapes. E.g., the value
|
|
|
|
`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
|
|
|
|
`path-with-"-and-:-in-it` and `vanilla-path`.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_DIR`::
|
|
|
|
If the `GIT_DIR` environment variable is set then it
|
2005-12-08 00:05:21 +00:00
|
|
|
specifies a path to use instead of the default `.git`
|
|
|
|
for the base of the repository.
|
2016-06-28 11:40:11 +00:00
|
|
|
The `--git-dir` command-line option also sets this value.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_WORK_TREE`::
|
2013-05-31 01:11:41 +00:00
|
|
|
Set the path to the root of the working tree.
|
2016-06-28 11:40:11 +00:00
|
|
|
This can also be controlled by the `--work-tree` command-line
|
2007-06-06 07:10:42 +00:00
|
|
|
option and the core.worktree configuration variable.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NAMESPACE`::
|
2013-01-21 19:17:53 +00:00
|
|
|
Set the Git namespace; see linkgit:gitnamespaces[7] for details.
|
2016-06-28 11:40:11 +00:00
|
|
|
The `--namespace` command-line option also sets this value.
|
2011-07-08 23:14:10 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_CEILING_DIRECTORIES`::
|
Provide a mechanism to turn off symlink resolution in ceiling paths
Commit 1b77d83cab 'setup_git_directory_gently_1(): resolve symlinks
in ceiling paths' changed the setup code to resolve symlinks in the
entries in GIT_CEILING_DIRECTORIES. Because those entries are
compared textually to the symlink-resolved current directory, an
entry in GIT_CEILING_DIRECTORIES that contained a symlink would have
no effect. It was known that this could cause performance problems
if the symlink resolution *itself* touched slow filesystems, but it
was thought that such use cases would be unlikely. The intention of
the earlier change was to deal with a case when the user has this:
GIT_CEILING_DIRECTORIES=/home/gitster
but in reality, /home/gitster is a symbolic link to somewhere else,
e.g. /net/machine/home4/gitster. A textual comparison between the
specified value /home/gitster and the location getcwd(3) returns
would not help us, but readlink("/home/gitster") would still be
fast.
After this change was released, Anders Kaseorg <andersk@mit.edu>
reported:
> [...] my computer has been acting so slow when I’m not connected to
> the network. I put various network filesystem paths in
> $GIT_CEILING_DIRECTORIES, such as
> /afs/athena.mit.edu/user/a/n/andersk (to avoid hitting its parents
> /afs/athena.mit.edu, /afs/athena.mit.edu/user/a, and
> /afs/athena.mit.edu/user/a/n which all live in different AFS
> volumes). Now when I’m not connected to the network, every
> invocation of Git, including the __git_ps1 in my shell prompt, waits
> for AFS to timeout.
To allow users to work around this problem, give them a mechanism to
turn off symlink resolution in GIT_CEILING_DIRECTORIES entries. All
the entries that follow an empty entry will not be checked for symbolic
links and used literally in comparison. E.g. with these:
GIT_CEILING_DIRECTORIES=:/foo/bar:/xyzzy or
GIT_CEILING_DIRECTORIES=/foo/bar::/xyzzy
we will not readlink("/xyzzy") because it comes after an empty entry.
With the former (but not with the latter), "/foo/bar" comes after an
empty entry, and we will not readlink it, either.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-20 09:09:24 +00:00
|
|
|
This should be a colon-separated list of absolute paths. If
|
2013-02-27 17:47:27 +00:00
|
|
|
set, it is a list of directories that Git should not chdir up
|
Provide a mechanism to turn off symlink resolution in ceiling paths
Commit 1b77d83cab 'setup_git_directory_gently_1(): resolve symlinks
in ceiling paths' changed the setup code to resolve symlinks in the
entries in GIT_CEILING_DIRECTORIES. Because those entries are
compared textually to the symlink-resolved current directory, an
entry in GIT_CEILING_DIRECTORIES that contained a symlink would have
no effect. It was known that this could cause performance problems
if the symlink resolution *itself* touched slow filesystems, but it
was thought that such use cases would be unlikely. The intention of
the earlier change was to deal with a case when the user has this:
GIT_CEILING_DIRECTORIES=/home/gitster
but in reality, /home/gitster is a symbolic link to somewhere else,
e.g. /net/machine/home4/gitster. A textual comparison between the
specified value /home/gitster and the location getcwd(3) returns
would not help us, but readlink("/home/gitster") would still be
fast.
After this change was released, Anders Kaseorg <andersk@mit.edu>
reported:
> [...] my computer has been acting so slow when I’m not connected to
> the network. I put various network filesystem paths in
> $GIT_CEILING_DIRECTORIES, such as
> /afs/athena.mit.edu/user/a/n/andersk (to avoid hitting its parents
> /afs/athena.mit.edu, /afs/athena.mit.edu/user/a, and
> /afs/athena.mit.edu/user/a/n which all live in different AFS
> volumes). Now when I’m not connected to the network, every
> invocation of Git, including the __git_ps1 in my shell prompt, waits
> for AFS to timeout.
To allow users to work around this problem, give them a mechanism to
turn off symlink resolution in GIT_CEILING_DIRECTORIES entries. All
the entries that follow an empty entry will not be checked for symbolic
links and used literally in comparison. E.g. with these:
GIT_CEILING_DIRECTORIES=:/foo/bar:/xyzzy or
GIT_CEILING_DIRECTORIES=/foo/bar::/xyzzy
we will not readlink("/xyzzy") because it comes after an empty entry.
With the former (but not with the latter), "/foo/bar" comes after an
empty entry, and we will not readlink it, either.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-20 09:09:24 +00:00
|
|
|
into while looking for a repository directory (useful for
|
|
|
|
excluding slow-loading network directories). It will not
|
|
|
|
exclude the current working directory or a GIT_DIR set on the
|
|
|
|
command line or in the environment. Normally, Git has to read
|
|
|
|
the entries in this list and resolve any symlink that
|
|
|
|
might be present in order to compare them with the current
|
|
|
|
directory. However, if even this access is slow, you
|
|
|
|
can add an empty entry to the list to tell Git that the
|
|
|
|
subsequent entries are not symlinks and needn't be resolved;
|
|
|
|
e.g.,
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
|
2008-05-20 06:49:26 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_DISCOVERY_ACROSS_FILESYSTEM`::
|
2010-04-04 17:33:53 +00:00
|
|
|
When run in a directory that does not have ".git" repository
|
2013-01-21 19:17:53 +00:00
|
|
|
directory, Git tries to find such a directory in the parent
|
2010-04-04 17:33:53 +00:00
|
|
|
directories to find the top of the working tree, but by default it
|
2022-09-15 16:06:56 +00:00
|
|
|
does not cross filesystem boundaries. This Boolean environment variable
|
2013-01-21 19:17:53 +00:00
|
|
|
can be set to true to tell Git not to stop at filesystem
|
2016-06-07 22:35:06 +00:00
|
|
|
boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
|
|
|
|
an explicit repository directory set via `GIT_DIR` or on the
|
2010-04-04 21:49:31 +00:00
|
|
|
command line.
|
2010-03-17 19:55:53 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_COMMON_DIR`::
|
$GIT_COMMON_DIR: a new environment variable
This variable is intended to support multiple working directories
attached to a repository. Such a repository may have a main working
directory, created by either "git init" or "git clone" and one or more
linked working directories. These working directories and the main
repository share the same repository directory.
In linked working directories, $GIT_COMMON_DIR must be defined to point
to the real repository directory and $GIT_DIR points to an unused
subdirectory inside $GIT_COMMON_DIR. File locations inside the
repository are reorganized from the linked worktree view point:
- worktree-specific such as HEAD, logs/HEAD, index, other top-level
refs and unrecognized files are from $GIT_DIR.
- the rest like objects, refs, info, hooks, packed-refs, shallow...
are from $GIT_COMMON_DIR (except info/sparse-checkout, but that's
a separate patch)
Scripts are supposed to retrieve paths in $GIT_DIR with "git rev-parse
--git-path", which will take care of "$GIT_DIR vs $GIT_COMMON_DIR"
business.
The redirection is done by git_path(), git_pathdup() and
strbuf_git_path(). The selected list of paths goes to $GIT_COMMON_DIR,
not the other way around in case a developer adds a new
worktree-specific file and it's accidentally promoted to be shared
across repositories (this includes unknown files added by third party
commands)
The list of known files that belong to $GIT_DIR are:
ADD_EDIT.patch BISECT_ANCESTORS_OK BISECT_EXPECTED_REV BISECT_LOG
BISECT_NAMES CHERRY_PICK_HEAD COMMIT_MSG FETCH_HEAD HEAD MERGE_HEAD
MERGE_MODE MERGE_RR NOTES_EDITMSG NOTES_MERGE_WORKTREE ORIG_HEAD
REVERT_HEAD SQUASH_MSG TAG_EDITMSG fast_import_crash_* logs/HEAD
next-index-* rebase-apply rebase-merge rsync-refs-* sequencer/*
shallow_*
Path mapping is NOT done for git_path_submodule(). Multi-checkouts are
not supported as submodules.
Helped-by: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-30 08:24:36 +00:00
|
|
|
If this variable is set to a path, non-worktree files that are
|
|
|
|
normally in $GIT_DIR will be taken from this path
|
|
|
|
instead. Worktree-specific files such as HEAD or index are
|
2014-11-30 08:24:47 +00:00
|
|
|
taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
|
2015-07-17 00:17:02 +00:00
|
|
|
linkgit:git-worktree[1] for
|
$GIT_COMMON_DIR: a new environment variable
This variable is intended to support multiple working directories
attached to a repository. Such a repository may have a main working
directory, created by either "git init" or "git clone" and one or more
linked working directories. These working directories and the main
repository share the same repository directory.
In linked working directories, $GIT_COMMON_DIR must be defined to point
to the real repository directory and $GIT_DIR points to an unused
subdirectory inside $GIT_COMMON_DIR. File locations inside the
repository are reorganized from the linked worktree view point:
- worktree-specific such as HEAD, logs/HEAD, index, other top-level
refs and unrecognized files are from $GIT_DIR.
- the rest like objects, refs, info, hooks, packed-refs, shallow...
are from $GIT_COMMON_DIR (except info/sparse-checkout, but that's
a separate patch)
Scripts are supposed to retrieve paths in $GIT_DIR with "git rev-parse
--git-path", which will take care of "$GIT_DIR vs $GIT_COMMON_DIR"
business.
The redirection is done by git_path(), git_pathdup() and
strbuf_git_path(). The selected list of paths goes to $GIT_COMMON_DIR,
not the other way around in case a developer adds a new
worktree-specific file and it's accidentally promoted to be shared
across repositories (this includes unknown files added by third party
commands)
The list of known files that belong to $GIT_DIR are:
ADD_EDIT.patch BISECT_ANCESTORS_OK BISECT_EXPECTED_REV BISECT_LOG
BISECT_NAMES CHERRY_PICK_HEAD COMMIT_MSG FETCH_HEAD HEAD MERGE_HEAD
MERGE_MODE MERGE_RR NOTES_EDITMSG NOTES_MERGE_WORKTREE ORIG_HEAD
REVERT_HEAD SQUASH_MSG TAG_EDITMSG fast_import_crash_* logs/HEAD
next-index-* rebase-apply rebase-merge rsync-refs-* sequencer/*
shallow_*
Path mapping is NOT done for git_path_submodule(). Multi-checkouts are
not supported as submodules.
Helped-by: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-30 08:24:36 +00:00
|
|
|
details. This variable has lower precedence than other path
|
|
|
|
variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
|
|
|
|
|
2020-05-26 18:37:20 +00:00
|
|
|
`GIT_DEFAULT_HASH`::
|
2020-02-22 20:17:39 +00:00
|
|
|
If this variable is set, the default hash algorithm for new
|
2023-04-26 15:13:55 +00:00
|
|
|
repositories will be set to this value. This value is
|
|
|
|
ignored when cloning and the setting of the remote repository
|
2023-07-31 13:42:02 +00:00
|
|
|
is always used. The default is "sha1".
|
|
|
|
See `--object-format` in linkgit:git-init[1].
|
2020-02-22 20:17:39 +00:00
|
|
|
|
2023-12-29 07:26:52 +00:00
|
|
|
`GIT_DEFAULT_REF_FORMAT`::
|
|
|
|
If this variable is set, the default reference backend format for new
|
|
|
|
repositories will be set to this value. The default is "files".
|
|
|
|
See `--ref-format` in linkgit:git-init[1].
|
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
Git Commits
|
2005-05-10 21:32:38 +00:00
|
|
|
~~~~~~~~~~~
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_AUTHOR_NAME`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The human-readable name used in the author identity when creating commit or
|
|
|
|
tag objects, or when writing reflogs. Overrides the `user.name` and
|
|
|
|
`author.name` configuration settings.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_AUTHOR_EMAIL`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The email address used in the author identity when creating commit or
|
|
|
|
tag objects, or when writing reflogs. Overrides the `user.email` and
|
|
|
|
`author.email` configuration settings.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_AUTHOR_DATE`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The date used for the author identity when creating commit or tag objects, or
|
|
|
|
when writing reflogs. See linkgit:git-commit[1] for valid formats.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_COMMITTER_NAME`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The human-readable name used in the committer identity when creating commit or
|
|
|
|
tag objects, or when writing reflogs. Overrides the `user.name` and
|
|
|
|
`committer.name` configuration settings.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_COMMITTER_EMAIL`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The email address used in the author identity when creating commit or
|
|
|
|
tag objects, or when writing reflogs. Overrides the `user.email` and
|
|
|
|
`committer.email` configuration settings.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_COMMITTER_DATE`::
|
2020-01-22 03:45:39 +00:00
|
|
|
The date used for the committer identity when creating commit or tag objects, or
|
|
|
|
when writing reflogs. See linkgit:git-commit[1] for valid formats.
|
|
|
|
|
|
|
|
`EMAIL`::
|
|
|
|
The email address used in the author and committer identities if no other
|
|
|
|
relevant environment variable or configuration setting has been set.
|
2005-05-10 21:32:38 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
Git Diffs
|
2005-05-10 21:32:38 +00:00
|
|
|
~~~~~~~~~
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_DIFF_OPTS`::
|
2006-11-27 19:37:43 +00:00
|
|
|
Only valid setting is "--unified=??" or "-u??" to set the
|
|
|
|
number of context lines shown when a unified diff is created.
|
|
|
|
This takes precedence over any "-U" or "--unified" option
|
2013-01-21 19:17:53 +00:00
|
|
|
value passed on the Git diff command line.
|
2006-11-27 19:37:43 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_EXTERNAL_DIFF`::
|
|
|
|
When the environment variable `GIT_EXTERNAL_DIFF` is set, the
|
2020-09-01 13:20:12 +00:00
|
|
|
program named by it is called to generate diffs, and Git
|
|
|
|
does not use its builtin diff machinery.
|
|
|
|
For a path that is added, removed, or modified,
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_EXTERNAL_DIFF` is called with 7 parameters:
|
2006-11-27 19:37:43 +00:00
|
|
|
|
|
|
|
path old-file old-hex old-mode new-file new-hex new-mode
|
|
|
|
+
|
|
|
|
where:
|
|
|
|
|
|
|
|
<old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
|
|
|
|
contents of <old|new>,
|
2013-04-15 17:49:04 +00:00
|
|
|
<old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
|
2006-11-27 19:37:43 +00:00
|
|
|
<old|new>-mode:: are the octal representation of the file modes.
|
|
|
|
+
|
|
|
|
The file parameters can point at the user's working file
|
|
|
|
(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
|
|
|
|
when a new file is added), or a temporary file (e.g. `old-file` in the
|
2016-06-07 22:35:06 +00:00
|
|
|
index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the
|
2023-01-23 09:01:14 +00:00
|
|
|
temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits.
|
2006-11-27 19:37:43 +00:00
|
|
|
+
|
2016-06-07 22:35:06 +00:00
|
|
|
For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
|
2006-11-27 19:37:43 +00:00
|
|
|
parameter, <path>.
|
2013-12-05 23:38:46 +00:00
|
|
|
+
|
2016-06-07 22:35:06 +00:00
|
|
|
For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
|
|
|
|
`GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
|
2013-12-05 23:38:46 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_DIFF_PATH_COUNTER`::
|
2013-12-05 23:38:46 +00:00
|
|
|
A 1-based counter incremented by one for every path.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_DIFF_PATH_TOTAL`::
|
2013-12-05 23:38:46 +00:00
|
|
|
The total number of paths.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2006-06-25 13:56:18 +00:00
|
|
|
other
|
|
|
|
~~~~~
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_MERGE_VERBOSITY`::
|
2007-07-12 23:54:06 +00:00
|
|
|
A number controlling the amount of output shown by
|
|
|
|
the recursive merge strategy. Overrides merge.verbosity.
|
2007-12-29 06:20:38 +00:00
|
|
|
See linkgit:git-merge[1]
|
2007-07-12 23:54:06 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_PAGER`::
|
2007-07-19 10:43:51 +00:00
|
|
|
This environment variable overrides `$PAGER`. If it is set
|
2013-01-21 19:17:53 +00:00
|
|
|
to an empty string or to the value "cat", Git will not launch
|
2008-08-24 05:28:32 +00:00
|
|
|
a pager. See also the `core.pager` option in
|
|
|
|
linkgit:git-config[1].
|
2006-07-31 13:27:00 +00:00
|
|
|
|
2019-11-25 21:28:22 +00:00
|
|
|
`GIT_PROGRESS_DELAY`::
|
|
|
|
A number controlling how many seconds to delay before showing
|
|
|
|
optional progress indicators. Defaults to 2.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_EDITOR`::
|
2012-03-23 12:38:42 +00:00
|
|
|
This environment variable overrides `$EDITOR` and `$VISUAL`.
|
2013-01-21 19:17:53 +00:00
|
|
|
It is used by several Git commands when, on interactive mode,
|
2012-03-23 12:38:42 +00:00
|
|
|
an editor is to be launched. See also linkgit:git-var[1]
|
|
|
|
and the `core.editor` option in linkgit:git-config[1].
|
|
|
|
|
2020-08-31 03:40:08 +00:00
|
|
|
`GIT_SEQUENCE_EDITOR`::
|
|
|
|
This environment variable overrides the configured Git editor
|
|
|
|
when editing the todo list of an interactive rebase. See also
|
2020-12-22 15:44:42 +00:00
|
|
|
linkgit:git-rebase[1] and the `sequence.editor` option in
|
|
|
|
linkgit:git-config[1].
|
2020-08-31 03:40:08 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_SSH`::
|
|
|
|
`GIT_SSH_COMMAND`::
|
2014-11-09 22:42:32 +00:00
|
|
|
If either of these environment variables is set then 'git fetch'
|
|
|
|
and 'git push' will use the specified command instead of 'ssh'
|
|
|
|
when they need to connect to a remote system.
|
2017-10-16 17:55:31 +00:00
|
|
|
The command-line parameters passed to the configured command are
|
|
|
|
determined by the ssh variant. See `ssh.variant` option in
|
|
|
|
linkgit:git-config[1] for details.
|
2007-08-04 06:06:52 +00:00
|
|
|
+
|
2014-11-09 22:42:32 +00:00
|
|
|
`$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
|
|
|
|
by the shell, which allows additional arguments to be included.
|
|
|
|
`$GIT_SSH` on the other hand must be just the path to a program
|
|
|
|
(which can be a wrapper shell script, if additional arguments are
|
|
|
|
needed).
|
2007-08-04 06:06:52 +00:00
|
|
|
+
|
|
|
|
Usually it is easier to configure any desired options through your
|
|
|
|
personal `.ssh/config` file. Please consult your ssh documentation
|
|
|
|
for further details.
|
|
|
|
|
2017-02-01 12:01:16 +00:00
|
|
|
`GIT_SSH_VARIANT`::
|
|
|
|
If this environment variable is set, it overrides Git's autodetection
|
|
|
|
whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
|
|
|
|
plink or tortoiseplink. This variable overrides the config setting
|
|
|
|
`ssh.variant` that serves the same purpose.
|
|
|
|
|
2022-09-15 16:06:55 +00:00
|
|
|
`GIT_SSL_NO_VERIFY`::
|
|
|
|
Setting and exporting this environment variable to any value
|
|
|
|
tells Git not to verify the SSL certificate when fetching or
|
|
|
|
pushing over HTTPS.
|
|
|
|
|
2023-05-06 04:15:29 +00:00
|
|
|
`GIT_ATTR_SOURCE`::
|
|
|
|
Sets the treeish that gitattributes will be read from.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_ASKPASS`::
|
2013-01-21 19:17:53 +00:00
|
|
|
If this environment variable is set, then Git commands which need to
|
2010-08-30 13:40:29 +00:00
|
|
|
acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
|
2014-05-21 18:52:26 +00:00
|
|
|
will call this program with a suitable prompt as command-line argument
|
2016-06-08 17:23:16 +00:00
|
|
|
and read the password from its STDOUT. See also the `core.askPass`
|
2010-08-30 13:40:29 +00:00
|
|
|
option in linkgit:git-config[1].
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TERMINAL_PROMPT`::
|
2022-09-15 16:06:56 +00:00
|
|
|
If this Boolean environment variable is set to false, git will not prompt
|
2014-12-04 03:52:29 +00:00
|
|
|
on the terminal (e.g., when asking for HTTP authentication).
|
|
|
|
|
config: allow overriding of global and system configuration
In order to have git run in a fully controlled environment without any
misconfiguration, it may be desirable for users or scripts to override
global- and system-level configuration files. We already have a way of
doing this, which is to unset both HOME and XDG_CONFIG_HOME environment
variables and to set `GIT_CONFIG_NOGLOBAL=true`. This is quite kludgy,
and unsetting the first two variables likely has an impact on other
executables spawned by such a script.
The obvious way to fix this would be to introduce `GIT_CONFIG_NOGLOBAL`
as an equivalent to `GIT_CONFIG_NOSYSTEM`. But in the past, it has
turned out that this design is inflexible: we cannot test system-level
parsing of the git configuration in our test harness because there is no
way to change its location, so all tests run with `GIT_CONFIG_NOSYSTEM`
set.
Instead of doing the same mistake with `GIT_CONFIG_NOGLOBAL`, introduce
two new variables `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM`:
- If unset, git continues to use the usual locations.
- If set to a specific path, we skip reading the normal
configuration files and instead take the path. By setting the path
to `/dev/null`, no configuration will be loaded for the respective
level.
This implements the usecase where we want to execute code in a sanitized
environment without any potential misconfigurations via `/dev/null`, but
is more flexible and allows for more usecases than simply adding
`GIT_CONFIG_NOGLOBAL`.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-19 12:31:16 +00:00
|
|
|
`GIT_CONFIG_GLOBAL`::
|
|
|
|
`GIT_CONFIG_SYSTEM`::
|
|
|
|
Take the configuration from the given files instead from global or
|
|
|
|
system-level configuration files. If `GIT_CONFIG_SYSTEM` is set, the
|
|
|
|
system config file defined at build time (usually `/etc/gitconfig`)
|
|
|
|
will not be read. Likewise, if `GIT_CONFIG_GLOBAL` is set, neither
|
|
|
|
`$HOME/.gitconfig` nor `$XDG_CONFIG_HOME/git/config` will be read. Can
|
|
|
|
be set to `/dev/null` to skip reading configuration files of the
|
|
|
|
respective level.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_CONFIG_NOSYSTEM`::
|
2012-10-14 08:53:59 +00:00
|
|
|
Whether to skip reading settings from the system-wide
|
2022-09-15 16:06:56 +00:00
|
|
|
`$(prefix)/etc/gitconfig` file. This Boolean environment variable can
|
2012-10-14 08:53:59 +00:00
|
|
|
be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
|
|
|
|
predictable environment for a picky script, or you can set it
|
2022-09-15 16:06:56 +00:00
|
|
|
to true to temporarily avoid using a buggy `/etc/gitconfig` file while
|
2012-10-14 08:53:59 +00:00
|
|
|
waiting for someone with sufficient permissions to fix it.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_FLUSH`::
|
2024-01-04 10:20:17 +00:00
|
|
|
If this Boolean environment variable is set to true, then commands such
|
2010-01-09 23:33:00 +00:00
|
|
|
as 'git blame' (in incremental mode), 'git rev-list', 'git log',
|
core-tutorial: trim the section on Inspecting Changes
Back when the core tutorial was written, `log` and `whatchanged`
were scripted Porcelains. In the "Inspecting Changes" section that
talks about the plumbing commands in the diff family, it made sense
to use `log` and `whatchanged` as good examples of the use of these
plumbing commands, and because even these scripted Porcelains were
novelty (there wasn't the new end-user tutorial written), it made
some sense to illustrate uses of the `git log` (and `git
whatchanged`) scripted Porcelain commands.
But we no longer have scripted `log` and `whatchanged` to serve as
examples, and this document is not where the end users learn what
`git log` command is about. Stop at briefly mentioning the
possibility of combining rev-list with diff-tree to build your own
log, and leave the end-user documentation of `log` to the new
tutorial and the user manual.
Also resurrect the last version of `git-log`, `git-whatchanged`, and
`git-show` to serve as examples to contrib/examples/ directory.
While at it, remove 'whatchanged' from a list of sample commands
that are affected by GIT_FLUSH environment variable. This is not
meant to be an exhaustive list but as a list of typical ones, and an
old command that is kept primarily for backward compatibility does
not belong to it.
Helped-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-09 17:28:53 +00:00
|
|
|
'git check-attr' and 'git check-ignore' will
|
2013-04-11 12:05:13 +00:00
|
|
|
force a flush of the output stream after each record have been
|
|
|
|
flushed. If this
|
2024-01-04 10:20:17 +00:00
|
|
|
variable is set to false, the output of these commands will be done
|
2007-06-29 17:40:46 +00:00
|
|
|
using completely buffered I/O. If this environment variable is
|
2013-01-21 19:17:53 +00:00
|
|
|
not set, Git will choose buffered or record-oriented flushing
|
2007-06-29 17:40:46 +00:00
|
|
|
based on whether stdout appears to be redirected to a file or not.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE`::
|
2014-07-12 00:00:53 +00:00
|
|
|
Enables general trace messages, e.g. alias expansion, built-in
|
|
|
|
command execution and external command execution.
|
|
|
|
+
|
|
|
|
If this variable is set to "1", "2" or "true" (comparison
|
|
|
|
is case insensitive), trace messages will be printed to
|
|
|
|
stderr.
|
|
|
|
+
|
|
|
|
If the variable is set to an integer value greater than 2
|
|
|
|
and lower than 10 (strictly) then Git will interpret this
|
|
|
|
value as an open file descriptor and will try to write the
|
|
|
|
trace messages into this file descriptor.
|
|
|
|
+
|
|
|
|
Alternatively, if the variable is set to an absolute path
|
|
|
|
(starting with a '/' character), Git will interpret this
|
2018-09-04 00:05:44 +00:00
|
|
|
as a file path and will try to append the trace messages
|
|
|
|
to it.
|
2014-07-12 00:00:53 +00:00
|
|
|
+
|
|
|
|
Unsetting the variable, or setting it to empty, "0" or
|
|
|
|
"false" (case insensitive) disables trace messages.
|
2006-06-25 13:56:18 +00:00
|
|
|
|
2017-10-27 23:26:36 +00:00
|
|
|
`GIT_TRACE_FSMONITOR`::
|
|
|
|
Enables trace messages for the filesystem monitor extension.
|
|
|
|
See `GIT_TRACE` for available trace output options.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_PACK_ACCESS`::
|
2014-07-12 00:01:38 +00:00
|
|
|
Enables trace messages for all accesses to any packs. For each
|
2013-06-09 05:22:48 +00:00
|
|
|
access, the pack file name and an offset in the pack is
|
|
|
|
recorded. This may be helpful for troubleshooting some
|
|
|
|
pack-related performance problems.
|
2016-06-07 22:35:06 +00:00
|
|
|
See `GIT_TRACE` for available trace output options.
|
2013-06-09 05:22:48 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_PACKET`::
|
2014-07-12 00:00:53 +00:00
|
|
|
Enables trace messages for all packets coming in or out of a
|
|
|
|
given program. This can help with debugging object negotiation
|
|
|
|
or other protocol issues. Tracing is turned off at a packet
|
2016-06-07 22:35:06 +00:00
|
|
|
starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
|
|
|
|
See `GIT_TRACE` for available trace output options.
|
2014-07-12 00:00:53 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_PACKFILE`::
|
2015-06-16 17:23:20 +00:00
|
|
|
Enables tracing of packfiles sent or received by a
|
|
|
|
given program. Unlike other trace output, this trace is
|
|
|
|
verbatim: no headers, and no quoting of binary data. You almost
|
|
|
|
certainly want to direct into a file (e.g.,
|
|
|
|
`GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
|
|
|
|
the terminal or mixing it with other trace output.
|
|
|
|
+
|
|
|
|
Note that this is currently only implemented for the client side
|
|
|
|
of clones and fetches.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_PERFORMANCE`::
|
2014-07-12 00:07:01 +00:00
|
|
|
Enables performance related trace messages, e.g. total execution
|
|
|
|
time of each Git command.
|
2016-06-07 22:35:06 +00:00
|
|
|
See `GIT_TRACE` for available trace output options.
|
2014-07-12 00:07:01 +00:00
|
|
|
|
2020-09-09 10:15:08 +00:00
|
|
|
`GIT_TRACE_REFS`::
|
|
|
|
Enables trace messages for operations on the ref database.
|
|
|
|
See `GIT_TRACE` for available trace output options.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_SETUP`::
|
2014-07-12 00:00:53 +00:00
|
|
|
Enables trace messages printing the .git, working tree and current
|
|
|
|
working directory after Git has completed its setup phase.
|
2016-06-07 22:35:06 +00:00
|
|
|
See `GIT_TRACE` for available trace output options.
|
2014-07-12 00:00:53 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_TRACE_SHALLOW`::
|
2014-07-12 00:00:53 +00:00
|
|
|
Enables trace messages that can help debugging fetching /
|
|
|
|
cloning of shallow repositories.
|
2016-06-07 22:35:06 +00:00
|
|
|
See `GIT_TRACE` for available trace output options.
|
2013-06-09 05:22:49 +00:00
|
|
|
|
2016-07-06 20:38:06 +00:00
|
|
|
`GIT_TRACE_CURL`::
|
2016-05-23 13:44:02 +00:00
|
|
|
Enables a curl full trace dump of all incoming and outgoing data,
|
|
|
|
including descriptive information, of the git transport protocol.
|
2016-07-06 20:38:06 +00:00
|
|
|
This is similar to doing curl `--trace-ascii` on the command line.
|
|
|
|
See `GIT_TRACE` for available trace output options.
|
2016-05-23 13:44:02 +00:00
|
|
|
|
2018-01-19 00:28:02 +00:00
|
|
|
`GIT_TRACE_CURL_NO_DATA`::
|
|
|
|
When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
|
|
|
|
data (that is, only dump info lines and headers).
|
|
|
|
|
trace2: rename environment variables to GIT_TRACE2*
For an environment variable that is supposed to be set by users, the
GIT_TR2* env vars are just too unclear, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use
abbreviations, and in case of the few that do (GIT_DIR,
GIT_COMMON_DIR, GIT_DIFF_OPTS) it's quite obvious what the
abbreviations (DIR and OPTS) stand for. But what does TR stand for?
Track, traditional, trailer, transaction, transfer, transformation,
transition, translation, transplant, transport, traversal, tree,
trigger, truncate, trust, or ...?!
The trace2 facility, as the '2' suffix in its name suggests, is
supposed to eventually supercede Git's original trace facility. It's
reasonable to expect that the corresponding environment variables
follow suit, and after the original GIT_TRACE variables they are
called GIT_TRACE2; there is no such thing is 'GIT_TR'.
All trace2-specific config variables are, very sensibly, in the
'trace2' section, not in 'tr2'.
OTOH, we don't gain anything at all by omitting the last three
characters of "trace" from the names of these environment variables.
So let's rename all GIT_TR2* environment variables to GIT_TRACE2*,
before they make their way into a stable release.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19 14:43:08 +00:00
|
|
|
`GIT_TRACE2`::
|
2019-05-10 19:44:26 +00:00
|
|
|
Enables more detailed trace messages from the "trace2" library.
|
trace2: rename environment variables to GIT_TRACE2*
For an environment variable that is supposed to be set by users, the
GIT_TR2* env vars are just too unclear, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use
abbreviations, and in case of the few that do (GIT_DIR,
GIT_COMMON_DIR, GIT_DIFF_OPTS) it's quite obvious what the
abbreviations (DIR and OPTS) stand for. But what does TR stand for?
Track, traditional, trailer, transaction, transfer, transformation,
transition, translation, transplant, transport, traversal, tree,
trigger, truncate, trust, or ...?!
The trace2 facility, as the '2' suffix in its name suggests, is
supposed to eventually supercede Git's original trace facility. It's
reasonable to expect that the corresponding environment variables
follow suit, and after the original GIT_TRACE variables they are
called GIT_TRACE2; there is no such thing is 'GIT_TR'.
All trace2-specific config variables are, very sensibly, in the
'trace2' section, not in 'tr2'.
OTOH, we don't gain anything at all by omitting the last three
characters of "trace" from the names of these environment variables.
So let's rename all GIT_TR2* environment variables to GIT_TRACE2*,
before they make their way into a stable release.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19 14:43:08 +00:00
|
|
|
Output from `GIT_TRACE2` is a simple text-based format for human
|
2019-05-10 19:44:26 +00:00
|
|
|
readability.
|
|
|
|
+
|
2019-05-19 14:43:09 +00:00
|
|
|
If this variable is set to "1", "2" or "true" (comparison
|
|
|
|
is case insensitive), trace messages will be printed to
|
|
|
|
stderr.
|
|
|
|
+
|
|
|
|
If the variable is set to an integer value greater than 2
|
|
|
|
and lower than 10 (strictly) then Git will interpret this
|
|
|
|
value as an open file descriptor and will try to write the
|
|
|
|
trace messages into this file descriptor.
|
|
|
|
+
|
|
|
|
Alternatively, if the variable is set to an absolute path
|
|
|
|
(starting with a '/' character), Git will interpret this
|
|
|
|
as a file path and will try to append the trace messages
|
|
|
|
to it. If the path already exists and is a directory, the
|
|
|
|
trace messages will be written to files (one per process)
|
|
|
|
in that directory, named according to the last component
|
|
|
|
of the SID and an optional counter (to avoid filename
|
|
|
|
collisions).
|
|
|
|
+
|
|
|
|
In addition, if the variable is set to
|
2023-12-25 21:21:26 +00:00
|
|
|
`af_unix:[<socket-type>:]<absolute-pathname>`, Git will try
|
2019-05-19 14:43:09 +00:00
|
|
|
to open the path as a Unix Domain Socket. The socket type
|
|
|
|
can be either `stream` or `dgram`.
|
|
|
|
+
|
|
|
|
Unsetting the variable, or setting it to empty, "0" or
|
|
|
|
"false" (case insensitive) disables trace messages.
|
|
|
|
+
|
|
|
|
See link:technical/api-trace2.html[Trace2 documentation]
|
|
|
|
for full details.
|
|
|
|
|
2019-05-10 19:44:26 +00:00
|
|
|
|
trace2: rename environment variables to GIT_TRACE2*
For an environment variable that is supposed to be set by users, the
GIT_TR2* env vars are just too unclear, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use
abbreviations, and in case of the few that do (GIT_DIR,
GIT_COMMON_DIR, GIT_DIFF_OPTS) it's quite obvious what the
abbreviations (DIR and OPTS) stand for. But what does TR stand for?
Track, traditional, trailer, transaction, transfer, transformation,
transition, translation, transplant, transport, traversal, tree,
trigger, truncate, trust, or ...?!
The trace2 facility, as the '2' suffix in its name suggests, is
supposed to eventually supercede Git's original trace facility. It's
reasonable to expect that the corresponding environment variables
follow suit, and after the original GIT_TRACE variables they are
called GIT_TRACE2; there is no such thing is 'GIT_TR'.
All trace2-specific config variables are, very sensibly, in the
'trace2' section, not in 'tr2'.
OTOH, we don't gain anything at all by omitting the last three
characters of "trace" from the names of these environment variables.
So let's rename all GIT_TR2* environment variables to GIT_TRACE2*,
before they make their way into a stable release.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19 14:43:08 +00:00
|
|
|
`GIT_TRACE2_EVENT`::
|
2019-05-10 19:44:26 +00:00
|
|
|
This setting writes a JSON-based format that is suited for machine
|
2019-05-19 14:43:09 +00:00
|
|
|
interpretation.
|
|
|
|
See `GIT_TRACE2` for available trace output options and
|
|
|
|
link:technical/api-trace2.html[Trace2 documentation] for full details.
|
2019-05-10 19:44:26 +00:00
|
|
|
|
trace2: rename environment variables to GIT_TRACE2*
For an environment variable that is supposed to be set by users, the
GIT_TR2* env vars are just too unclear, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use
abbreviations, and in case of the few that do (GIT_DIR,
GIT_COMMON_DIR, GIT_DIFF_OPTS) it's quite obvious what the
abbreviations (DIR and OPTS) stand for. But what does TR stand for?
Track, traditional, trailer, transaction, transfer, transformation,
transition, translation, transplant, transport, traversal, tree,
trigger, truncate, trust, or ...?!
The trace2 facility, as the '2' suffix in its name suggests, is
supposed to eventually supercede Git's original trace facility. It's
reasonable to expect that the corresponding environment variables
follow suit, and after the original GIT_TRACE variables they are
called GIT_TRACE2; there is no such thing is 'GIT_TR'.
All trace2-specific config variables are, very sensibly, in the
'trace2' section, not in 'tr2'.
OTOH, we don't gain anything at all by omitting the last three
characters of "trace" from the names of these environment variables.
So let's rename all GIT_TR2* environment variables to GIT_TRACE2*,
before they make their way into a stable release.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19 14:43:08 +00:00
|
|
|
`GIT_TRACE2_PERF`::
|
|
|
|
In addition to the text-based messages available in `GIT_TRACE2`, this
|
2019-05-10 19:44:26 +00:00
|
|
|
setting writes a column-based format for understanding nesting
|
2019-05-19 14:43:09 +00:00
|
|
|
regions.
|
|
|
|
See `GIT_TRACE2` for available trace output options and
|
|
|
|
link:technical/api-trace2.html[Trace2 documentation] for full details.
|
2019-05-10 19:44:26 +00:00
|
|
|
|
2020-06-05 21:21:36 +00:00
|
|
|
`GIT_TRACE_REDACT`::
|
|
|
|
By default, when tracing is activated, Git redacts the values of
|
2021-11-10 23:51:28 +00:00
|
|
|
cookies, the "Authorization:" header, the "Proxy-Authorization:"
|
2022-09-15 16:06:56 +00:00
|
|
|
header and packfile URIs. Set this Boolean environment variable to false to prevent this
|
2021-11-10 23:51:28 +00:00
|
|
|
redaction.
|
2018-01-19 00:28:01 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_LITERAL_PATHSPECS`::
|
2022-09-15 16:06:56 +00:00
|
|
|
Setting this Boolean environment variable to true will cause Git to treat all
|
add global --literal-pathspecs option
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-19 22:37:30 +00:00
|
|
|
pathspecs literally, rather than as glob patterns. For example,
|
|
|
|
running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
|
|
|
|
for commits that touch the path `*.c`, not any paths that the
|
|
|
|
glob `*.c` matches. You might want this if you are feeding
|
2013-01-21 19:17:53 +00:00
|
|
|
literal paths to Git (e.g., paths previously given to you by
|
add global --literal-pathspecs option
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-19 22:37:30 +00:00
|
|
|
`git ls-tree`, `--raw` diff output, etc).
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_GLOB_PATHSPECS`::
|
2022-09-15 16:06:56 +00:00
|
|
|
Setting this Boolean environment variable to true will cause Git to treat all
|
2013-07-14 08:36:08 +00:00
|
|
|
pathspecs as glob patterns (aka "glob" magic).
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_NOGLOB_PATHSPECS`::
|
2022-09-15 16:06:56 +00:00
|
|
|
Setting this Boolean environment variable to true will cause Git to treat all
|
2013-07-14 08:36:08 +00:00
|
|
|
pathspecs as literal (aka "literal" magic).
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_ICASE_PATHSPECS`::
|
2022-09-15 16:06:56 +00:00
|
|
|
Setting this Boolean environment variable to true will cause Git to treat all
|
2013-07-14 08:36:09 +00:00
|
|
|
pathspecs as case-insensitive.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_REFLOG_ACTION`::
|
setup_reflog_action: document the rules for using GIT_REFLOG_ACTION
The set_reflog_action helper (in git-sh-setup) is designed to be
used once at the very top of a program, like this in "git am", for
example:
set_reflog_action am
The helper function sets the given string to GIT_REFLOG_ACTION only
when GIT_REFLOG_ACTION is not yet set. Thanks to this, "git am",
when run as the top-level program, will use "am" in GIT_REFLOG_ACTION
and the reflog entries made by whatever it does will record the
updates of refs done by "am".
Because of the conditional assignment, when "git am" is run as a
subprogram (i.e. an implementation detail) of "git rebase" that
already sets GIT_REFLOG_ACTION to its own name, the call in "git am"
to the helper function at the beginning will *not* have any effect.
So "git rebase" can do this:
set_reflog_action rebase
... do its own preparation, like checking out "onto" commit
... decide to do "format-patch" to "am" pipeline
git format-patch --stdout >mbox
git am mbox
and the reflog entries made inside "git am" invocation will say
"rebase", not "am".
Calls to "git" commands that update refs would use GIT_REFLOG_ACTION
to record who did that update. Most such calls in scripted Porcelains
do not define custom reflog message and rely on GIT_REFLOG_ACTION to
contain its (or its caller's, when it is called as a subprogram) name.
If a scripted Porcelain wants to record a custom reflog message for
a single invocation of "git" command (e.g. when "git rebase" uses
"git checkout" to detach HEAD at the commit a series is to be
replayed on), it needs to set GIT_REFLOG_ACTION to the custom
message and export it while calling the "git" command, but such an
assignment must be restricted to that single "git" invocation and
should not be left behind to affect later codepath.
Document the rules to avoid future confusion.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-19 17:54:00 +00:00
|
|
|
When a ref is updated, reflog entries are created to keep
|
|
|
|
track of the reason why the ref was updated (which is
|
|
|
|
typically the name of the high-level command that updated
|
|
|
|
the ref), in addition to the old and new values of the ref.
|
|
|
|
A scripted Porcelain command can use set_reflog_action
|
|
|
|
helper function in `git-sh-setup` to set its name to this
|
|
|
|
variable when it is invoked as the top level command by the
|
|
|
|
end user, to be recorded in the body of the reflog.
|
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_REF_PARANOIA`::
|
2022-09-15 16:06:56 +00:00
|
|
|
If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating
|
refs: turn on GIT_REF_PARANOIA by default
The original point of the GIT_REF_PARANOIA flag was to include broken
refs in iterations, so that possibly-destructive operations would not
silently ignore them (and would generally instead try to operate on the
oids and fail when the objects could not be accessed).
We already turned this on by default for some dangerous operations, like
"repack -ad" (where missing a reachability tip would mean dropping the
associated history). But it was not on for general use, even though it
could easily result in the spreading of corruption (e.g., imagine
cloning a repository which simply omits some of its refs because
their objects are missing; the result quietly succeeds even though you
did not clone everything!).
This patch turns on GIT_REF_PARANOIA by default. So a clone as mentioned
above would actually fail (upload-pack tells us about the broken ref,
and when we ask for the objects, pack-objects fails to deliver them).
This may be inconvenient when working with a corrupted repository, but:
- we are better off to err on the side of complaining about
corruption, and then provide mechanisms for explicitly loosening
safety.
- this is only one type of corruption anyway. If we are missing any
other objects in the history that _aren't_ ref tips, then we'd
behave similarly (happily show the ref, but then barf when we
started traversing).
We retain the GIT_REF_PARANOIA variable, but simply default it to "1"
instead of "0". That gives the user an escape hatch for loosening this
when working with a corrupt repository. It won't work across a remote
connection to upload-pack (because we can't necessarily set environment
variables on the remote), but there the client has other options (e.g.,
choosing which refs to fetch).
As a bonus, this also makes ref iteration faster in general (because we
don't have to call has_object_file() for each ref), though probably not
noticeably so in the general case. In a repo with a million refs, it
shaved a few hundred milliseconds off of upload-pack's advertisement;
that's noticeable, but most repos are not nearly that large.
The possible downside here is that any operation which iterates refs but
doesn't ever open their objects may now quietly claim to have X when the
object is corrupted (e.g., "git rev-list new-branch --not --all" will
treat a broken ref as uninteresting). But again, that's not really any
different than corruption below the ref level. We might have
refs/heads/old-branch as non-corrupt, but we are not actively checking
that we have the entire reachable history. Or the pointed-to object
could even be corrupted on-disk (but our "do we have it" check would
still succeed). In that sense, this is merely bringing ref-corruption in
line with general object corruption.
One alternative implementation would be to actually check for broken
refs, and then _immediately die_ if we see any. That would cause the
"rev-list --not --all" case above to abort immediately. But in many ways
that's the worst of all worlds:
- it still spends time looking up the objects an extra time
- it still doesn't catch corruption below the ref level
- it's even more inconvenient; with the current implementation of
GIT_REF_PARANOIA for something like upload-pack, we can make
the advertisement and let the client choose a non-broken piece of
history. If we bail as soon as we see a broken ref, they cannot even
see the advertisement.
The test changes here show some of the fallout. A non-destructive "git
repack -adk" now fails by default (but we can override it). Deleting a
broken ref now actually tells the hooks the correct "before" state,
rather than a confusing null oid.
Signed-off-by: Jeff King <peff@peff.net>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-09-24 18:46:13 +00:00
|
|
|
over lists of refs. Normally Git will try to include any such
|
|
|
|
refs, which may cause some operations to fail. This is usually
|
|
|
|
preferable, as potentially destructive operations (e.g.,
|
|
|
|
linkgit:git-prune[1]) are better off aborting rather than
|
|
|
|
ignoring broken refs (and thus considering the history they
|
|
|
|
point to as not worth saving). The default value is `1` (i.e.,
|
|
|
|
be paranoid about detecting and aborting all operations). You
|
|
|
|
should not normally need to set this to `0`, but it may be
|
|
|
|
useful when trying to salvage data from a corrupted repository.
|
2015-03-20 18:43:06 +00:00
|
|
|
|
commit-graph: introduce envvar to disable commit existence checks
Our `lookup_commit_in_graph()` helper tries to look up commits from the
commit graph and, if it doesn't exist there, falls back to parsing it
from the object database instead. This is intended to speed up the
lookup of any such commit that exists in the database. There is an edge
case though where the commit exists in the graph, but not in the object
database. To avoid returning such stale commits the helper function thus
double checks that any such commit parsed from the graph also exists in
the object database. This makes the function safe to use even when
commit graphs aren't updated regularly.
We're about to introduce the same pattern into other parts of our code
base though, namely `repo_parse_commit_internal()`. Here the extra
sanity check is a bit of a tougher sell: `lookup_commit_in_graph()` was
a newly introduced helper, and as such there was no performance hit by
adding this sanity check. If we added `repo_parse_commit_internal()`
with that sanity check right from the beginning as well, this would
probably never have been an issue to begin with. But by retrofitting it
with this sanity check now we do add a performance regression to
preexisting code, and thus there is a desire to avoid this or at least
give an escape hatch.
In practice, there is no inherent reason why either of those functions
should have the sanity check whereas the other one does not: either both
of them are able to detect this issue or none of them should be. This
also means that the default of whether we do the check should likely be
the same for both. To err on the side of caution, we thus rather want to
make `repo_parse_commit_internal()` stricter than to loosen the checks
that we already have in `lookup_commit_in_graph()`.
The escape hatch is added in the form of a new GIT_COMMIT_GRAPH_PARANOIA
environment variable that mirrors GIT_REF_PARANOIA. If enabled, which is
the default, we will double check that commits looked up in the commit
graph via `lookup_commit_in_graph()` also exist in the object database.
This same check will also be added in `repo_parse_commit_internal()`.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-10-31 07:16:13 +00:00
|
|
|
`GIT_COMMIT_GRAPH_PARANOIA`::
|
|
|
|
When loading a commit object from the commit-graph, Git performs an
|
|
|
|
existence check on the object in the object database. This is done to
|
|
|
|
avoid issues with stale commit-graphs that contain references to
|
|
|
|
already-deleted commits, but comes with a performance penalty.
|
|
|
|
+
|
commit-graph: disable GIT_COMMIT_GRAPH_PARANOIA by default
In 7a5d604443 (commit: detect commits that exist in commit-graph but not
in the ODB, 2023-10-31), we have introduced a new object existence check
into `repo_parse_commit_internal()` so that we do not parse commits via
the commit-graph that don't have a corresponding object in the object
database. This new check of course comes with a performance penalty,
which the commit put at around 30% for `git rev-list --topo-order`. But
there are in fact scenarios where the performance regression is even
higher. The following benchmark against linux.git with a fully-build
commit-graph:
Benchmark 1: git.v2.42.1 rev-list --count HEAD
Time (mean ± σ): 658.0 ms ± 5.2 ms [User: 613.5 ms, System: 44.4 ms]
Range (min … max): 650.2 ms … 666.0 ms 10 runs
Benchmark 2: git.v2.43.0-rc1 rev-list --count HEAD
Time (mean ± σ): 1.333 s ± 0.019 s [User: 1.263 s, System: 0.069 s]
Range (min … max): 1.302 s … 1.361 s 10 runs
Summary
git.v2.42.1 rev-list --count HEAD ran
2.03 ± 0.03 times faster than git.v2.43.0-rc1 rev-list --count HEAD
While it's a noble goal to ensure that results are the same regardless
of whether or not we have a potentially stale commit-graph, taking twice
as much time is a tough sell. Furthermore, we can generally assume that
the commit-graph will be updated by git-gc(1) or git-maintenance(1) as
required so that the case where the commit-graph is stale should not at
all be common.
With that in mind, default-disable GIT_COMMIT_GRAPH_PARANOIA and restore
the behaviour and thus performance previous to the mentioned commit. In
order to not be inconsistent, also disable this behaviour by default in
`lookup_commit_in_graph()`, where the object existence check has been
introduced right at its inception via f559d6d45e (revision: avoid
hitting packfiles when commits are in commit-graph, 2021-08-09).
This results in another speedup in commands that end up calling this
function, even though it's less pronounced compared to the above
benchmark. The following has been executed in linux.git with ~1.2
million references:
Benchmark 1: GIT_COMMIT_GRAPH_PARANOIA=true git rev-list --all --no-walk=unsorted
Time (mean ± σ): 2.947 s ± 0.003 s [User: 2.412 s, System: 0.534 s]
Range (min … max): 2.943 s … 2.949 s 3 runs
Benchmark 2: GIT_COMMIT_GRAPH_PARANOIA=false git rev-list --all --no-walk=unsorted
Time (mean ± σ): 2.724 s ± 0.030 s [User: 2.207 s, System: 0.514 s]
Range (min … max): 2.704 s … 2.759 s 3 runs
Summary
GIT_COMMIT_GRAPH_PARANOIA=false git rev-list --all --no-walk=unsorted ran
1.08 ± 0.01 times faster than GIT_COMMIT_GRAPH_PARANOIA=true git rev-list --all --no-walk=unsorted
So whereas 7a5d604443 initially introduced the logic to start doing an
object existence check in `repo_parse_commit_internal()` by default, the
updated logic will now instead cause `lookup_commit_in_graph()` to stop
doing the check by default. This behaviour continues to be tweakable by
the user via the GIT_COMMIT_GRAPH_PARANOIA environment variable.
Note that this requires us to amend some tests to manually turn on the
paranoid checks again. This is because we cause repository corruption by
manually deleting objects which are part of the commit graph already.
These circumstances shouldn't usually happen in repositories.
Reported-by: Jeff King <peff@peff.net>
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-11-24 11:08:21 +00:00
|
|
|
The default is "false", which disables the aforementioned behavior.
|
|
|
|
Setting this to "true" enables the existence check so that stale commits
|
|
|
|
will never be returned from the commit-graph at the cost of performance.
|
commit-graph: introduce envvar to disable commit existence checks
Our `lookup_commit_in_graph()` helper tries to look up commits from the
commit graph and, if it doesn't exist there, falls back to parsing it
from the object database instead. This is intended to speed up the
lookup of any such commit that exists in the database. There is an edge
case though where the commit exists in the graph, but not in the object
database. To avoid returning such stale commits the helper function thus
double checks that any such commit parsed from the graph also exists in
the object database. This makes the function safe to use even when
commit graphs aren't updated regularly.
We're about to introduce the same pattern into other parts of our code
base though, namely `repo_parse_commit_internal()`. Here the extra
sanity check is a bit of a tougher sell: `lookup_commit_in_graph()` was
a newly introduced helper, and as such there was no performance hit by
adding this sanity check. If we added `repo_parse_commit_internal()`
with that sanity check right from the beginning as well, this would
probably never have been an issue to begin with. But by retrofitting it
with this sanity check now we do add a performance regression to
preexisting code, and thus there is a desire to avoid this or at least
give an escape hatch.
In practice, there is no inherent reason why either of those functions
should have the sanity check whereas the other one does not: either both
of them are able to detect this issue or none of them should be. This
also means that the default of whether we do the check should likely be
the same for both. To err on the side of caution, we thus rather want to
make `repo_parse_commit_internal()` stricter than to loosen the checks
that we already have in `lookup_commit_in_graph()`.
The escape hatch is added in the form of a new GIT_COMMIT_GRAPH_PARANOIA
environment variable that mirrors GIT_REF_PARANOIA. If enabled, which is
the default, we will double check that commits looked up in the commit
graph via `lookup_commit_in_graph()` also exist in the object database.
This same check will also be added in `repo_parse_commit_internal()`.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-10-31 07:16:13 +00:00
|
|
|
|
2016-06-07 22:35:06 +00:00
|
|
|
`GIT_ALLOW_PROTOCOL`::
|
2016-12-14 22:39:52 +00:00
|
|
|
If set to a colon-separated list of protocols, behave as if
|
|
|
|
`protocol.allow` is set to `never`, and each of the listed
|
|
|
|
protocols has `protocol.<name>.allow` set to `always`
|
2022-07-19 18:32:15 +00:00
|
|
|
(overriding any existing configuration). See the description of
|
2016-12-14 22:39:52 +00:00
|
|
|
`protocol.allow` in linkgit:git-config[1] for more details.
|
|
|
|
|
|
|
|
`GIT_PROTOCOL_FROM_USER`::
|
2022-09-15 16:06:56 +00:00
|
|
|
Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are
|
2016-12-14 22:39:52 +00:00
|
|
|
configured to the `user` state. This is useful to restrict recursive
|
|
|
|
submodule initialization from an untrusted repository or for programs
|
|
|
|
which feed potentially-untrusted URLS to git commands. See
|
|
|
|
linkgit:git-config[1] for more details.
|
add global --literal-pathspecs option
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-19 22:37:30 +00:00
|
|
|
|
2017-10-16 17:55:24 +00:00
|
|
|
`GIT_PROTOCOL`::
|
|
|
|
For internal use only. Used in handshaking the wire protocol.
|
|
|
|
Contains a colon ':' separated list of keys with optional values
|
|
|
|
'key[=value]'. Presence of unknown keys and values must be
|
|
|
|
ignored.
|
docs/git: discuss server-side config for GIT_PROTOCOL
The v2 protocol requires that the GIT_PROTOCOL environment variable gets
passed around, but we don't have any documentation describing how this
is supposed to work. In particular, we need to note what server admins
might need to configure to make things work.
The definition of the GIT_PROTOCOL variable is probably the best place
for this, since:
- we deal with multiple transports (ssh, http, etc).
Transport-specific documentation (like the git-http-backend bits
added in the previous commit) are helpful for those transports, but
this gives a broader overview. Plus we do not have a specific
transport endpoint program for ssh, so this is a reasonable place to
mention it.
- the server side of the protocol involves multiple programs. For now,
upload-pack is the only endpoint which uses GIT_PROTOCOL, but that
will likely expand in the future. We're better off with a central
discussion of what the server admin might need to do. However, for
discoverability, this patch adds a pointer from upload-pack's
documentation.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-09-10 14:09:56 +00:00
|
|
|
+
|
|
|
|
Note that servers may need to be configured to allow this variable to
|
|
|
|
pass over some transports. It will be propagated automatically when
|
|
|
|
accessing local repositories (i.e., `file://` or a filesystem path), as
|
|
|
|
well as over the `git://` protocol. For git-over-http, it should work
|
|
|
|
automatically in most configurations, but see the discussion in
|
|
|
|
linkgit:git-http-backend[1]. For git-over-ssh, the ssh server may need
|
|
|
|
to be configured to allow clients to pass this variable (e.g., by using
|
|
|
|
`AcceptEnv GIT_PROTOCOL` with OpenSSH).
|
|
|
|
+
|
|
|
|
This configuration is optional. If the variable is not propagated, then
|
|
|
|
clients will fall back to the original "v0" protocol (but may miss out
|
|
|
|
on some performance improvements or features). This variable currently
|
|
|
|
only affects clones and fetches; it is not yet used for pushes (but may
|
|
|
|
be in the future).
|
2017-10-16 17:55:24 +00:00
|
|
|
|
git: add --no-optional-locks option
Some tools like IDEs or fancy editors may periodically run
commands like "git status" in the background to keep track
of the state of the repository. Some of these commands may
refresh the index and write out the result in an
opportunistic way: if they can get the index lock, then they
update the on-disk index with any updates they find. And if
not, then their in-core refresh is lost and just has to be
recomputed by the next caller.
But taking the index lock may conflict with other operations
in the repository. Especially ones that the user is doing
themselves, which _aren't_ opportunistic. In other words,
"git status" knows how to back off when somebody else is
holding the lock, but other commands don't know that status
would be happy to drop the lock if somebody else wanted it.
There are a couple possible solutions:
1. Have some kind of "pseudo-lock" that allows other
commands to tell status that they want the lock.
This is likely to be complicated and error-prone to
implement (and maybe even impossible with just
dotlocks to work from, as it requires some
inter-process communication).
2. Avoid background runs of commands like "git status"
that want to do opportunistic updates, preferring
instead plumbing like diff-files, etc.
This is awkward for a couple of reasons. One is that
"status --porcelain" reports a lot more about the
repository state than is available from individual
plumbing commands. And two is that we actually _do_
want to see the refreshed index. We just don't want to
take a lock or write out the result. Whereas commands
like diff-files expect us to refresh the index
separately and write it to disk so that they can depend
on the result. But that write is exactly what we're
trying to avoid.
3. Ask "status" not to lock or write the index.
This is easy to implement. The big downside is that any
work done in refreshing the index for such a call is
lost when the process exits. So a background process
may end up re-hashing a changed file multiple times
until the user runs a command that does an index
refresh themselves.
This patch implements the option 3. The idea (and the test)
is largely stolen from a Git for Windows patch by Johannes
Schindelin, 67e5ce7f63 (status: offer *not* to lock the
index and update it, 2016-08-12). The twist here is that
instead of making this an option to "git status", it becomes
a "git" option and matching environment variable.
The reason there is two-fold:
1. An environment variable is carried through to
sub-processes. And whether an invocation is a
background process or not should apply to the whole
process tree. So you could do "git --no-optional-locks
foo", and if "foo" is a script or alias that calls
"status", you'll still get the effect.
2. There may be other programs that want the same
treatment.
I've punted here on finding more callers to convert,
since "status" is the obvious one to call as a repeated
background job. But "git diff"'s opportunistic refresh
of the index may be a good candidate.
The test is taken from 67e5ce7f63, and it's worth repeating
Johannes's explanation:
Note that the regression test added in this commit does
not *really* verify that no index.lock file was written;
that test is not possible in a portable way. Instead, we
verify that .git/index is rewritten *only* when `git
status` is run without `--no-optional-locks`.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-27 06:54:30 +00:00
|
|
|
`GIT_OPTIONAL_LOCKS`::
|
2022-09-15 16:06:56 +00:00
|
|
|
If this Boolean environment variable is set to false, Git will complete any requested operation without
|
git: add --no-optional-locks option
Some tools like IDEs or fancy editors may periodically run
commands like "git status" in the background to keep track
of the state of the repository. Some of these commands may
refresh the index and write out the result in an
opportunistic way: if they can get the index lock, then they
update the on-disk index with any updates they find. And if
not, then their in-core refresh is lost and just has to be
recomputed by the next caller.
But taking the index lock may conflict with other operations
in the repository. Especially ones that the user is doing
themselves, which _aren't_ opportunistic. In other words,
"git status" knows how to back off when somebody else is
holding the lock, but other commands don't know that status
would be happy to drop the lock if somebody else wanted it.
There are a couple possible solutions:
1. Have some kind of "pseudo-lock" that allows other
commands to tell status that they want the lock.
This is likely to be complicated and error-prone to
implement (and maybe even impossible with just
dotlocks to work from, as it requires some
inter-process communication).
2. Avoid background runs of commands like "git status"
that want to do opportunistic updates, preferring
instead plumbing like diff-files, etc.
This is awkward for a couple of reasons. One is that
"status --porcelain" reports a lot more about the
repository state than is available from individual
plumbing commands. And two is that we actually _do_
want to see the refreshed index. We just don't want to
take a lock or write out the result. Whereas commands
like diff-files expect us to refresh the index
separately and write it to disk so that they can depend
on the result. But that write is exactly what we're
trying to avoid.
3. Ask "status" not to lock or write the index.
This is easy to implement. The big downside is that any
work done in refreshing the index for such a call is
lost when the process exits. So a background process
may end up re-hashing a changed file multiple times
until the user runs a command that does an index
refresh themselves.
This patch implements the option 3. The idea (and the test)
is largely stolen from a Git for Windows patch by Johannes
Schindelin, 67e5ce7f63 (status: offer *not* to lock the
index and update it, 2016-08-12). The twist here is that
instead of making this an option to "git status", it becomes
a "git" option and matching environment variable.
The reason there is two-fold:
1. An environment variable is carried through to
sub-processes. And whether an invocation is a
background process or not should apply to the whole
process tree. So you could do "git --no-optional-locks
foo", and if "foo" is a script or alias that calls
"status", you'll still get the effect.
2. There may be other programs that want the same
treatment.
I've punted here on finding more callers to convert,
since "status" is the obvious one to call as a repeated
background job. But "git diff"'s opportunistic refresh
of the index may be a good candidate.
The test is taken from 67e5ce7f63, and it's worth repeating
Johannes's explanation:
Note that the regression test added in this commit does
not *really* verify that no index.lock file was written;
that test is not possible in a portable way. Instead, we
verify that .git/index is rewritten *only* when `git
status` is run without `--no-optional-locks`.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-27 06:54:30 +00:00
|
|
|
performing any optional sub-operations that require taking a lock.
|
|
|
|
For example, this will prevent `git status` from refreshing the
|
|
|
|
index as a side effect. This is useful for processes running in
|
|
|
|
the background which do not want to cause lock contention with
|
|
|
|
other operations on the repository. Defaults to `1`.
|
|
|
|
|
2017-11-01 17:10:33 +00:00
|
|
|
`GIT_REDIRECT_STDIN`::
|
|
|
|
`GIT_REDIRECT_STDOUT`::
|
|
|
|
`GIT_REDIRECT_STDERR`::
|
|
|
|
Windows-only: allow redirecting the standard input/output/error
|
|
|
|
handles to paths specified by the environment variables. This is
|
|
|
|
particularly useful in multi-threaded applications where the
|
|
|
|
canonical way to pass standard handles via `CreateProcess()` is
|
|
|
|
not an option because it would require the handles to be marked
|
|
|
|
inheritable (and consequently *every* spawned process would
|
|
|
|
inherit them, possibly blocking regular Git operations). The
|
|
|
|
primary intended use case is to use named pipes for communication
|
|
|
|
(e.g. `\\.\pipe\my-git-stdin-123`).
|
|
|
|
+
|
|
|
|
Two special values are supported: `off` will simply close the
|
|
|
|
corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
|
|
|
|
`2>&1`, standard error will be redirected to the same handle as
|
|
|
|
standard output.
|
|
|
|
|
2017-12-03 21:27:39 +00:00
|
|
|
`GIT_PRINT_SHA1_ELLIPSIS` (deprecated)::
|
|
|
|
If set to `yes`, print an ellipsis following an
|
|
|
|
(abbreviated) SHA-1 value. This affects indications of
|
|
|
|
detached HEADs (linkgit:git-checkout[1]) and the raw
|
|
|
|
diff output (linkgit:git-diff[1]). Printing an
|
|
|
|
ellipsis in the cases mentioned is no longer considered
|
|
|
|
adequate and support for it is likely to be removed in the
|
|
|
|
foreseeable future (along with the variable).
|
|
|
|
|
2005-08-30 20:51:01 +00:00
|
|
|
Discussion[[Discussion]]
|
|
|
|
------------------------
|
2007-09-03 04:01:19 +00:00
|
|
|
|
|
|
|
More detail on the following is available from the
|
2013-01-21 19:17:53 +00:00
|
|
|
link:user-manual.html#git-concepts[Git concepts chapter of the
|
2008-06-30 22:01:21 +00:00
|
|
|
user-manual] and linkgit:gitcore-tutorial[7].
|
2007-09-03 04:01:19 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
A Git project normally consists of a working directory with a ".git"
|
2007-09-03 04:01:19 +00:00
|
|
|
subdirectory at the top level. The .git directory contains, among other
|
|
|
|
things, a compressed object database representing the complete history
|
|
|
|
of the project, an "index" file which links that history to the current
|
|
|
|
contents of the working tree, and named pointers into that history such
|
|
|
|
as tags and branch heads.
|
|
|
|
|
|
|
|
The object database contains objects of three main types: blobs, which
|
|
|
|
hold file data; trees, which point to blobs and other trees to build up
|
2007-12-18 06:07:36 +00:00
|
|
|
directory hierarchies; and commits, which each reference a single tree
|
2007-09-03 04:01:19 +00:00
|
|
|
and some number of parent commits.
|
|
|
|
|
|
|
|
The commit, equivalent to what other systems call a "changeset" or
|
|
|
|
"version", represents a step in the project's history, and each parent
|
|
|
|
represents an immediately preceding step. Commits with more than one
|
|
|
|
parent represent merges of independent lines of development.
|
|
|
|
|
2013-04-15 17:49:04 +00:00
|
|
|
All objects are named by the SHA-1 hash of their contents, normally
|
2007-09-03 04:01:19 +00:00
|
|
|
written as a string of 40 hex digits. Such names are globally unique.
|
|
|
|
The entire history leading up to a commit can be vouched for by signing
|
|
|
|
just that commit. A fourth object type, the tag, is provided for this
|
|
|
|
purpose.
|
|
|
|
|
|
|
|
When first created, objects are stored in individual files, but for
|
|
|
|
efficiency may later be compressed together into "pack files".
|
|
|
|
|
|
|
|
Named pointers called refs mark interesting points in history. A ref
|
2023-12-15 20:32:41 +00:00
|
|
|
may contain the SHA-1 name of an object or the name of another ref (the
|
|
|
|
latter is called a "symbolic ref").
|
|
|
|
Refs with names beginning `refs/head/` contain the SHA-1 name of the most
|
2013-04-15 17:49:04 +00:00
|
|
|
recent commit (or "head") of a branch under development. SHA-1 names of
|
2023-12-15 20:32:41 +00:00
|
|
|
tags of interest are stored under `refs/tags/`. A symbolic ref named
|
2007-09-03 04:01:19 +00:00
|
|
|
`HEAD` contains the name of the currently checked-out branch.
|
|
|
|
|
|
|
|
The index file is initialized with a list of all paths and, for each
|
|
|
|
path, a blob object and a set of attributes. The blob object represents
|
|
|
|
the contents of the file as of the head of the current branch. The
|
|
|
|
attributes (last modified time, size, etc.) are taken from the
|
|
|
|
corresponding file in the working tree. Subsequent changes to the
|
|
|
|
working tree can be found by comparing these attributes. The index may
|
|
|
|
be updated with new content, and new commits may be created from the
|
|
|
|
content stored in the index.
|
|
|
|
|
|
|
|
The index is also capable of storing multiple entries (called "stages")
|
|
|
|
for a given pathname. These stages are used to hold the various
|
|
|
|
unmerged version of a file when a merge is in progress.
|
2005-05-22 17:44:16 +00:00
|
|
|
|
2012-08-17 19:48:52 +00:00
|
|
|
FURTHER DOCUMENTATION
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
See the references in the "description" section to get started
|
2013-01-21 19:17:53 +00:00
|
|
|
using Git. The following is probably more detail than necessary
|
2012-08-17 19:48:52 +00:00
|
|
|
for a first-time user.
|
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
The link:user-manual.html#git-concepts[Git concepts chapter of the
|
2012-08-17 19:48:52 +00:00
|
|
|
user-manual] and linkgit:gitcore-tutorial[7] both provide
|
2013-01-21 19:17:53 +00:00
|
|
|
introductions to the underlying Git architecture.
|
2012-08-17 19:48:52 +00:00
|
|
|
|
|
|
|
See linkgit:gitworkflows[7] for an overview of recommended workflows.
|
|
|
|
|
|
|
|
See also the link:howto-index.html[howto] documents for some useful
|
|
|
|
examples.
|
|
|
|
|
|
|
|
The internals are documented in the
|
2013-01-21 19:16:20 +00:00
|
|
|
link:technical/api-index.html[Git API documentation].
|
2012-08-17 19:48:52 +00:00
|
|
|
|
|
|
|
Users migrating from CVS may also want to
|
|
|
|
read linkgit:gitcvs-migration[7].
|
|
|
|
|
|
|
|
|
2005-11-15 23:31:25 +00:00
|
|
|
Authors
|
|
|
|
-------
|
2011-03-11 05:52:08 +00:00
|
|
|
Git was started by Linus Torvalds, and is currently maintained by Junio
|
2013-01-21 19:17:53 +00:00
|
|
|
C Hamano. Numerous contributions have come from the Git mailing list
|
2023-11-24 03:35:12 +00:00
|
|
|
<git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary
|
2012-12-12 18:06:24 +00:00
|
|
|
gives you a more complete list of contributors.
|
|
|
|
|
|
|
|
If you have a clone of git.git itself, the
|
2011-03-13 03:00:38 +00:00
|
|
|
output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
|
|
|
|
the authors for specific parts of the project.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2010-08-02 16:07:39 +00:00
|
|
|
Reporting Bugs
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Report bugs to the Git mailing list <git@vger.kernel.org> where the
|
|
|
|
development and maintenance is primarily done. You do not have to be
|
2018-09-28 21:20:49 +00:00
|
|
|
subscribed to the list to send a message there. See the list archive
|
2019-11-27 12:53:43 +00:00
|
|
|
at https://lore.kernel.org/git for previous bug reports and other
|
2018-09-28 21:20:49 +00:00
|
|
|
discussions.
|
2010-08-02 16:07:39 +00:00
|
|
|
|
2018-03-08 15:08:20 +00:00
|
|
|
Issues which are security relevant should be disclosed privately to
|
|
|
|
the Git Security mailing list <git-security@googlegroups.com>.
|
|
|
|
|
2008-05-29 17:21:46 +00:00
|
|
|
SEE ALSO
|
|
|
|
--------
|
|
|
|
linkgit:gittutorial[7], linkgit:gittutorial-2[7],
|
2014-10-10 21:25:37 +00:00
|
|
|
linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
|
2008-05-29 17:21:46 +00:00
|
|
|
linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
|
2009-06-06 13:11:07 +00:00
|
|
|
linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
|
|
|
|
linkgit:gitworkflows[7]
|
2008-05-29 17:21:46 +00:00
|
|
|
|
2005-05-10 21:32:30 +00:00
|
|
|
GIT
|
|
|
|
---
|
2008-06-06 07:07:32 +00:00
|
|
|
Part of the linkgit:git[1] suite
|