| 1 | git(1) |
| 2 | ====== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git - the stupid content tracker |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>] |
| 13 | [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] |
| 14 | [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--no-lazy-fetch] |
| 15 | [--no-optional-locks] [--no-advice] [--bare] [--git-dir=<path>] |
| 16 | [--work-tree=<path>] [--namespace=<name>] [--config-env=<name>=<envvar>] |
| 17 | <command> [<args>] |
| 18 | |
| 19 | DESCRIPTION |
| 20 | ----------- |
| 21 | Git is a fast, scalable, distributed revision control system with an |
| 22 | unusually rich command set that provides both high-level operations |
| 23 | and full access to internals. |
| 24 | |
| 25 | See linkgit:gittutorial[7] to get started, then see |
| 26 | linkgit:giteveryday[7] for a useful minimum set of |
| 27 | commands. The link:user-manual.html[Git User's Manual] has a more |
| 28 | in-depth introduction. |
| 29 | |
| 30 | After you mastered the basic concepts, you can come back to this |
| 31 | page to learn what commands Git offers. You can learn more about |
| 32 | individual Git commands with "git help command". linkgit:gitcli[7] |
| 33 | manual page gives you an overview of the command-line command syntax. |
| 34 | |
| 35 | A formatted and hyperlinked copy of the latest Git documentation |
| 36 | can be viewed at https://git.github.io/htmldocs/git.html |
| 37 | or https://git-scm.com/docs. |
| 38 | |
| 39 | |
| 40 | OPTIONS |
| 41 | ------- |
| 42 | -v:: |
| 43 | --version:: |
| 44 | Prints the Git suite version that the 'git' program came from. |
| 45 | + |
| 46 | This option is internally converted to `git version ...` and accepts |
| 47 | the same options as the linkgit:git-version[1] command. If `--help` is |
| 48 | also given, it takes precedence over `--version`. |
| 49 | |
| 50 | -h:: |
| 51 | --help:: |
| 52 | Prints the synopsis and a list of the most commonly used |
| 53 | commands. If the option `--all` or `-a` is given then all |
| 54 | available commands are printed. If a Git command is named this |
| 55 | option will bring up the manual page for that command. |
| 56 | + |
| 57 | Other options are available to control how the manual page is |
| 58 | displayed. See linkgit:git-help[1] for more information, |
| 59 | because `git --help ...` is converted internally into `git |
| 60 | help ...`. |
| 61 | |
| 62 | -C <path>:: |
| 63 | Run as if git was started in '<path>' instead of the current working |
| 64 | directory. When multiple `-C` options are given, each subsequent |
| 65 | non-absolute `-C <path>` is interpreted relative to the preceding `-C |
| 66 | <path>`. If '<path>' is present but empty, e.g. `-C ""`, then the |
| 67 | current working directory is left unchanged. |
| 68 | + |
| 69 | This option affects options that expect path name like `--git-dir` and |
| 70 | `--work-tree` in that their interpretations of the path names would be |
| 71 | made relative to the working directory caused by the `-C` option. For |
| 72 | example the following invocations are equivalent: |
| 73 | |
| 74 | git --git-dir=a.git --work-tree=b -C c status |
| 75 | git --git-dir=c/a.git --work-tree=c/b status |
| 76 | |
| 77 | -c <name>=<value>:: |
| 78 | Pass a configuration parameter to the command. The value |
| 79 | given will override values from configuration files. |
| 80 | The <name> is expected in the same format as listed by |
| 81 | 'git config' (subkeys separated by dots). |
| 82 | + |
| 83 | Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets |
| 84 | `foo.bar` to the boolean true value (just like `[foo]bar` would in a |
| 85 | config file). Including the equals but with an empty value (like `git -c |
| 86 | foo.bar= ...`) sets `foo.bar` to the empty string which `git config |
| 87 | --type=bool` will convert to `false`. |
| 88 | |
| 89 | --config-env=<name>=<envvar>:: |
| 90 | Like `-c <name>=<value>`, give configuration variable |
| 91 | '<name>' a value, where <envvar> is the name of an |
| 92 | environment variable from which to retrieve the value. Unlike |
| 93 | `-c` there is no shortcut for directly setting the value to an |
| 94 | empty string, instead the environment variable itself must be |
| 95 | set to the empty string. It is an error if the `<envvar>` does not exist |
| 96 | in the environment. `<envvar>` may not contain an equals sign |
| 97 | to avoid ambiguity with `<name>` containing one. |
| 98 | + |
| 99 | This is useful for cases where you want to pass transitory |
| 100 | configuration options to git, but are doing so on operating systems |
| 101 | where other processes might be able to read your command line |
| 102 | (e.g. `/proc/self/cmdline`), but not your environment |
| 103 | (e.g. `/proc/self/environ`). That behavior is the default on |
| 104 | Linux, but may not be on your system. |
| 105 | + |
| 106 | Note that this might add security for variables such as |
| 107 | `http.extraHeader` where the sensitive information is part of |
| 108 | the value, but not e.g. `url.<base>.insteadOf` where the |
| 109 | sensitive information can be part of the key. |
| 110 | |
| 111 | --exec-path[=<path>]:: |
| 112 | Path to wherever your core Git programs are installed. |
| 113 | This can also be controlled by setting the GIT_EXEC_PATH |
| 114 | environment variable. If no path is given, 'git' will print |
| 115 | the current setting and then exit. |
| 116 | |
| 117 | --html-path:: |
| 118 | Print the path, without trailing slash, where Git's HTML |
| 119 | documentation is installed and exit. |
| 120 | |
| 121 | --man-path:: |
| 122 | Print the manpath (see `man(1)`) for the man pages for |
| 123 | this version of Git and exit. |
| 124 | |
| 125 | --info-path:: |
| 126 | Print the path where the Info files documenting this |
| 127 | version of Git are installed and exit. |
| 128 | |
| 129 | -p:: |
| 130 | --paginate:: |
| 131 | Pipe all output into 'less' (or if set, $PAGER) if standard |
| 132 | output is a terminal. This overrides the `pager.<cmd>` |
| 133 | configuration options (see the "Configuration Mechanism" section |
| 134 | below). |
| 135 | |
| 136 | -P:: |
| 137 | --no-pager:: |
| 138 | Do not pipe Git output into a pager. |
| 139 | |
| 140 | --git-dir=<path>:: |
| 141 | Set the path to the repository (".git" directory). This can also be |
| 142 | controlled by setting the `GIT_DIR` environment variable. It can be |
| 143 | an absolute path or relative path to current working directory. |
| 144 | + |
| 145 | Specifying the location of the ".git" directory using this |
| 146 | option (or `GIT_DIR` environment variable) turns off the |
| 147 | repository discovery that tries to find a directory with |
| 148 | ".git" subdirectory (which is how the repository and the |
| 149 | top-level of the working tree are discovered), and tells Git |
| 150 | that you are at the top level of the working tree. If you |
| 151 | are not at the top-level directory of the working tree, you |
| 152 | should tell Git where the top-level of the working tree is, |
| 153 | with the `--work-tree=<path>` option (or `GIT_WORK_TREE` |
| 154 | environment variable) |
| 155 | + |
| 156 | If you just want to run git as if it was started in `<path>` then use |
| 157 | `git -C <path>`. |
| 158 | |
| 159 | --work-tree=<path>:: |
| 160 | Set the path to the working tree. It can be an absolute path |
| 161 | or a path relative to the current working directory. |
| 162 | This can also be controlled by setting the GIT_WORK_TREE |
| 163 | environment variable and the core.worktree configuration |
| 164 | variable (see core.worktree in linkgit:git-config[1] for a |
| 165 | more detailed discussion). |
| 166 | |
| 167 | --namespace=<path>:: |
| 168 | Set the Git namespace. See linkgit:gitnamespaces[7] for more |
| 169 | details. Equivalent to setting the `GIT_NAMESPACE` environment |
| 170 | variable. |
| 171 | |
| 172 | --bare:: |
| 173 | Treat the repository as a bare repository. If GIT_DIR |
| 174 | environment is not set, it is set to the current working |
| 175 | directory. |
| 176 | |
| 177 | --no-replace-objects:: |
| 178 | Do not use replacement refs to replace Git objects. |
| 179 | This is equivalent to exporting the `GIT_NO_REPLACE_OBJECTS` |
| 180 | environment variable with any value. |
| 181 | See linkgit:git-replace[1] for more information. |
| 182 | |
| 183 | --no-lazy-fetch:: |
| 184 | Do not fetch missing objects from the promisor remote on |
| 185 | demand. Useful together with `git cat-file -e <object>` to |
| 186 | see if the object is locally available. |
| 187 | This is equivalent to setting the `GIT_NO_LAZY_FETCH` |
| 188 | environment variable to `1`. |
| 189 | |
| 190 | --no-optional-locks:: |
| 191 | Do not perform optional operations that require locks. This is |
| 192 | equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`. |
| 193 | |
| 194 | --no-advice:: |
| 195 | Disable all advice hints from being printed. |
| 196 | |
| 197 | --literal-pathspecs:: |
| 198 | Treat pathspecs literally (i.e. no globbing, no pathspec magic). |
| 199 | This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment |
| 200 | variable to `1`. |
| 201 | |
| 202 | --glob-pathspecs:: |
| 203 | Add "glob" magic to all pathspec. This is equivalent to setting |
| 204 | the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling |
| 205 | globbing on individual pathspecs can be done using pathspec |
| 206 | magic ":(literal)" |
| 207 | |
| 208 | --noglob-pathspecs:: |
| 209 | Add "literal" magic to all pathspec. This is equivalent to setting |
| 210 | the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling |
| 211 | globbing on individual pathspecs can be done using pathspec |
| 212 | magic ":(glob)" |
| 213 | |
| 214 | --icase-pathspecs:: |
| 215 | Add "icase" magic to all pathspec. This is equivalent to setting |
| 216 | the `GIT_ICASE_PATHSPECS` environment variable to `1`. |
| 217 | |
| 218 | --list-cmds=<group>[,<group>...]:: |
| 219 | List commands by group. This is an internal/experimental |
| 220 | option and may change or be removed in the future. Supported |
| 221 | groups are: builtins, parseopt (builtin commands that use |
| 222 | parse-options), deprecated (deprecated builtins), |
| 223 | main (all commands in libexec directory), |
| 224 | others (all other commands in `$PATH` that have git- prefix), |
| 225 | list-<category> (see categories in command-list.txt), |
| 226 | nohelpers (exclude helper commands), alias and config |
| 227 | (retrieve command list from config variable completion.commands) |
| 228 | |
| 229 | --attr-source=<tree-ish>:: |
| 230 | Read gitattributes from <tree-ish> instead of the worktree. See |
| 231 | linkgit:gitattributes[5]. This is equivalent to setting the |
| 232 | `GIT_ATTR_SOURCE` environment variable. |
| 233 | |
| 234 | GIT COMMANDS |
| 235 | ------------ |
| 236 | |
| 237 | We divide Git into high level ("porcelain") commands and low level |
| 238 | ("plumbing") commands. For defining command aliases, see |
| 239 | linkgit:git-config[1] and look for descriptions of `alias.*`. |
| 240 | For installing custom "git" subcommands, see the description for |
| 241 | the 'PATH' environment variable in this manual. |
| 242 | |
| 243 | High-level commands (porcelain) |
| 244 | ------------------------------- |
| 245 | |
| 246 | We separate the porcelain commands into the main commands and some |
| 247 | ancillary user utilities. |
| 248 | |
| 249 | Main porcelain commands |
| 250 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 251 | |
| 252 | include::{build_dir}/cmds-mainporcelain.adoc[] |
| 253 | |
| 254 | Ancillary Commands |
| 255 | ~~~~~~~~~~~~~~~~~~ |
| 256 | Manipulators: |
| 257 | |
| 258 | include::{build_dir}/cmds-ancillarymanipulators.adoc[] |
| 259 | |
| 260 | Interrogators: |
| 261 | |
| 262 | include::{build_dir}/cmds-ancillaryinterrogators.adoc[] |
| 263 | |
| 264 | |
| 265 | Interacting with Others |
| 266 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 267 | |
| 268 | These commands are to interact with foreign SCM and with other |
| 269 | people via patch over e-mail. |
| 270 | |
| 271 | include::{build_dir}/cmds-foreignscminterface.adoc[] |
| 272 | |
| 273 | Reset, restore and revert |
| 274 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 275 | There are three commands with similar names: `git reset`, |
| 276 | `git restore` and `git revert`. |
| 277 | |
| 278 | * linkgit:git-revert[1] is about making a new commit that reverts the |
| 279 | changes made by other commits. |
| 280 | |
| 281 | * linkgit:git-restore[1] is about restoring files in the working tree |
| 282 | from either the index or another commit. This command does not |
| 283 | update your branch. The command can also be used to restore files in |
| 284 | the index from another commit. |
| 285 | |
| 286 | * linkgit:git-reset[1] is about updating your branch, moving the tip |
| 287 | in order to add or remove commits from the branch. This operation |
| 288 | changes the commit history. |
| 289 | + |
| 290 | `git reset` can also be used to restore the index, overlapping with |
| 291 | `git restore`. |
| 292 | |
| 293 | |
| 294 | Low-level commands (plumbing) |
| 295 | ----------------------------- |
| 296 | |
| 297 | Although Git includes its |
| 298 | own porcelain layer, its low-level commands are sufficient to support |
| 299 | development of alternative porcelains. Developers of such porcelains |
| 300 | might start by reading about linkgit:git-update-index[1] and |
| 301 | linkgit:git-read-tree[1]. |
| 302 | |
| 303 | The interface (input, output, set of options and the semantics) |
| 304 | to these low-level commands are meant to be a lot more stable |
| 305 | than Porcelain level commands, because these commands are |
| 306 | primarily for scripted use. The interface to Porcelain commands |
| 307 | on the other hand are subject to change in order to improve the |
| 308 | end user experience. |
| 309 | |
| 310 | The following description divides |
| 311 | the low-level commands into commands that manipulate objects (in |
| 312 | the repository, index, and working tree), commands that interrogate and |
| 313 | compare objects, and commands that move objects and references between |
| 314 | repositories. |
| 315 | |
| 316 | |
| 317 | Manipulation commands |
| 318 | ~~~~~~~~~~~~~~~~~~~~~ |
| 319 | |
| 320 | include::{build_dir}/cmds-plumbingmanipulators.adoc[] |
| 321 | |
| 322 | |
| 323 | Interrogation commands |
| 324 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 325 | |
| 326 | include::{build_dir}/cmds-plumbinginterrogators.adoc[] |
| 327 | |
| 328 | In general, the interrogate commands do not touch the files in |
| 329 | the working tree. |
| 330 | |
| 331 | |
| 332 | Syncing repositories |
| 333 | ~~~~~~~~~~~~~~~~~~~~ |
| 334 | |
| 335 | include::{build_dir}/cmds-synchingrepositories.adoc[] |
| 336 | |
| 337 | The following are helper commands used by the above; end users |
| 338 | typically do not use them directly. |
| 339 | |
| 340 | include::{build_dir}/cmds-synchelpers.adoc[] |
| 341 | |
| 342 | |
| 343 | Internal helper commands |
| 344 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 345 | |
| 346 | These are internal helper commands used by other commands; end |
| 347 | users typically do not use them directly. |
| 348 | |
| 349 | include::{build_dir}/cmds-purehelpers.adoc[] |
| 350 | |
| 351 | Guides |
| 352 | ------ |
| 353 | |
| 354 | The following documentation pages are guides about Git concepts. |
| 355 | |
| 356 | include::{build_dir}/cmds-guide.adoc[] |
| 357 | |
| 358 | Repository, command and file interfaces |
| 359 | --------------------------------------- |
| 360 | |
| 361 | This documentation discusses repository and command interfaces which |
| 362 | users are expected to interact with directly. See `--user-formats` in |
| 363 | linkgit:git-help[1] for more details on the criteria. |
| 364 | |
| 365 | include::{build_dir}/cmds-userinterfaces.adoc[] |
| 366 | |
| 367 | File formats, protocols and other developer interfaces |
| 368 | ------------------------------------------------------ |
| 369 | |
| 370 | This documentation discusses file formats, over-the-wire protocols and |
| 371 | other git developer interfaces. See `--developer-interfaces` in |
| 372 | linkgit:git-help[1]. |
| 373 | |
| 374 | include::{build_dir}/cmds-developerinterfaces.adoc[] |
| 375 | |
| 376 | Configuration Mechanism |
| 377 | ----------------------- |
| 378 | |
| 379 | Git uses a simple text format to store customizations that are per |
| 380 | repository and are per user. Such a configuration file may look |
| 381 | like this: |
| 382 | |
| 383 | ------------ |
| 384 | # |
| 385 | # A '#' or ';' character indicates a comment. |
| 386 | # |
| 387 | |
| 388 | ; core variables |
| 389 | [core] |
| 390 | ; Don't trust file modes |
| 391 | filemode = false |
| 392 | |
| 393 | ; user identity |
| 394 | [user] |
| 395 | name = "Junio C Hamano" |
| 396 | email = "gitster@pobox.com" |
| 397 | |
| 398 | ------------ |
| 399 | |
| 400 | Various commands read from the configuration file and adjust |
| 401 | their operation accordingly. See linkgit:git-config[1] for a |
| 402 | list and more details about the configuration mechanism. |
| 403 | |
| 404 | |
| 405 | Identifier Terminology |
| 406 | ---------------------- |
| 407 | <object>:: |
| 408 | Indicates the object name for any type of object. |
| 409 | |
| 410 | <blob>:: |
| 411 | Indicates a blob object name. |
| 412 | |
| 413 | <tree>:: |
| 414 | Indicates a tree object name. |
| 415 | |
| 416 | <commit>:: |
| 417 | Indicates a commit object name. |
| 418 | |
| 419 | <tree-ish>:: |
| 420 | Indicates a tree, commit or tag object name. A |
| 421 | command that takes a <tree-ish> argument ultimately wants to |
| 422 | operate on a <tree> object but automatically dereferences |
| 423 | <commit> and <tag> objects that point at a <tree>. |
| 424 | |
| 425 | <commit-ish>:: |
| 426 | Indicates a commit or tag object name. A |
| 427 | command that takes a <commit-ish> argument ultimately wants to |
| 428 | operate on a <commit> object but automatically dereferences |
| 429 | <tag> objects that point at a <commit>. |
| 430 | |
| 431 | <type>:: |
| 432 | Indicates that an object type is required. |
| 433 | Currently one of: `blob`, `tree`, `commit`, or `tag`. |
| 434 | |
| 435 | <file>:: |
| 436 | Indicates a filename - almost always relative to the |
| 437 | root of the tree structure `GIT_INDEX_FILE` describes. |
| 438 | |
| 439 | Symbolic Identifiers |
| 440 | -------------------- |
| 441 | Any Git command accepting any <object> can also use the following |
| 442 | symbolic notation: |
| 443 | |
| 444 | HEAD:: |
| 445 | indicates the head of the current branch. |
| 446 | |
| 447 | <tag>:: |
| 448 | a valid tag 'name' |
| 449 | (i.e. a `refs/tags/<tag>` reference). |
| 450 | |
| 451 | <head>:: |
| 452 | a valid head 'name' |
| 453 | (i.e. a `refs/heads/<head>` reference). |
| 454 | |
| 455 | For a more complete list of ways to spell object names, see |
| 456 | "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. |
| 457 | |
| 458 | |
| 459 | File/Directory Structure |
| 460 | ------------------------ |
| 461 | |
| 462 | Please see the linkgit:gitrepository-layout[5] document. |
| 463 | |
| 464 | Read linkgit:githooks[5] for more details about each hook. |
| 465 | |
| 466 | Higher level SCMs may provide and manage additional information in the |
| 467 | `$GIT_DIR`. |
| 468 | |
| 469 | |
| 470 | Terminology |
| 471 | ----------- |
| 472 | Please see linkgit:gitglossary[7]. |
| 473 | |
| 474 | |
| 475 | Environment Variables |
| 476 | --------------------- |
| 477 | Various Git commands pay attention to environment variables and change |
| 478 | their behavior. The environment variables marked as "Boolean" take |
| 479 | their values the same way as Boolean valued configuration variables, i.e., |
| 480 | "true", "yes", "on" and positive numbers are taken as "yes", while "false", |
| 481 | "no", "off", and "0" are taken as "no". |
| 482 | |
| 483 | Here are the variables: |
| 484 | |
| 485 | System |
| 486 | ~~~~~~ |
| 487 | `HOME`:: |
| 488 | Specifies the path to the user's home directory. On Windows, if |
| 489 | unset, Git will set a process environment variable equal to: |
| 490 | `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist; |
| 491 | otherwise `$USERPROFILE` if `$USERPROFILE` exists. |
| 492 | |
| 493 | `PATH`:: |
| 494 | When a user runs 'git <command>' that is not part of the core Git programs |
| 495 | (installed in GIT_EXEC_PATH), 'git-<command>' that is runnable by the user |
| 496 | in a directory on `$PATH` is invoked. Argument passed after the command |
| 497 | name are passed as-is to the program. To execute `git <foo>`, `git` finds |
| 498 | command `<foo>` (either a core Git program found in 'GIT_EXEC_PATH', or a |
| 499 | custom one in a directory on 'PATH'), before trying `foo` as an alias. |
| 500 | |
| 501 | The Git Repository |
| 502 | ~~~~~~~~~~~~~~~~~~ |
| 503 | These environment variables apply to 'all' core Git commands. Nb: it |
| 504 | is worth noting that they may be used/overridden by SCMS sitting above |
| 505 | Git so take care if using a foreign front-end. |
| 506 | |
| 507 | `GIT_INDEX_FILE`:: |
| 508 | This environment variable specifies an alternate |
| 509 | index file. If not specified, the default of `$GIT_DIR/index` |
| 510 | is used. |
| 511 | |
| 512 | `GIT_INDEX_VERSION`:: |
| 513 | This environment variable specifies what index version is used |
| 514 | when writing the index file out. It won't affect existing index |
| 515 | files. By default index file version 2 or 3 is used. See |
| 516 | linkgit:git-update-index[1] for more information. |
| 517 | |
| 518 | `GIT_OBJECT_DIRECTORY`:: |
| 519 | If the object storage directory is specified via this |
| 520 | environment variable then the sha1 directories are created |
| 521 | underneath - otherwise the default `$GIT_DIR/objects` |
| 522 | directory is used. |
| 523 | |
| 524 | `GIT_ALTERNATE_OBJECT_DIRECTORIES`:: |
| 525 | Due to the immutable nature of Git objects, old objects can be |
| 526 | archived into shared, read-only directories. This variable |
| 527 | specifies a ":" separated (on Windows ";" separated) list |
| 528 | of Git object directories which can be used to search for Git |
| 529 | objects. New objects will not be written to these directories. |
| 530 | + |
| 531 | Entries that begin with `"` (double-quote) will be interpreted |
| 532 | as C-style quoted paths, removing leading and trailing |
| 533 | double-quotes and respecting backslash escapes. E.g., the value |
| 534 | `"path-with-\"-and-:-in-it":vanilla-path` has two paths: |
| 535 | `path-with-"-and-:-in-it` and `vanilla-path`. |
| 536 | |
| 537 | `GIT_DIR`:: |
| 538 | If the `GIT_DIR` environment variable is set then it |
| 539 | specifies a path to use instead of the default `.git` |
| 540 | for the base of the repository. |
| 541 | The `--git-dir` command-line option also sets this value. |
| 542 | |
| 543 | `GIT_WORK_TREE`:: |
| 544 | Set the path to the root of the working tree. |
| 545 | This can also be controlled by the `--work-tree` command-line |
| 546 | option and the core.worktree configuration variable. |
| 547 | |
| 548 | `GIT_NAMESPACE`:: |
| 549 | Set the Git namespace; see linkgit:gitnamespaces[7] for details. |
| 550 | The `--namespace` command-line option also sets this value. |
| 551 | |
| 552 | `GIT_CEILING_DIRECTORIES`:: |
| 553 | This should be a colon-separated list of absolute paths. If |
| 554 | set, it is a list of directories that Git should not chdir up |
| 555 | into while looking for a repository directory (useful for |
| 556 | excluding slow-loading network directories). It will not |
| 557 | exclude the current working directory or a GIT_DIR set on the |
| 558 | command line or in the environment. Normally, Git has to read |
| 559 | the entries in this list and resolve any symlink that |
| 560 | might be present in order to compare them with the current |
| 561 | directory. However, if even this access is slow, you |
| 562 | can add an empty entry to the list to tell Git that the |
| 563 | subsequent entries are not symlinks and needn't be resolved; |
| 564 | e.g., |
| 565 | `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`. |
| 566 | |
| 567 | `GIT_DISCOVERY_ACROSS_FILESYSTEM`:: |
| 568 | When run in a directory that does not have ".git" repository |
| 569 | directory, Git tries to find such a directory in the parent |
| 570 | directories to find the top of the working tree, but by default it |
| 571 | does not cross filesystem boundaries. This Boolean environment variable |
| 572 | can be set to true to tell Git not to stop at filesystem |
| 573 | boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect |
| 574 | an explicit repository directory set via `GIT_DIR` or on the |
| 575 | command line. |
| 576 | |
| 577 | `GIT_COMMON_DIR`:: |
| 578 | If this variable is set to a path, non-worktree files that are |
| 579 | normally in $GIT_DIR will be taken from this path |
| 580 | instead. Worktree-specific files such as HEAD or index are |
| 581 | taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and |
| 582 | linkgit:git-worktree[1] for |
| 583 | details. This variable has lower precedence than other path |
| 584 | variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... |
| 585 | |
| 586 | `GIT_DEFAULT_HASH`:: |
| 587 | If this variable is set, the default hash algorithm for new |
| 588 | repositories will be set to this value. This value is |
| 589 | ignored when cloning and the setting of the remote repository |
| 590 | is always used. The default is "sha1". |
| 591 | See `--object-format` in linkgit:git-init[1]. |
| 592 | |
| 593 | `GIT_DEFAULT_REF_FORMAT`:: |
| 594 | If this variable is set, the default reference backend format for new |
| 595 | repositories will be set to this value. The default is "files". |
| 596 | See `--ref-format` in linkgit:git-init[1]. |
| 597 | |
| 598 | `GIT_REFERENCE_BACKEND`:: |
| 599 | Specify which reference backend to be used along with its URI. |
| 600 | See `extensions.refStorage` option in linkgit:git-config[1] for more |
| 601 | details. Overrides the config variable when used. |
| 602 | |
| 603 | Git Commits |
| 604 | ~~~~~~~~~~~ |
| 605 | `GIT_AUTHOR_NAME`:: |
| 606 | The human-readable name used in the author identity when creating commit or |
| 607 | tag objects, or when writing reflogs. Overrides the `user.name` and |
| 608 | `author.name` configuration settings. |
| 609 | |
| 610 | `GIT_AUTHOR_EMAIL`:: |
| 611 | The email address used in the author identity when creating commit or |
| 612 | tag objects, or when writing reflogs. Overrides the `user.email` and |
| 613 | `author.email` configuration settings. |
| 614 | |
| 615 | `GIT_AUTHOR_DATE`:: |
| 616 | The date used for the author identity when creating commit or tag objects, or |
| 617 | when writing reflogs. See linkgit:git-commit[1] for valid formats. |
| 618 | |
| 619 | `GIT_COMMITTER_NAME`:: |
| 620 | The human-readable name used in the committer identity when creating commit or |
| 621 | tag objects, or when writing reflogs. Overrides the `user.name` and |
| 622 | `committer.name` configuration settings. |
| 623 | |
| 624 | `GIT_COMMITTER_EMAIL`:: |
| 625 | The email address used in the author identity when creating commit or |
| 626 | tag objects, or when writing reflogs. Overrides the `user.email` and |
| 627 | `committer.email` configuration settings. |
| 628 | |
| 629 | `GIT_COMMITTER_DATE`:: |
| 630 | The date used for the committer identity when creating commit or tag objects, or |
| 631 | when writing reflogs. See linkgit:git-commit[1] for valid formats. |
| 632 | |
| 633 | `EMAIL`:: |
| 634 | The email address used in the author and committer identities if no other |
| 635 | relevant environment variable or configuration setting has been set. |
| 636 | |
| 637 | Git Diffs |
| 638 | ~~~~~~~~~ |
| 639 | `GIT_DIFF_OPTS`:: |
| 640 | Only valid setting is "--unified=??" or "-u??" to set the |
| 641 | number of context lines shown when a unified diff is created. |
| 642 | This takes precedence over any "-U" or "--unified" option |
| 643 | value passed on the Git diff command line. |
| 644 | |
| 645 | `GIT_EXTERNAL_DIFF`:: |
| 646 | When the environment variable `GIT_EXTERNAL_DIFF` is set, the |
| 647 | program named by it is called to generate diffs, and Git |
| 648 | does not use its builtin diff machinery. |
| 649 | For a path that is added, removed, or modified, |
| 650 | `GIT_EXTERNAL_DIFF` is called with 7 parameters: |
| 651 | |
| 652 | path old-file old-hex old-mode new-file new-hex new-mode |
| 653 | + |
| 654 | where: |
| 655 | |
| 656 | <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the |
| 657 | contents of <old|new>, |
| 658 | <old|new>-hex:: are the 40-hexdigit SHA-1 hashes, |
| 659 | <old|new>-mode:: are the octal representation of the file modes. |
| 660 | + |
| 661 | The file parameters can point at the user's working file |
| 662 | (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` |
| 663 | when a new file is added), or a temporary file (e.g. `old-file` in the |
| 664 | index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the |
| 665 | temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits. |
| 666 | + |
| 667 | For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1 |
| 668 | parameter, <path>. |
| 669 | + |
| 670 | For each path `GIT_EXTERNAL_DIFF` is called, two environment variables, |
| 671 | `GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set. |
| 672 | |
| 673 | `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE`:: |
| 674 | If this Boolean environment variable is set to true then the |
| 675 | `GIT_EXTERNAL_DIFF` command is expected to return exit code |
| 676 | 0 if it considers the input files to be equal or 1 if it |
| 677 | considers them to be different, like `diff(1)`. |
| 678 | If it is set to false, which is the default, then the command |
| 679 | is expected to return exit code 0 regardless of equality. |
| 680 | Any other exit code causes Git to report a fatal error. |
| 681 | |
| 682 | |
| 683 | `GIT_DIFF_PATH_COUNTER`:: |
| 684 | A 1-based counter incremented by one for every path. |
| 685 | |
| 686 | `GIT_DIFF_PATH_TOTAL`:: |
| 687 | The total number of paths. |
| 688 | |
| 689 | other |
| 690 | ~~~~~ |
| 691 | `GIT_MERGE_VERBOSITY`:: |
| 692 | A number controlling the amount of output shown by |
| 693 | the recursive merge strategy. Overrides merge.verbosity. |
| 694 | See linkgit:git-merge[1] |
| 695 | |
| 696 | `GIT_PAGER`:: |
| 697 | This environment variable overrides `$PAGER`. If it is set |
| 698 | to an empty string or to the value "cat", Git will not launch |
| 699 | a pager. See also the `core.pager` option in |
| 700 | linkgit:git-config[1]. |
| 701 | |
| 702 | `GIT_PROGRESS_DELAY`:: |
| 703 | A number controlling how many seconds to delay before showing |
| 704 | optional progress indicators. Defaults to 1. |
| 705 | |
| 706 | `GIT_EDITOR`:: |
| 707 | This environment variable overrides `$EDITOR` and `$VISUAL`. |
| 708 | It is used by several Git commands when, on interactive mode, |
| 709 | an editor is to be launched. See also linkgit:git-var[1] |
| 710 | and the `core.editor` option in linkgit:git-config[1]. |
| 711 | |
| 712 | `GIT_SEQUENCE_EDITOR`:: |
| 713 | This environment variable overrides the configured Git editor |
| 714 | when editing the todo list of an interactive rebase. See also |
| 715 | linkgit:git-rebase[1] and the `sequence.editor` option in |
| 716 | linkgit:git-config[1]. |
| 717 | |
| 718 | `GIT_SSH`:: |
| 719 | `GIT_SSH_COMMAND`:: |
| 720 | If either of these environment variables is set then 'git fetch' |
| 721 | and 'git push' will use the specified command instead of 'ssh' |
| 722 | when they need to connect to a remote system. |
| 723 | The command-line parameters passed to the configured command are |
| 724 | determined by the ssh variant. See `ssh.variant` option in |
| 725 | linkgit:git-config[1] for details. |
| 726 | + |
| 727 | `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted |
| 728 | by the shell, which allows additional arguments to be included. |
| 729 | `$GIT_SSH` on the other hand must be just the path to a program |
| 730 | (which can be a wrapper shell script, if additional arguments are |
| 731 | needed). |
| 732 | + |
| 733 | Usually it is easier to configure any desired options through your |
| 734 | personal `.ssh/config` file. Please consult your ssh documentation |
| 735 | for further details. |
| 736 | |
| 737 | `GIT_SSH_VARIANT`:: |
| 738 | If this environment variable is set, it overrides Git's autodetection |
| 739 | whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH, |
| 740 | plink or tortoiseplink. This variable overrides the config setting |
| 741 | `ssh.variant` that serves the same purpose. |
| 742 | |
| 743 | `GIT_SSL_NO_VERIFY`:: |
| 744 | Setting and exporting this environment variable to any value |
| 745 | tells Git not to verify the SSL certificate when fetching or |
| 746 | pushing over HTTPS. |
| 747 | |
| 748 | `GIT_ATTR_SOURCE`:: |
| 749 | Sets the treeish that gitattributes will be read from. |
| 750 | |
| 751 | `GIT_ASKPASS`:: |
| 752 | If this environment variable is set, then Git commands which need to |
| 753 | acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) |
| 754 | will call this program with a suitable prompt as command-line argument |
| 755 | and read the password from its STDOUT. See also the `core.askPass` |
| 756 | option in linkgit:git-config[1]. |
| 757 | |
| 758 | `GIT_TERMINAL_PROMPT`:: |
| 759 | If this Boolean environment variable is set to false, git will not prompt |
| 760 | on the terminal (e.g., when asking for HTTP authentication). |
| 761 | |
| 762 | `GIT_CONFIG_GLOBAL`:: |
| 763 | `GIT_CONFIG_SYSTEM`:: |
| 764 | Take the configuration from the given files instead from global or |
| 765 | system-level configuration files. If `GIT_CONFIG_SYSTEM` is set, the |
| 766 | system config file defined at build time (usually `/etc/gitconfig`) |
| 767 | will not be read. Likewise, if `GIT_CONFIG_GLOBAL` is set, neither |
| 768 | `$HOME/.gitconfig` nor `$XDG_CONFIG_HOME/git/config` will be read. Can |
| 769 | be set to `/dev/null` to skip reading configuration files of the |
| 770 | respective level. |
| 771 | |
| 772 | `GIT_CONFIG_NOSYSTEM`:: |
| 773 | Whether to skip reading settings from the system-wide |
| 774 | `$(prefix)/etc/gitconfig` file. This Boolean environment variable can |
| 775 | be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a |
| 776 | predictable environment for a picky script, or you can set it |
| 777 | to true to temporarily avoid using a buggy `/etc/gitconfig` file while |
| 778 | waiting for someone with sufficient permissions to fix it. |
| 779 | |
| 780 | `GIT_FLUSH`:: |
| 781 | If this Boolean environment variable is set to true, then commands such |
| 782 | as 'git blame' (in incremental mode), 'git rev-list', 'git log', |
| 783 | 'git check-attr' and 'git check-ignore' will |
| 784 | force a flush of the output stream after each record have been |
| 785 | flushed. If this |
| 786 | variable is set to false, the output of these commands will be done |
| 787 | using completely buffered I/O. If this environment variable is |
| 788 | not set, Git will choose buffered or record-oriented flushing |
| 789 | based on whether stdout appears to be redirected to a file or not. |
| 790 | |
| 791 | `GIT_TRACE`:: |
| 792 | Enables general trace messages, e.g. alias expansion, built-in |
| 793 | command execution and external command execution. |
| 794 | + |
| 795 | If this variable is set to "1", "2" or "true" (comparison |
| 796 | is case insensitive), trace messages will be printed to |
| 797 | stderr. |
| 798 | + |
| 799 | If the variable is set to an integer value greater than 2 |
| 800 | and lower than 10 (strictly) then Git will interpret this |
| 801 | value as an open file descriptor and will try to write the |
| 802 | trace messages into this file descriptor. |
| 803 | + |
| 804 | Alternatively, if the variable is set to an absolute path |
| 805 | (starting with a '/' character), Git will interpret this |
| 806 | as a file path and will try to append the trace messages |
| 807 | to it. |
| 808 | + |
| 809 | Unsetting the variable, or setting it to empty, "0" or |
| 810 | "false" (case insensitive) disables trace messages. |
| 811 | |
| 812 | `GIT_TRACE_FSMONITOR`:: |
| 813 | Enables trace messages for the filesystem monitor extension. |
| 814 | See `GIT_TRACE` for available trace output options. |
| 815 | |
| 816 | `GIT_TRACE_PACK_ACCESS`:: |
| 817 | Enables trace messages for all accesses to any packs. For each |
| 818 | access, the pack file name and an offset in the pack is |
| 819 | recorded. This may be helpful for troubleshooting some |
| 820 | pack-related performance problems. |
| 821 | See `GIT_TRACE` for available trace output options. |
| 822 | |
| 823 | `GIT_TRACE_PACKET`:: |
| 824 | Enables trace messages for all packets coming in or out of a |
| 825 | given program. This can help with debugging object negotiation |
| 826 | or other protocol issues. Tracing is turned off at a packet |
| 827 | starting with "PACK" (but see `GIT_TRACE_PACKFILE` below). |
| 828 | See `GIT_TRACE` for available trace output options. |
| 829 | |
| 830 | `GIT_TRACE_PACKFILE`:: |
| 831 | Enables tracing of packfiles sent or received by a |
| 832 | given program. Unlike other trace output, this trace is |
| 833 | verbatim: no headers, and no quoting of binary data. You almost |
| 834 | certainly want to direct into a file (e.g., |
| 835 | `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on |
| 836 | the terminal or mixing it with other trace output. |
| 837 | + |
| 838 | Note that this is currently only implemented for the client side |
| 839 | of clones and fetches. |
| 840 | |
| 841 | `GIT_TRACE_PERFORMANCE`:: |
| 842 | Enables performance related trace messages, e.g. total execution |
| 843 | time of each Git command. |
| 844 | See `GIT_TRACE` for available trace output options. |
| 845 | |
| 846 | `GIT_TRACE_REFS`:: |
| 847 | Enables trace messages for operations on the ref database. |
| 848 | See `GIT_TRACE` for available trace output options. |
| 849 | |
| 850 | `GIT_TRACE_SETUP`:: |
| 851 | Enables trace messages printing the .git, working tree and current |
| 852 | working directory after Git has completed its setup phase. |
| 853 | See `GIT_TRACE` for available trace output options. |
| 854 | |
| 855 | `GIT_TRACE_SHALLOW`:: |
| 856 | Enables trace messages that can help debugging fetching / |
| 857 | cloning of shallow repositories. |
| 858 | See `GIT_TRACE` for available trace output options. |
| 859 | |
| 860 | `GIT_TRACE_CURL`:: |
| 861 | Enables a curl full trace dump of all incoming and outgoing data, |
| 862 | including descriptive information, of the git transport protocol. |
| 863 | This is similar to doing curl `--trace-ascii` on the command line. |
| 864 | See `GIT_TRACE` for available trace output options. |
| 865 | |
| 866 | `GIT_TRACE_CURL_NO_DATA`:: |
| 867 | When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump |
| 868 | data (that is, only dump info lines and headers). |
| 869 | |
| 870 | `GIT_TRACE2`:: |
| 871 | Enables more detailed trace messages from the "trace2" library. |
| 872 | Output from `GIT_TRACE2` is a simple text-based format for human |
| 873 | readability. |
| 874 | + |
| 875 | If this variable is set to "1", "2" or "true" (comparison |
| 876 | is case insensitive), trace messages will be printed to |
| 877 | stderr. |
| 878 | + |
| 879 | If the variable is set to an integer value greater than 2 |
| 880 | and lower than 10 (strictly) then Git will interpret this |
| 881 | value as an open file descriptor and will try to write the |
| 882 | trace messages into this file descriptor. |
| 883 | + |
| 884 | Alternatively, if the variable is set to an absolute path |
| 885 | (starting with a '/' character), Git will interpret this |
| 886 | as a file path and will try to append the trace messages |
| 887 | to it. If the path already exists and is a directory, the |
| 888 | trace messages will be written to files (one per process) |
| 889 | in that directory, named according to the last component |
| 890 | of the SID and an optional counter (to avoid filename |
| 891 | collisions). |
| 892 | + |
| 893 | In addition, if the variable is set to |
| 894 | `af_unix:[<socket-type>:]<absolute-pathname>`, Git will try |
| 895 | to open the path as a Unix Domain Socket. The socket type |
| 896 | can be either `stream` or `dgram`. |
| 897 | + |
| 898 | Unsetting the variable, or setting it to empty, "0" or |
| 899 | "false" (case insensitive) disables trace messages. |
| 900 | + |
| 901 | See link:technical/api-trace2.html[Trace2 documentation] |
| 902 | for full details. |
| 903 | |
| 904 | |
| 905 | `GIT_TRACE2_EVENT`:: |
| 906 | This setting writes a JSON-based format that is suited for machine |
| 907 | interpretation. |
| 908 | See `GIT_TRACE2` for available trace output options and |
| 909 | link:technical/api-trace2.html[Trace2 documentation] for full details. |
| 910 | |
| 911 | `GIT_TRACE2_PERF`:: |
| 912 | In addition to the text-based messages available in `GIT_TRACE2`, this |
| 913 | setting writes a column-based format for understanding nesting |
| 914 | regions. |
| 915 | See `GIT_TRACE2` for available trace output options and |
| 916 | link:technical/api-trace2.html[Trace2 documentation] for full details. |
| 917 | |
| 918 | `GIT_TRACE_REDACT`:: |
| 919 | By default, when tracing is activated, Git redacts the values of |
| 920 | cookies, the "Authorization:" header, the "Proxy-Authorization:" |
| 921 | header and packfile URIs. Set this Boolean environment variable to false to prevent this |
| 922 | redaction. |
| 923 | |
| 924 | `GIT_NO_REPLACE_OBJECTS`:: |
| 925 | Setting and exporting this environment variable tells Git to |
| 926 | ignore replacement refs and do not replace Git objects. |
| 927 | |
| 928 | `GIT_LITERAL_PATHSPECS`:: |
| 929 | Setting this Boolean environment variable to true will cause Git to treat all |
| 930 | pathspecs literally, rather than as glob patterns. For example, |
| 931 | running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search |
| 932 | for commits that touch the path `*.c`, not any paths that the |
| 933 | glob `*.c` matches. You might want this if you are feeding |
| 934 | literal paths to Git (e.g., paths previously given to you by |
| 935 | `git ls-tree`, `--raw` diff output, etc). |
| 936 | |
| 937 | `GIT_GLOB_PATHSPECS`:: |
| 938 | Setting this Boolean environment variable to true will cause Git to treat all |
| 939 | pathspecs as glob patterns (aka "glob" magic). |
| 940 | |
| 941 | `GIT_NOGLOB_PATHSPECS`:: |
| 942 | Setting this Boolean environment variable to true will cause Git to treat all |
| 943 | pathspecs as literal (aka "literal" magic). |
| 944 | |
| 945 | `GIT_ICASE_PATHSPECS`:: |
| 946 | Setting this Boolean environment variable to true will cause Git to treat all |
| 947 | pathspecs as case-insensitive. |
| 948 | |
| 949 | `GIT_NO_LAZY_FETCH`:: |
| 950 | Setting this Boolean environment variable to true tells Git |
| 951 | not to lazily fetch missing objects from the promisor remote |
| 952 | on demand. |
| 953 | |
| 954 | `GIT_REFLOG_ACTION`:: |
| 955 | When a ref is updated, reflog entries are created to keep |
| 956 | track of the reason why the ref was updated (which is |
| 957 | typically the name of the high-level command that updated |
| 958 | the ref), in addition to the old and new values of the ref. |
| 959 | A scripted Porcelain command can use set_reflog_action |
| 960 | helper function in `git-sh-setup` to set its name to this |
| 961 | variable when it is invoked as the top level command by the |
| 962 | end user, to be recorded in the body of the reflog. |
| 963 | |
| 964 | `GIT_REF_PARANOIA`:: |
| 965 | If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating |
| 966 | over lists of refs. Normally Git will try to include any such |
| 967 | refs, which may cause some operations to fail. This is usually |
| 968 | preferable, as potentially destructive operations (e.g., |
| 969 | linkgit:git-prune[1]) are better off aborting rather than |
| 970 | ignoring broken refs (and thus considering the history they |
| 971 | point to as not worth saving). The default value is `1` (i.e., |
| 972 | be paranoid about detecting and aborting all operations). You |
| 973 | should not normally need to set this to `0`, but it may be |
| 974 | useful when trying to salvage data from a corrupted repository. |
| 975 | |
| 976 | `GIT_COMMIT_GRAPH_PARANOIA`:: |
| 977 | When loading a commit object from the commit-graph, Git performs an |
| 978 | existence check on the object in the object database. This is done to |
| 979 | avoid issues with stale commit-graphs that contain references to |
| 980 | already-deleted commits, but comes with a performance penalty. |
| 981 | + |
| 982 | The default is "false", which disables the aforementioned behavior. |
| 983 | Setting this to "true" enables the existence check so that stale commits |
| 984 | will never be returned from the commit-graph at the cost of performance. |
| 985 | |
| 986 | `GIT_ALLOW_PROTOCOL`:: |
| 987 | If set to a colon-separated list of protocols, behave as if |
| 988 | `protocol.allow` is set to `never`, and each of the listed |
| 989 | protocols has `protocol.<name>.allow` set to `always` |
| 990 | (overriding any existing configuration). See the description of |
| 991 | `protocol.allow` in linkgit:git-config[1] for more details. |
| 992 | |
| 993 | `GIT_PROTOCOL_FROM_USER`:: |
| 994 | Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are |
| 995 | configured to the `user` state. This is useful to restrict recursive |
| 996 | submodule initialization from an untrusted repository or for programs |
| 997 | which feed potentially-untrusted URLS to git commands. See |
| 998 | linkgit:git-config[1] for more details. |
| 999 | |
| 1000 | `GIT_PROTOCOL`:: |
| 1001 | For internal use only. Used in handshaking the wire protocol. |
| 1002 | Contains a colon ':' separated list of keys with optional values |
| 1003 | '<key>[=<value>]'. Presence of unknown keys and values must be |
| 1004 | ignored. |
| 1005 | + |
| 1006 | Note that servers may need to be configured to allow this variable to |
| 1007 | pass over some transports. It will be propagated automatically when |
| 1008 | accessing local repositories (i.e., `file://` or a filesystem path), as |
| 1009 | well as over the `git://` protocol. For git-over-http, it should work |
| 1010 | automatically in most configurations, but see the discussion in |
| 1011 | linkgit:git-http-backend[1]. For git-over-ssh, the ssh server may need |
| 1012 | to be configured to allow clients to pass this variable (e.g., by using |
| 1013 | `AcceptEnv GIT_PROTOCOL` with OpenSSH). |
| 1014 | + |
| 1015 | This configuration is optional. If the variable is not propagated, then |
| 1016 | clients will fall back to the original "v0" protocol (but may miss out |
| 1017 | on some performance improvements or features). This variable currently |
| 1018 | only affects clones and fetches; it is not yet used for pushes (but may |
| 1019 | be in the future). |
| 1020 | |
| 1021 | `GIT_OPTIONAL_LOCKS`:: |
| 1022 | If this Boolean environment variable is set to false, Git will complete any requested operation without |
| 1023 | performing any optional sub-operations that require taking a lock. |
| 1024 | For example, this will prevent `git status` from refreshing the |
| 1025 | index as a side effect. This is useful for processes running in |
| 1026 | the background which do not want to cause lock contention with |
| 1027 | other operations on the repository. Defaults to `1`. |
| 1028 | |
| 1029 | `GIT_REDIRECT_STDIN`:: |
| 1030 | `GIT_REDIRECT_STDOUT`:: |
| 1031 | `GIT_REDIRECT_STDERR`:: |
| 1032 | Windows-only: allow redirecting the standard input/output/error |
| 1033 | handles to paths specified by the environment variables. This is |
| 1034 | particularly useful in multi-threaded applications where the |
| 1035 | canonical way to pass standard handles via `CreateProcess()` is |
| 1036 | not an option because it would require the handles to be marked |
| 1037 | inheritable (and consequently *every* spawned process would |
| 1038 | inherit them, possibly blocking regular Git operations). The |
| 1039 | primary intended use case is to use named pipes for communication |
| 1040 | (e.g. `\\.\pipe\my-git-stdin-123`). |
| 1041 | + |
| 1042 | Two special values are supported: `off` will simply close the |
| 1043 | corresponding standard handle, and if `GIT_REDIRECT_STDERR` is |
| 1044 | `2>&1`, standard error will be redirected to the same handle as |
| 1045 | standard output. |
| 1046 | |
| 1047 | `GIT_PRINT_SHA1_ELLIPSIS` (deprecated):: |
| 1048 | If set to `yes`, print an ellipsis following an |
| 1049 | (abbreviated) SHA-1 value. This affects indications of |
| 1050 | detached HEADs (linkgit:git-checkout[1]) and the raw |
| 1051 | diff output (linkgit:git-diff[1]). Printing an |
| 1052 | ellipsis in the cases mentioned is no longer considered |
| 1053 | adequate and support for it is likely to be removed in the |
| 1054 | foreseeable future (along with the variable). |
| 1055 | |
| 1056 | `GIT_ADVICE`:: |
| 1057 | If set to `0`, then disable all advice messages. These messages are |
| 1058 | intended to provide hints to human users that may help them get out of |
| 1059 | problematic situations or take advantage of new features. Users can |
| 1060 | disable individual messages using the `advice.*` config keys. These |
| 1061 | messages may be disruptive to tools that execute Git processes, so this |
| 1062 | variable is available to disable the messages. (The `--no-advice` |
| 1063 | global option is also available, but old Git versions may fail when |
| 1064 | this option is not understood. The environment variable will be ignored |
| 1065 | by Git versions that do not understand it.) |
| 1066 | |
| 1067 | Discussion[[Discussion]] |
| 1068 | ------------------------ |
| 1069 | |
| 1070 | More detail on the following is available from the |
| 1071 | link:user-manual.html#git-concepts[Git concepts chapter of the |
| 1072 | user-manual] and linkgit:gitcore-tutorial[7]. |
| 1073 | |
| 1074 | A Git project normally consists of a working directory with a ".git" |
| 1075 | subdirectory at the top level. The .git directory contains, among other |
| 1076 | things, a compressed object database representing the complete history |
| 1077 | of the project, an "index" file which links that history to the current |
| 1078 | contents of the working tree, and named pointers into that history such |
| 1079 | as tags and branch heads. |
| 1080 | |
| 1081 | The object database contains objects of three main types: blobs, which |
| 1082 | hold file data; trees, which point to blobs and other trees to build up |
| 1083 | directory hierarchies; and commits, which each reference a single tree |
| 1084 | and some number of parent commits. |
| 1085 | |
| 1086 | The commit, equivalent to what other systems call a "changeset" or |
| 1087 | "version", represents a step in the project's history, and each parent |
| 1088 | represents an immediately preceding step. Commits with more than one |
| 1089 | parent represent merges of independent lines of development. |
| 1090 | |
| 1091 | All objects are named by the SHA-1 hash of their contents, normally |
| 1092 | written as a string of 40 hex digits. Such names are globally unique. |
| 1093 | The entire history leading up to a commit can be vouched for by signing |
| 1094 | just that commit. A fourth object type, the tag, is provided for this |
| 1095 | purpose. |
| 1096 | |
| 1097 | When first created, objects are stored in individual files, but for |
| 1098 | efficiency may later be compressed together into "pack files". |
| 1099 | |
| 1100 | Named pointers called refs mark interesting points in history. A ref |
| 1101 | may contain the SHA-1 name of an object or the name of another ref (the |
| 1102 | latter is called a "symbolic ref"). |
| 1103 | Refs with names beginning `refs/head/` contain the SHA-1 name of the most |
| 1104 | recent commit (or "head") of a branch under development. SHA-1 names of |
| 1105 | tags of interest are stored under `refs/tags/`. A symbolic ref named |
| 1106 | `HEAD` contains the name of the currently checked-out branch. |
| 1107 | |
| 1108 | The index file is initialized with a list of all paths and, for each |
| 1109 | path, a blob object and a set of attributes. The blob object represents |
| 1110 | the contents of the file as of the head of the current branch. The |
| 1111 | attributes (last modified time, size, etc.) are taken from the |
| 1112 | corresponding file in the working tree. Subsequent changes to the |
| 1113 | working tree can be found by comparing these attributes. The index may |
| 1114 | be updated with new content, and new commits may be created from the |
| 1115 | content stored in the index. |
| 1116 | |
| 1117 | The index is also capable of storing multiple entries (called "stages") |
| 1118 | for a given pathname. These stages are used to hold the various |
| 1119 | unmerged version of a file when a merge is in progress. |
| 1120 | |
| 1121 | SECURITY |
| 1122 | -------- |
| 1123 | |
| 1124 | Some configuration options and hook files may cause Git to run arbitrary |
| 1125 | shell commands. Because configuration and hooks are not copied using |
| 1126 | `git clone`, it is generally safe to clone remote repositories with |
| 1127 | untrusted content, inspect them with `git log`, and so on. |
| 1128 | |
| 1129 | However, it is not safe to run Git commands in a `.git` directory (or |
| 1130 | the working tree that surrounds it) when that `.git` directory itself |
| 1131 | comes from an untrusted source. The commands in its config and hooks |
| 1132 | are executed in the usual way. |
| 1133 | |
| 1134 | By default, Git will refuse to run when the repository is owned by |
| 1135 | someone other than the user running the command. See the entry for |
| 1136 | `safe.directory` in linkgit:git-config[1]. While this can help protect |
| 1137 | you in a multi-user environment, note that you can also acquire |
| 1138 | untrusted repositories that are owned by you (for example, if you |
| 1139 | extract a zip file or tarball from an untrusted source). In such cases, |
| 1140 | you'd need to "sanitize" the untrusted repository first. |
| 1141 | |
| 1142 | If you have an untrusted `.git` directory, you should first clone it |
| 1143 | with `git clone --no-local` to obtain a clean copy. Git does restrict |
| 1144 | the set of options and hooks that will be run by `upload-pack`, which |
| 1145 | handles the server side of a clone or fetch, but beware that the |
| 1146 | surface area for attack against `upload-pack` is large, so this does |
| 1147 | carry some risk. The safest thing is to serve the repository as an |
| 1148 | unprivileged user (either via linkgit:git-daemon[1], ssh, or using |
| 1149 | other tools to change user ids). See the discussion in the `SECURITY` |
| 1150 | section of linkgit:git-upload-pack[1]. |
| 1151 | |
| 1152 | FURTHER DOCUMENTATION |
| 1153 | --------------------- |
| 1154 | |
| 1155 | See the references in the "description" section to get started |
| 1156 | using Git. The following is probably more detail than necessary |
| 1157 | for a first-time user. |
| 1158 | |
| 1159 | The link:user-manual.html#git-concepts[Git concepts chapter of the |
| 1160 | user-manual] and linkgit:gitcore-tutorial[7] both provide |
| 1161 | introductions to the underlying Git architecture. |
| 1162 | |
| 1163 | See linkgit:gitworkflows[7] for an overview of recommended workflows. |
| 1164 | |
| 1165 | See also the link:howto-index.html[howto] documents for some useful |
| 1166 | examples. |
| 1167 | |
| 1168 | The internals are documented in the |
| 1169 | link:technical/api-index.html[Git API documentation]. |
| 1170 | |
| 1171 | Users migrating from CVS may also want to |
| 1172 | read linkgit:gitcvs-migration[7]. |
| 1173 | |
| 1174 | |
| 1175 | Authors |
| 1176 | ------- |
| 1177 | Git was started by Linus Torvalds, and is currently maintained by Junio |
| 1178 | C Hamano. Numerous contributions have come from the Git mailing list |
| 1179 | <git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary |
| 1180 | gives you a more complete list of contributors. |
| 1181 | |
| 1182 | If you have a clone of git.git itself, the |
| 1183 | output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you |
| 1184 | the authors for specific parts of the project. |
| 1185 | |
| 1186 | Reporting Bugs |
| 1187 | -------------- |
| 1188 | |
| 1189 | Report bugs to the Git mailing list <git@vger.kernel.org> where the |
| 1190 | development and maintenance is primarily done. You do not have to be |
| 1191 | subscribed to the list to send a message there. See the list archive |
| 1192 | at https://lore.kernel.org/git for previous bug reports and other |
| 1193 | discussions. |
| 1194 | |
| 1195 | Issues which are security relevant should be disclosed privately to |
| 1196 | the Git Security mailing list <git-security@googlegroups.com>. |
| 1197 | |
| 1198 | SEE ALSO |
| 1199 | -------- |
| 1200 | linkgit:gittutorial[7], linkgit:gittutorial-2[7], |
| 1201 | linkgit:giteveryday[7], linkgit:gitcvs-migration[7], |
| 1202 | linkgit:gitglossary[7], linkgit:gitcore-tutorial[7], |
| 1203 | linkgit:gitcli[7], link:user-manual.html[The Git User's Manual], |
| 1204 | linkgit:gitworkflows[7] |
| 1205 | |
| 1206 | GIT |
| 1207 | --- |
| 1208 | Part of the linkgit:git[1] suite |