diff options
Diffstat (limited to 'Documentation')
44 files changed, 429 insertions, 278 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8579530710..32210a4386 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -580,11 +580,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `http://git.example.com` + `.git/config` `GIT_DIR` `HEAD` diff --git a/Documentation/Makefile b/Documentation/Makefile index 4e4dd7ecf1..6d738f831e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -12,7 +12,6 @@ MAN1_TXT += $(filter-out \ $(wildcard git-*.txt)) MAN1_TXT += git.txt MAN1_TXT += gitk.txt -MAN1_TXT += gitremote-helpers.txt MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt @@ -30,6 +29,7 @@ MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt MAN7_TXT += gitsubmodules.txt MAN7_TXT += gittutorial-2.txt diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.txt index 94100fa403..85e1122966 100644 --- a/Documentation/RelNotes/2.22.0.txt +++ b/Documentation/RelNotes/2.22.0.txt @@ -46,6 +46,27 @@ UI, Workflows & Features configuration (when available), which allows --list-cmds to honour a repository specific setting of completion.commands, for example. + * "git mergetool" learned to offer Sublime Merge (smerge) as one of + its backends. + + * A new hook "post-index-change" is called when the on-disk index + file changes, which can help e.g. a virtualized working tree + implementation. + + * "git difftool" can now run outside a repository. + + * "git checkout -m <other>" was about carrying the differences + between HEAD and the working-tree files forward while checking out + another branch, and ignored the differences between HEAD and the + index. The command has been taught to abort when the index and the + HEAD are different. + + * A progress indicator has been added to the "index-pack" step, which + often makes users wait for completion during "git clone". + + * "git submodule" learns "set-branch" subcommand that allows the + submodule.*.branch settings to be modified. + Performance, Internal Implementation, Development Support etc. @@ -80,6 +101,35 @@ Performance, Internal Implementation, Development Support etc. * "git multi-pack-index verify" did not scale well with the number of packfiles, which is being improved. + * "git stash" has been rewritten in C. + + * The "check-docs" Makefile target to support developers has been + updated. + + * The tests have been updated not to rely on the abbreviated option + names the parse-options API offers, to protect us from an + abbreviated form of an option that used to be unique within the + command getting non-unique when a new option that share the same + prefix is added. + + * The scripted version of "git rebase -i" wrote and rewrote the todo + list many times during a single step of its operation, and the + recent C-rewrite made a faithful conversion of the logic to C. The + implementation has been updated to carry necessary information + around in-core to avoid rewriting the same file over and over + unnecessarily. + + * Test framework update to more robustly clean up leftover files and + processes after tests are done. + + * Conversion from unsigned char[20] to struct object_id continues. + + * While running "git diff" in a lazy clone, we can upfront know which + missing blobs we will need, instead of waiting for the on-demand + machinery to discover them one by one. The code learned to aim to + achieve better performance by batching the request for these + promised blobs. + Fixes since v2.21 ----------------- @@ -203,8 +253,8 @@ Fixes since v2.21 * A corner-case object name ambiguity while the sequencer machinery is working (e.g. "rebase -i -x") has been fixed. - * "git format-patch" used overwrite an existing patch/cover-letter - file. A new "--no-clobber" option stops it. + * "git format-patch" did not diagnose an error while opening the + output file for the cover-letter, which has been corrected. (merge 2fe95f494c jc/format-patch-error-check later to maint). * "git checkout -f <branch>" while the index has an unmerged path @@ -220,6 +270,87 @@ Fixes since v2.21 * dumb-http walker has been updated to share more error recovery strategy with the normal codepath. + * A buglet in configuration parser has been fixed. + (merge 19e7fdaa58 nd/include-if-wildmatch later to maint). + + * The documentation for "git read-tree --reset -u" has been updated. + (merge b5a0bd694c nd/read-tree-reset-doc later to maint). + + * Code clean-up around a much-less-important-than-it-used-to-be + update_server_info() funtion. + (merge b3223761c8 jk/server-info-rabbit-hole later to maint). + + * The message given when "git commit -a <paths>" errors out has been + updated. + (merge 5a1dbd48bc nd/commit-a-with-paths-msg-update later to maint). + + * "git cherry-pick --options A..B", after giving control back to the + user to ask help resolving a conflicted step, did not honor the + options it originally received, which has been corrected. + + * Various glitches in "git gc" around reflog handling have been fixed. + + * The code to read from commit-graph file has been cleanup with more + careful error checking before using data read from it. + + * Performance fix around "git fetch" that grabs many refs. + (merge b764300912 jt/fetch-pack-wanted-refs-optim later to maint). + + * Protocol v2 support in "git fetch-pack" of shallow clones has been + corrected. + + * Performance fix around "git blame", especially in a linear history + (which is the norm we should optimize for). + (merge f892014943 dk/blame-keep-origin-blob later to maint). + + * Performance fix for "rev-list --parents -- pathspec". + (merge 8320b1dbe7 jk/revision-rewritten-parents-in-prio-queue later to maint). + + * Updating the display with progress message has been cleaned up to + deal better with overlong messages. + (merge 545dc345eb sg/overlong-progress-fix later to maint). + + * "git blame -- path" in a non-bare repository starts blaming from + the working tree, and the same command in a bare repository errors + out because there is no working tree by definition. The command + has been taught to instead start blaming from the commit at HEAD, + which is more useful. + (merge a544fb08f8 sg/blame-in-bare-start-at-head later to maint). + + * An underallocation in the code to read the untracked cache + extension has been corrected. + (merge 3a7b45a623 js/untracked-cache-allocfix later to maint). + + * The code is updated to check the result of memory allocation before + it is used in more places, by using xmalloc and/or xcalloc calls. + (merge 999b951b28 jk/xmalloc later to maint). + + * The GETTEXT_POISON test option has been quite broken ever since it + was made runtime-tunable, which has been fixed. + (merge f88b9cb603 jc/gettext-test-fix later to maint). + + * Test fix on APFS that is incapable of store paths in Latin-1. + (merge 3889149619 js/iso8895-test-on-apfs later to maint). + + * "git submodule foreach <command> --quiet" did not pass the option + down correctly, which has been corrected. + (merge a282f5a906 nd/submodule-foreach-quiet later to maint). + + * "git send-email" has been taught to use quoted-printable when the + payload contains carriage-return. The use of the mechanism is in + line with the design originally added the codepath that chooses QP + when the payload has overly long lines. + (merge 74d76a1701 bc/send-email-qp-cr later to maint). + + * The recently added feature to add addresses that are on + anything-by: trailers in 'git send-email' was found to be way too + eager and considered nonsense strings as if they can be legitimate + beginning of *-by: trailer. This has been tightened. + + * Build with gettext breaks on recent macOS w/ Homebrew when + /usr/local/bin is not on PATH, which has been corrected. + (merge 92a1377a2a js/macos-gettext-build later to maint). + * Code cleanup, docfix, build fix, etc. (merge 11f470aee7 jc/test-yes-doc later to maint). (merge 90503a240b js/doc-symref-in-proto-v1 later to maint). @@ -245,3 +376,12 @@ Fixes since v2.21 (merge a7256debd4 nd/checkout-m-doc-update later to maint). (merge 3a9e1ad78d jt/t5551-protocol-v2-does-not-have-half-auth later to maint). (merge 0b918b75af sg/t5318-cleanup later to maint). + (merge 68ed71b53c cb/doco-mono later to maint). + (merge a34dca2451 nd/interpret-trailers-docfix later to maint). + (merge cf7b857a77 en/fast-import-parsing-fix later to maint). + (merge fe61ccbc35 po/rerere-doc-fmt later to maint). + (merge ffea0248bf po/describe-not-necessarily-7 later to maint). + (merge 7cb7283adb tg/ls-files-debug-format-fix later to maint). + (merge f64a21bd82 tz/doc-apostrophe-no-longer-needed later to maint). + (merge dbe7b41019 js/t3301-unbreak-notes-test later to maint). + (merge d8083e4180 km/t3000-retitle later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ec8b205145..6d589e118c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -372,15 +372,15 @@ such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". Some parts of the system have dedicated maintainers with their own repositories. -- 'git-gui/' comes from git-gui project, maintained by Pat Thoyts: +- `git-gui/` comes from git-gui project, maintained by Pat Thoyts: git://repo.or.cz/git-gui.git -- 'gitk-git/' comes from Paul Mackerras's gitk project: +- `gitk-git/` comes from Paul Mackerras's gitk project: git://ozlabs.org/~paulus/gitk -- 'po/' comes from the localization coordinator, Jiang Xin: +- `po/` comes from the localization coordinator, Jiang Xin: https://github.com/git-l10n/git-po/ diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 88620429ea..ec4f6ae658 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -90,4 +90,6 @@ advice.*:: waitingForEditor:: Print a message to the terminal whenever Git is waiting for editor input from the user. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. -- diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 7e9b6c8f4c..75538d27e7 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -414,7 +414,7 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesFile:: Specifies the pathname to the file that contains patterns to describe paths that are not meant to be tracked, in addition - to '.gitignore' (per-directory) and '.git/info/exclude'. + to `.gitignore` (per-directory) and `.git/info/exclude`. Defaults to `$XDG_CONFIG_HOME/git/ignore`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` is used instead. See linkgit:gitignore[5]. @@ -429,8 +429,8 @@ core.askPass:: command-line argument and write the password on its STDOUT. core.attributesFile:: - In addition to '.gitattributes' (per-directory) and - '.git/info/attributes', Git looks into this file for attributes + In addition to `.gitattributes` (per-directory) and + `.git/info/attributes`, Git looks into this file for attributes (see linkgit:gitattributes[5]). Path expansions are made the same way as for `core.excludesFile`. Its default value is `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not @@ -438,10 +438,10 @@ core.attributesFile:: core.hooksPath:: By default Git will look for your hooks in the - '$GIT_DIR/hooks' directory. Set this to different path, - e.g. '/etc/git/hooks', and Git will try to find your hooks in - that directory, e.g. '/etc/git/hooks/pre-receive' instead of - in '$GIT_DIR/hooks/pre-receive'. + `$GIT_DIR/hooks` directory. Set this to different path, + e.g. `/etc/git/hooks`, and Git will try to find your hooks in + that directory, e.g. `/etc/git/hooks/pre-receive` instead of + in `$GIT_DIR/hooks/pre-receive`. + The path can be either absolute or relative. A relative path is taken as relative to the directory where the hooks are run (see diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 73c08b0c00..02b92b18b5 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -1,25 +1,42 @@ gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 50. + to 50, which is the default for the `--depth` option when + `--aggressive` isn't in use. ++ +See the documentation for the `--depth` option in +linkgit:git-repack[1] for more details. gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 250. + to 250, which is a much more aggressive window size than + the default `--window` of 10. ++ +See the documentation for the `--window` option in +linkgit:git-repack[1] for more details. gc.auto:: When there are approximately more than this many loose objects in the repository, `git gc --auto` will pack them. Some Porcelain commands use this command to perform a light-weight garbage collection from time to time. The - default value is 6700. Setting this to 0 disables it. + default value is 6700. ++ +Setting this to 0 disables not only automatic packing based on the +number of loose objects, but any other heuristic `git gc --auto` will +otherwise use to determine if there's work to do, such as +`gc.autoPackLimit`. gc.autoPackLimit:: When there are more than this many packs that are not marked with `*.keep` file in the repository, `git gc --auto` consolidates them into one larger pack. The default value is 50. Setting this to 0 disables it. + Setting `gc.auto` to 0 will also disable this. ++ +See the `gc.bigPackThreshold` configuration variable below. When in +use, it'll affect how the auto pack limit works. gc.autoDetach:: Make `git gc --auto` return immediately and run in background @@ -36,11 +53,16 @@ Note that if the number of kept packs is more than gc.autoPackLimit, this configuration variable is ignored, all packs except the base pack will be repacked. After this the number of packs should go below gc.autoPackLimit and gc.bigPackThreshold should be respected again. ++ +If the amount of memory estimated for `git repack` to run smoothly is +not available and `gc.bigPackThreshold` is not set, the largest pack +will also be excluded (this is the equivalent of running `git gc` with +`--keep-base-pack`). gc.writeCommitGraph:: If true, then gc will rewrite the commit-graph file when - linkgit:git-gc[1] is run. When using linkgit:git-gc[1] - '--auto' the commit-graph will be updated if housekeeping is + linkgit:git-gc[1] is run. When using `git gc --auto` + the commit-graph will be updated if housekeeping is required. Default is false. See linkgit:git-commit-graph[1] for details. @@ -94,6 +116,12 @@ gc.<pattern>.reflogExpireUnreachable:: With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>. ++ +These types of entries are generally created as a result of using `git +commit --amend` or `git rebase` and are the commits prior to the amend +or rebase occurring. Since these changes are not part of the current +project most users will want to expire them sooner, which is why the +default is more aggressive than `gc.reflogExpire`. gc.rerereResolved:: Records of conflicted merge you resolved earlier are diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index d389c73929..6a313937f8 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -39,9 +39,22 @@ merge.renameLimit:: is turned off. merge.renames:: - Whether and how Git detects renames. If set to "false", - rename detection is disabled. If set to "true", basic rename - detection is enabled. Defaults to the value of diff.renames. + Whether Git detects renames. If set to "false", rename detection + is disabled. If set to "true", basic rename detection is enabled. + Defaults to the value of diff.renames. + +merge.directoryRenames:: + Whether Git detects directory renames, affecting what happens at + merge time to new files added to a directory on one side of + history when that directory was renamed on the other side of + history. If merge.directoryRenames is set to "false", directory + rename detection is disabled, meaning that such new files will be + left behind in the old directory. If set to "true", directory + rename detection is enabled, meaning that such new files will be + moved into the new directory. If set to "conflict", a conflict + will be reported for such paths. If merge.renames is false, + merge.directoryRenames is ignored and treated as false. Defaults + to "conflict". merge.renormalize:: Tell Git that canonical representation of files in the diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 56d54a4898..fdc28c041c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -57,7 +57,7 @@ OPTIONS This is sort of "Git root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull 'git://example.com/hello.git', 'git daemon' will interpret the path - as '/srv/git/hello.git'. + as `/srv/git/hello.git`. --base-path-relaxed:: If --base-path is enabled and repo lookup fails, with this option diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ccdc5f83d6..a88f6ae2c6 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -139,7 +139,7 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + 7-char abbreviation for the tip commit +The hash suffix is "-g" + unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 24f32e8c54..5c8a2a5e97 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -118,6 +118,7 @@ include::pretty-options.txt[] include::pretty-formats.txt[] + include::diff-format.txt[] GIT diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 43ab3b1637..d65cdb3d08 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -422,7 +422,12 @@ However it is recommended that a `filedeleteall` command precede all `filemodify`, `filecopy`, `filerename` and `notemodify` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). -The `LF` after the command is optional (it used to be required). +The `LF` after the command is optional (it used to be required). Note +that for reasons of backward compatibility, if the commit ends with a +`data` command (i.e. it has has no `from`, `merge`, `filemodify`, +`filedelete`, `filecopy`, `filerename`, `filedeleteall` or +`notemodify` commands) then two `LF` commands may appear at the end of +the command instead of just one. `author` ^^^^^^^^ @@ -966,10 +971,6 @@ might want to refer to in their commit messages. 'get-mark' SP ':' <idnum> LF .... -This command can be used anywhere in the stream that comments are -accepted. In particular, the `get-mark` command can be used in the -middle of a commit but not in the middle of a `data` command. - See ``Responses To Commands'' below for details about how to read this output safely. @@ -996,9 +997,10 @@ Output uses the same format as `git cat-file --batch`: <contents> LF ==== -This command can be used anywhere in the stream that comments are -accepted. In particular, the `cat-blob` command can be used in the -middle of a commit but not in the middle of a `data` command. +This command can be used where a `filemodify` directive can appear, +allowing it to be used in the middle of a commit. For a `filemodify` +using an inline directive, it can also appear right before the `data` +directive. See ``Responses To Commands'' below for details about how to read this output safely. @@ -1011,8 +1013,8 @@ printing a blob from the active commit (with `cat-blob`) or copying a blob or tree from a previous commit for use in the current one (with `filemodify`). -The `ls` command can be used anywhere in the stream that comments are -accepted, including the middle of a commit. +The `ls` command can also be used where a `filemodify` directive can +appear, allowing it to be used in the middle of a commit. Reading from the active commit:: This form can only be used in the middle of a `commit`. @@ -1396,6 +1398,13 @@ deltas are suboptimal (see above) then also adding the `-f` option to force recomputation of all deltas can significantly reduce the final packfile size (30-50% smaller can be quite typical). +Instead of running `git repack` you can also run `git gc +--aggressive`, which will also optimize other things after an import +(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in +linkgit:git-gc[1] the `--aggressive` option will find new deltas with +the `-f` option to linkgit:git-repack[1]. For the reasons elaborated +on above using `--aggressive` after a fast-import is one of the few +cases where it's known to be worthwhile. MEMORY UTILIZATION ------------------ diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e6f08ab189..6b53dd7e06 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -189,7 +189,7 @@ to other tags will be rewritten to point to the underlying commit. rewriting. When applying a tree filter, the command needs to temporarily check out the tree to some directory, which may consume considerable space in case of large projects. By default it - does this in the '.git-rewrite/' directory but you can override + does this in the `.git-rewrite/` directory but you can override that choice by this parameter. -f:: diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a7c1b0f60e..247f765604 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -20,17 +20,16 @@ created from prior invocations of 'git add', packing refs, pruning reflog, rerere metadata or stale working trees. May also update ancillary indexes such as the commit-graph. -Users are encouraged to run this task on a regular basis within -each repository to maintain good disk space utilization and good -operating performance. +When common porcelain operations that create objects are run, they +will check whether the repository has grown substantially since the +last maintenance, and if so run `git gc` automatically. See `gc.auto` +below for how to disable this behavior. -Some git commands may automatically run 'git gc'; see the `--auto` flag -below for details. If you know what you're doing and all you want is to -disable this behavior permanently without further considerations, just do: - ----------------------- -$ git config --global gc.auto 0 ----------------------- +Running `git gc` manually should only be needed when adding objects to +a repository without regularly running such porcelain commands, to do +a one-off repository optimization, or e.g. to clean up a suboptimal +mass-import. See the "PACKFILE OPTIMIZATION" section in +linkgit:git-fast-import[1] for more details on the import case. OPTIONS ------- @@ -40,35 +39,17 @@ OPTIONS space utilization and performance. This option will cause 'git gc' to more aggressively optimize the repository at the expense of taking much more time. The effects of this optimization are - persistent, so this option only needs to be used occasionally; every - few hundred changesets or so. + mostly persistent. See the "AGGRESSIVE" section below for details. --auto:: With this option, 'git gc' checks whether any housekeeping is required; if not, it exits without performing any work. - Some git commands run `git gc --auto` after performing - operations that could create many loose objects. Housekeeping - is required if there are too many loose objects or too many - packs in the repository. -+ -If the number of loose objects exceeds the value of the `gc.auto` -configuration variable, then all loose objects are combined into a -single pack using `git repack -d -l`. Setting the value of `gc.auto` -to 0 disables automatic packing of loose objects. + -If the number of packs exceeds the value of `gc.autoPackLimit`, -then existing packs (except those marked with a `.keep` file -or over `gc.bigPackThreshold` limit) -are consolidated into a single pack by using the `-A` option of -'git repack'. -If the amount of memory is estimated not enough for `git repack` to -run smoothly and `gc.bigPackThreshold` is not set, the largest -pack will also be excluded (this is the equivalent of running `git gc` -with `--keep-base-pack`). -Setting `gc.autoPackLimit` to 0 disables automatic consolidation of -packs. +See the `gc.auto` option in the "CONFIGURATION" section below for how +this heuristic works. + -If houskeeping is required due to many loose objects or packs, all +Once housekeeping is triggered by exceeding the limits of +configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. @@ -96,69 +77,39 @@ be performed as well. `.keep` files are consolidated into a single pack. When this option is used, `gc.bigPackThreshold` is ignored. +AGGRESSIVE +---------- + +When the `--aggressive` option is supplied, linkgit:git-repack[1] will +be invoked with the `-f` flag, which in turn will pass +`--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw +away any existing deltas and re-compute them, at the expense of +spending much more time on the repacking. + +The effects of this are mostly persistent, e.g. when packs and loose +objects are coalesced into one another pack the existing deltas in +that pack might get re-used, but there are also various cases where we +might pick a sub-optimal delta from a newer pack instead. + +Furthermore, supplying `--aggressive` will tweak the `--depth` and +`--window` options passed to linkgit:git-repack[1]. See the +`gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By +using a larger window size we're more likely to find more optimal +deltas. + +It's probably not worth it to use this option on a given repository +without running tailored performance benchmarks on it. It takes a lot +more time, and the resulting space/delta optimization may or may not +be worth it. Not using this at all is the right trade-off for most +users and their repositories. + CONFIGURATION ------------- -The optional configuration variable `gc.reflogExpire` can be -set to indicate how long historical entries within each branch's -reflog should remain available in this repository. The setting is -expressed as a length of time, for example '90 days' or '3 months'. -It defaults to '90 days'. - -The optional configuration variable `gc.reflogExpireUnreachable` -can be set to indicate how long historical reflog entries which -are not part of the current branch should remain available in -this repository. These types of entries are generally created as -a result of using `git commit --amend` or `git rebase` and are the -commits prior to the amend or rebase occurring. Since these changes -are not part of the current project most users will want to expire -them sooner. This option defaults to '30 days'. - -The above two configuration variables can be given to a pattern. For -example, this sets non-default expiry values only to remote-tracking -branches: - ------------- -[gc "refs/remotes/*"] - reflogExpire = never - reflogExpireUnreachable = 3 days ------------- - -The optional configuration variable `gc.rerereResolved` indicates -how long records of conflicted merge you resolved earlier are -kept. This defaults to 60 days. - -The optional configuration variable `gc.rerereUnresolved` indicates -how long records of conflicted merge you have not resolved are -kept. This defaults to 15 days. - -The optional configuration variable `gc.packRefs` determines if -'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable -it within all non-bare repos or it can be set to a boolean value. -This defaults to true. - -The optional configuration variable `gc.writeCommitGraph` determines if -'git gc' should run 'git commit-graph write'. This can be set to a -boolean value. This defaults to false. - -The optional configuration variable `gc.aggressiveWindow` controls how -much time is spent optimizing the delta compression of the objects in -the repository when the --aggressive option is specified. The larger -the value, the more time is spent optimizing the delta compression. See -the documentation for the --window option in linkgit:git-repack[1] for -more details. This defaults to 250. - -Similarly, the optional configuration variable `gc.aggressiveDepth` -controls --depth option in linkgit:git-repack[1]. This defaults to 50. - -The optional configuration variable `gc.pruneExpire` controls how old -the unreferenced loose objects have to be before they are pruned. The -default is "2 weeks ago". - -Optional configuration variable `gc.worktreePruneExpire` controls how -old a stale working tree should be before `git worktree prune` deletes -it. Default is "3 months ago". +The below documentation is the same as what's found in +linkgit:git-config[1]: +include::config/gc.txt[] NOTES ----- @@ -168,8 +119,8 @@ anywhere in your repository. In particular, it will keep not only objects referenced by your current set of branches and tags, but also objects referenced by the index, remote-tracking branches, refs saved by 'git filter-branch' in -refs/original/, or reflogs (which may reference commits in branches -that were later amended or rewound). +refs/original/, reflogs (which may reference commits in branches +that were later amended or rewound), and anything else in the refs/* namespace. If you are expecting some objects to be deleted and they aren't, check all of those locations and decide whether it makes sense in your case to remove those references. @@ -190,8 +141,7 @@ mitigate this problem: However, these features fall short of a complete solution, so users who run commands concurrently have to live with some risk of corruption (which -seems to be low in practice) unless they turn off automatic garbage -collection with 'git config gc.auto 0'. +seems to be low in practice). HOOKS ----- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index c318bf87e1..f71db0daa2 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -171,8 +171,8 @@ variable, we launch 'kfmclient' to try to open the man page on an already opened konqueror in a new tab if possible. For consistency, we also try such a trick if 'man.konqueror.path' is -set to something like 'A_PATH_TO/konqueror'. That means we will try to -launch 'A_PATH_TO/kfmclient' instead. +set to something like `A_PATH_TO/konqueror`. That means we will try to +launch `A_PATH_TO/kfmclient` instead. If you really want to use 'konqueror', then you can use something like the following: diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index a5e8b36f62..96ec6499f0 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -3,7 +3,7 @@ git-interpret-trailers(1) NAME ---- -git-interpret-trailers - add or parse structured information in commit messages +git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 9dee7bef35..a7515714da 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -27,9 +27,9 @@ in the current working directory. Note that: taken as relative to the current working directory. E.g. when you are in a directory 'sub' that has a directory 'dir', you can run 'git ls-tree -r HEAD dir' to list the contents of the tree (that is - 'sub/dir' in `HEAD`). You don't want to give a tree that is not at the + `sub/dir` in `HEAD`). You don't want to give a tree that is not at the root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that - would result in asking for 'sub/sub/dir' in the `HEAD` commit. + would result in asking for `sub/sub/dir` in the `HEAD` commit. However, the current working directory can be ignored by passing --full-tree option. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5c70bc2878..d271842608 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -38,8 +38,9 @@ OPTIONS started. --reset:: - Same as -m, except that unmerged entries are discarded - instead of failing. + Same as -m, except that unmerged entries are discarded instead + of failing. When used with `-u`, updates leading to loss of + working tree changes will not abort the operation. -u:: After a successful merge, update the files in the work @@ -128,6 +129,10 @@ OPTIONS Instead of reading tree object(s) into the index, just empty it. +-q:: +--quiet:: + Quiet, suppress feedback messages. + <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 3fc5d94336..88ea7e1cc0 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -104,7 +104,7 @@ begins with `ext::`. Examples: link-level address). "ext::git-server-alias foo %G/repo% with% spaces %Vfoo":: - Represents a repository with path '/repo with spaces' accessed + Represents a repository with path `/repo with spaces` accessed using the helper program "git-server-alias foo". The hostname for the remote server passed in the protocol stream will be "foo" (this allows multiple virtual Git servers to share a @@ -118,7 +118,7 @@ begins with `ext::`. Examples: SEE ALSO -------- -linkgit:gitremote-helpers[1] +linkgit:gitremote-helpers[7] GIT --- diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 80afca866c..0451ceb8a2 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -52,7 +52,7 @@ EXAMPLES SEE ALSO -------- -linkgit:gitremote-helpers[1] +linkgit:gitremote-helpers[7] GIT --- diff --git a/Documentation/git-remote-helpers.txto b/Documentation/git-remote-helpers.txto index 49233f5d26..6f353ebfd3 100644 --- a/Documentation/git-remote-helpers.txto +++ b/Documentation/git-remote-helpers.txto @@ -1,7 +1,7 @@ git-remote-helpers ================== -This document has been moved to linkgit:gitremote-helpers[1]. +This document has been moved to linkgit:gitremote-helpers[7]. Please let the owners of the referring site know so that they can update the link you clicked to get here. diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt deleted file mode 100644 index f791d73c05..0000000000 --- a/Documentation/git-remote-testgit.txt +++ /dev/null @@ -1,30 +0,0 @@ -git-remote-testgit(1) -===================== - -NAME ----- -git-remote-testgit - Example remote-helper - - -SYNOPSIS --------- -[verse] -git clone testgit::<source-repo> [<destination>] - -DESCRIPTION ------------ - -This command is a simple remote-helper, that is used both as a -testcase for the remote-helper functionality, and as an example to -show remote-helper authors one possible implementation. - -The best way to learn more is to read the comments and source code in -'git-remote-testgit'. - -SEE ALSO --------- -linkgit:gitremote-helpers[1] - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index df310d2a58..95763d7581 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -24,7 +24,7 @@ on the initial manual merge, and applying previously recorded hand resolutions to their corresponding automerge results. [NOTE] -You need to set the configuration variable rerere.enabled in order to +You need to set the configuration variable `rerere.enabled` in order to enable this command. diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 4a01371227..5cc2fcefba 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -167,7 +167,7 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +whose commit message is "Add \'git show-branch'". The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset"". The "mhf" branch adds many other commits. The current branch is "master". diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 7ef8c47911..e31ea7d303 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git stash' list [<options>] -'git stash' show [<stash>] +'git stash' show [<options>] [<stash>] 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] @@ -106,7 +106,7 @@ stash@{1}: On master: 9cc0589... Add git-stash The command takes options applicable to the 'git log' command to control what is shown and how. See linkgit:git-log[1]. -show [<stash>]:: +show [<options>] [<stash>]:: Show the changes recorded in the stash entry as a diff between the stashed contents and the commit back when the stash entry was first diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 861d821d7f..d4e8f24f0c 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -278,7 +278,8 @@ Header lines start with "#" and are added in response to specific command line arguments. Parsers should ignore headers they don't recognize. -### Branch Headers +Branch Headers +^^^^^^^^^^^^^^ If `--branch` is given, a series of header lines are printed with information about the current branch. @@ -294,7 +295,8 @@ Line Notes ------------------------------------------------------------ .... -### Changed Tracked Entries +Changed Tracked Entries +^^^^^^^^^^^^^^^^^^^^^^^ Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe @@ -365,7 +367,8 @@ Field Meaning -------------------------------------------------------- .... -### Other Items +Other Items +^^^^^^^^^^^ Following the tracked entries (and if requested), a series of lines will be printed for untracked and then ignored items @@ -379,7 +382,8 @@ Ignored items have the following format: ! <path> -### Pathname Format Notes and -z +Pathname Format Notes and -z +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2794e29780..0ed5c24dc1 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 'git submodule' [--quiet] update [<options>] [--] [<path>...] +'git submodule' [--quiet] set-branch [<options>] [--] <path> 'git submodule' [--quiet] summary [<options>] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--recursive] [--] [<path>...] @@ -42,7 +43,7 @@ This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's default remote repository (Please note that to specify a repository 'foo.git' which is located right next to a superproject 'bar.git', you'll -have to use '../foo.git' instead of './foo.git' - as one might expect +have to use `../foo.git` instead of `./foo.git` - as one might expect when following the rules for relative URLs - because the evaluation of relative URLs in Git is identical to that of relative directories). + @@ -172,6 +173,12 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. -- +set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>:: + Sets the default remote tracking branch for the submodule. The + `--branch` option allows the remote branch to be specified. The + `--default` option removes the submodule.<name>.branch configuration + key, which causes the tracking branch to default to 'master'. + summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits @@ -259,13 +266,14 @@ OPTIONS This option is only valid for the deinit command. Unregister all submodules in the working tree. --b:: ---branch:: +-b <branch>:: +--branch <branch>:: Branch of repository to add as submodule. The name of the branch is recorded as `submodule.<name>.branch` in `.gitmodules` for `update --remote`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the - same name as the current branch in the current repository. + same name as the current branch in the current repository. If the + option is not specified, it defaults to 'master'. -f:: --force:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 223788fa3e..30711625fd 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -1100,10 +1100,10 @@ listed below are allowed: tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ -Keep in mind that the '\*' (asterisk) wildcard of the local ref -(right of the ':') *must* be the farthest right path component; +Keep in mind that the `*` (asterisk) wildcard of the local ref +(right of the `:`) *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's an -independent path component (surrounded by '/' or EOL). This +independent path component (surrounded by `/` or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index fd952a5ff9..8d162b56c5 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -92,8 +92,8 @@ configuration variable, we launch 'kfmclient' to try to open the HTML man page on an already opened konqueror in a new tab if possible. For consistency, we also try such a trick if 'browser.konqueror.path' is -set to something like 'A_PATH_TO/konqueror'. That means we will try to -launch 'A_PATH_TO/kfmclient' instead. +set to something like `A_PATH_TO/konqueror`. That means we will try to +launch `A_PATH_TO/kfmclient` instead. If you really want to use 'konqueror', then you can use something like the following: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 5bf653c111..786e778ab8 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -496,6 +496,24 @@ This hook is invoked by `git-p4 submit`. It takes no parameters and nothing from standard input. Exiting with non-zero status from this script prevent `git-p4 submit` from launching. Run `git-p4 submit --help` for details. +post-index-change +~~~~~~~~~~~~~~~~~ + +This hook is invoked when the index is written in read-cache.c +do_write_locked_index. + +The first parameter passed to the hook is the indicator for the +working directory being updated. "1" meaning working directory +was updated or "0" when the working directory was not updated. + +The second parameter passed to the hook is the indicator for whether +or not the index was updated and the skip-worktree bit could have +changed. "1" meaning skip-worktree bits could have been updated +and "0" meaning they were not. + +Only one parameter should be set to "1" when the hook runs. The hook +running passing "1", "1" should not be possible. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 244cd01493..1eabb0aaf3 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -168,12 +168,12 @@ Files ----- User configuration and preferences are stored at: -* '$XDG_CONFIG_HOME/git/gitk' if it exists, otherwise -* '$HOME/.gitk' if it exists +* `$XDG_CONFIG_HOME/git/gitk` if it exists, otherwise +* `$HOME/.gitk` if it exists -If neither of the above exist then '$XDG_CONFIG_HOME/git/gitk' is created and +If neither of the above exist then `$XDG_CONFIG_HOME/git/gitk` is created and used by default. If '$XDG_CONFIG_HOME' is not set it defaults to -'$HOME/.config' in all cases. +`$HOME/.config` in all cases. History ------- diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 312b6f9259..a66e95b70c 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -115,7 +115,7 @@ Consider the following .gitmodules file: This defines two submodules, `libfoo` and `libbar`. These are expected to -be checked out in the paths 'include/foo' and 'include/bar', and for both +be checked out in the paths `include/foo` and `include/bar`, and for both submodules a URL is specified which can be used for cloning the submodules. SEE ALSO diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 4f2905dc5d..43f80c8068 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -1,4 +1,4 @@ -gitremote-helpers(1) +gitremote-helpers(7) ==================== NAME @@ -513,8 +513,6 @@ linkgit:git-remote-ext[1] linkgit:git-remote-fd[1] -linkgit:git-remote-testgit[1] - linkgit:git-fast-import[1] GIT diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 366dee238c..216b11ee88 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -84,7 +84,7 @@ objects/info/alternates:: to the object database, not to the repository!) in your alternates file, but it will not work if you use absolute paths unless the absolute path in filesystem and web URL - is the same. See also 'objects/info/http-alternates'. + is the same. See also `objects/info/http-alternates`. objects/info/http-alternates:: This file records URLs to alternate object stores that diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index b284953f64..35317e71c8 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -50,11 +50,11 @@ following order: * built-in values (some set during build stage), * common system-wide configuration file (defaults to - '/etc/gitweb-common.conf'), + `/etc/gitweb-common.conf`), * either per-instance configuration file (defaults to 'gitweb_config.perl' in the same directory as the installed gitweb), or if it does not exists - then fallback system-wide configuration file (defaults to '/etc/gitweb.conf'). + then fallback system-wide configuration file (defaults to `/etc/gitweb.conf`). Values obtained in later configuration files override values obtained earlier in the above sequence. @@ -82,7 +82,7 @@ You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one of Git repository management tools) in a separate file, e.g. in -'/etc/gitweb-gitolite.conf'. To include it, put +`/etc/gitweb-gitolite.conf`. To include it, put -------------------------------------------------- read_config_file("/etc/gitweb-gitolite.conf"); @@ -142,7 +142,7 @@ and its path_info based equivalent http://git.example.com/gitweb.cgi/foo/bar.git ------------------------------------------------ + -will map to the path '/srv/git/foo/bar.git' on the filesystem. +will map to the path `/srv/git/foo/bar.git` on the filesystem. $projects_list:: Name of a plain text file listing projects, or a name of directory @@ -234,9 +234,9 @@ $GIT:: $mimetypes_file:: File to use for (filename extension based) guessing of MIME types before - trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken + trying `/etc/mime.types`. *NOTE* that this path, if relative, is taken as relative to the current Git repository, not to CGI script. If unset, - only '/etc/mime.types' is used (if present on filesystem). If no mimetypes + only `/etc/mime.types` is used (if present on filesystem). If no mimetypes file is found, mimetype guessing based on extension of file is disabled. Unset by default. @@ -297,8 +297,8 @@ relative to base URI of gitweb. + This list should contain the URI of gitweb's standard stylesheet. The default URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS` -makefile variable. Its default value is 'static/gitweb.css' -(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined, +makefile variable. Its default value is `static/gitweb.css` +(or `static/gitweb.min.css` if the `CSSMIN` variable is defined, i.e. if CSS minifier is used during build). + *Note*: there is also a legacy `$stylesheet` configuration variable, which was @@ -311,7 +311,7 @@ $logo:: is displayed in the top right corner of each gitweb page and used as a logo for the Atom feed. Relative to the base URI of gitweb (as a path). Can be adjusted when building gitweb using `GITWEB_LOGO` variable - By default set to 'static/git-logo.png'. + By default set to `static/git-logo.png`. $favicon:: Points to the location where you put 'git-favicon.png' on your web @@ -320,7 +320,7 @@ $favicon:: may display them in the browser's URL bar and next to the site name in bookmarks. Relative to the base URI of gitweb. Can be adjusted at build time using `GITWEB_FAVICON` variable. - By default set to 'static/git-favicon.png'. + By default set to `static/git-favicon.png`. $javascript:: Points to the location where you put 'gitweb.js' on your web server, @@ -328,7 +328,7 @@ $javascript:: Relative to the base URI of gitweb. Can be set at build time using the `GITWEB_JS` build-time configuration variable. + -The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if +The default value is either `static/gitweb.js`, or `static/gitweb.min.js` if the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used at build time. *Note* that this single file is generated from multiple individual JavaScript "modules". @@ -444,7 +444,7 @@ $default_blob_plain_mimetype:: doesn't result in some other type; by default "text/plain". Gitweb guesses mimetype of a file to display based on extension of its filename, using `$mimetypes_file` (if set and file exists) - and '/etc/mime.types' files (see *mime.types*(5) manpage; only + and `/etc/mime.types` files (see *mime.types*(5) manpage; only filename extension rules are supported by gitweb). $default_text_plain_charset:: @@ -486,7 +486,7 @@ affects how "summary" pages look like, or load limiting). (for example one for `git://` protocol, and one for `http://` protocol). + -Note that per repository configuration can be set in '$GIT_DIR/cloneurl' +Note that per repository configuration can be set in `$GIT_DIR/cloneurl` file, or as values of multi-value `gitweb.url` configuration variable in project config. Per-repository configuration takes precedence over value composed from `@git_base_url_list` elements and project name. @@ -520,7 +520,7 @@ $maxload:: If the server load exceeds this value then gitweb will return "503 Service Unavailable" error. The server load is taken to be 0 if gitweb cannot determine its value. Currently it works only on Linux, - where it uses '/proc/loadavg'; the load there is the number of active + where it uses `/proc/loadavg`; the load there is the number of active tasks on the system -- processes that are actually running -- averaged over the last minute. + @@ -739,7 +739,7 @@ Currently available providers are *"gravatar"* and *"picon"*. Only one provider at a time can be selected ('default' is one element list). If an unknown provider is specified, the feature is disabled. *Note* that some providers might require extra Perl packages to be -installed; see 'gitweb/INSTALL' for more details. +installed; see `gitweb/INSTALL` for more details. + This feature can be configured on a per-repository basis via repository's `gitweb.avatar` configuration variable. diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 88450589af..c7436098c9 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -36,7 +36,7 @@ browsed using gitweb itself. CONFIGURATION ------------- Various aspects of gitweb's behavior can be controlled through the configuration -file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] +file `gitweb_config.perl` or `/etc/gitweb.conf`. See the linkgit:gitweb.conf[5] for details. Repositories @@ -51,7 +51,7 @@ projects' root" subsection). our $projectroot = '/path/to/parent/directory'; ----------------------------------------------------------------------- -The default value for `$projectroot` is '/pub/git'. You can change it during +The default value for `$projectroot` is `/pub/git`. You can change it during building gitweb via `GITWEB_PROJECTROOT` build configuration variable. By default all Git repositories under `$projectroot` are visible and available @@ -231,7 +231,7 @@ Unnamed repository; edit this file to name it for gitweb. ------------------------------------------------------------------------------- + from the template during repository creation, usually installed in -'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo +`/usr/share/git-core/templates/`. You can use the `gitweb.description` repo configuration variable, but the file takes precedence. category (or `gitweb.category`):: @@ -407,7 +407,7 @@ in the instructions so they can be included in a future release. Apache as CGI ~~~~~~~~~~~~~ Apache must be configured to support CGI scripts in the directory in -which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' +which gitweb is installed. Let's assume that it is `/var/www/cgi-bin` directory. ----------------------------------------------------------------------- @@ -431,7 +431,7 @@ You can use mod_perl with gitweb. You must install Apache::Registry (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable this support. -Assuming that gitweb is installed to '/var/www/perl', the following +Assuming that gitweb is installed to `/var/www/perl`, the following Apache configuration (for mod_perl 2.x) is suitable. ----------------------------------------------------------------------- @@ -456,7 +456,7 @@ Apache with FastCGI ~~~~~~~~~~~~~~~~~~~ Gitweb works with Apache and FastCGI. First you need to rename, copy or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is -installed in '/usr/share/gitweb' directory. The following Apache +installed in `/usr/share/gitweb` directory. The following Apache configuration is suitable (UNTESTED!) ----------------------------------------------------------------------- @@ -503,22 +503,22 @@ repositories, you can configure Apache like this: ----------------------------------------------------------------------- The above configuration expects your public repositories to live under -'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, +`/pub/git` and will serve them as `http://git.domain.org/dir-under-pub-git`, both as clonable Git URL and as browseable gitweb interface. If you then start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` then you can even use the `git://` URL with exactly the same path. Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the -named file (i.e. in this example '/etc/gitweb.conf') as a configuration for +named file (i.e. in this example `/etc/gitweb.conf`) as a configuration for gitweb. You don't really need it in above example; it is required only if your configuration file is in different place than built-in (during -compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See +compiling gitweb) 'gitweb_config.perl' or `/etc/gitweb.conf`. See linkgit:gitweb.conf[5] for details, especially information about precedence rules. If you use the rewrite rules from the example you *might* also need something like the following in your gitweb configuration file -('/etc/gitweb.conf' following example): +(`/etc/gitweb.conf` following example): ---------------------------------------------------------------------------- @stylesheets = ("/some/absolute/path/gitweb.css"); $my_uri = "/"; @@ -575,7 +575,7 @@ like this: Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` environment variable from a web server, so you need to put the following -line in gitweb configuration file ('/etc/gitweb.conf' in above example): +line in gitweb configuration file (`/etc/gitweb.conf` in above example): -------------------------------------------------------------------------- $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; -------------------------------------------------------------------------- @@ -585,7 +585,7 @@ referenced by `$per_request_config`; These configurations enable two things. First, each unix user (`<user>`) of the server will be able to browse through gitweb Git repositories found in -'~/public_git/' with the following url: +`~/public_git/` with the following url: http://git.example.org/~<user>/ @@ -596,7 +596,7 @@ If you already use `mod_userdir` in your virtual host or you don't want to use the \'~' as first character, just comment or remove the second rewrite rule, and uncomment one of the following according to what you want. -Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible +Second, repositories found in `/pub/scm/` and `/var/git/` will be accessible through `http://git.example.org/scm/` and `http://git.example.org/var/`. You can add as many project roots as you want by adding rewrite rules like the third and the fourth. @@ -614,7 +614,7 @@ that it consumes and produces URLs in the form http://git.example.com/project.git/shortlog/sometag i.e. without 'gitweb.cgi' part, by using a configuration such as the -following. This configuration assumes that '/var/www/gitweb' is the +following. This configuration assumes that `/var/www/gitweb` is the DocumentRoot of your webserver, contains the gitweb.cgi script and complementary static files (stylesheet, favicon, JavaScript): @@ -645,9 +645,9 @@ parameter. `@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" access to your project .git dirs (described in "Single URL for gitweb and for fetching" section). A possible workaround for the latter is the -following: in your project root dir (e.g. '/pub/git') have the projects -named *without* a .git extension (e.g. '/pub/git/project' instead of -'/pub/git/project.git') and configure Apache as follows: +following: in your project root dir (e.g. `/pub/git`) have the projects +named *without* a .git extension (e.g. `/pub/git/project` instead of +`/pub/git/project.git`) and configure Apache as follows: ---------------------------------------------------------------------------- <VirtualHost *:80> ServerAlias git.example.com @@ -681,7 +681,7 @@ cloned), while will provide human-friendly gitweb access. This solution is not 100% bulletproof, in the sense that if some project has -a named ref (branch, tag) starting with 'git/', then paths such as +a named ref (branch, tag) starting with `git/`, then paths such as http://git.example.com/project/command/abranch..git/abranch @@ -697,7 +697,7 @@ SEE ALSO -------- linkgit:gitweb.conf[5], linkgit:git-instaweb[1] -'gitweb/README', 'gitweb/INSTALL' +`gitweb/README`, `gitweb/INSTALL` GIT --- diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index f44e5e9458..bfe6f9b500 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -244,8 +244,8 @@ Using a proxy: -------------- If you have to access the WebDAV server from behind an HTTP(S) proxy, -set the variable 'all_proxy' to 'http://proxy-host.com:port', or -'http://login-on-proxy:passwd-on-proxy@proxy-host.com:port'. See 'man +set the variable 'all_proxy' to `http://proxy-host.com:port`, or +`http://login-on-proxy:passwd-on-proxy@proxy-host.com:port`. See 'man curl' for details. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 9cf983d24d..ddbc1de43f 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -805,12 +805,13 @@ include::pretty-options.txt[] author's). If `-local` is appended to the format (e.g., `iso-local`), the user's local time zone is used instead. + +-- `--date=relative` shows dates relative to the current time, e.g. ``2 hours ago''. The `-local` option has no effect for `--date=relative`. -+ + `--date=local` is an alias for `--date=default-local`. -+ + `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format. The differences to the strict ISO 8601 format are: @@ -818,15 +819,14 @@ The differences to the strict ISO 8601 format are: - a space between time and time zone - no colon between hours and minutes of the time zone -+ `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict ISO 8601 format. -+ + `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 format, often found in email messages. -+ + `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. -+ + `--date=raw` shows the date as seconds since the epoch (1970-01-01 00:00:00 UTC), followed by a space, and then the timezone as an offset from UTC (a `+` or `-` with four digits; the first two are hours, and @@ -835,28 +835,28 @@ with `strftime("%s %z")`). Note that the `-local` option does not affect the seconds-since-epoch value (which is always measured in UTC), but does switch the accompanying timezone value. -+ + `--date=human` shows the timezone if the timezone does not match the current time-zone, and doesn't print the whole date if that matches (ie skip printing year for dates that are "this year", but also skip the whole date itself if it's in the last few days and we can just say what weekday it was). For older dates the hour and minute is also omitted. -+ + `--date=unix` shows the date as a Unix epoch timestamp (seconds since 1970). As with `--raw`, this is always in UTC and therefore `-local` has no effect. -+ + `--date=format:...` feeds the format `...` to your system `strftime`, except for %z and %Z, which are handled internally. Use `--date=format:%c` to show the date in your system locale's preferred format. See the `strftime` manual for a complete list of format placeholders. When using `-local`, the correct syntax is `--date=format-local:...`. -+ + `--date=default` is the default format, and is similar to `--date=rfc2822`, with a few exceptions: - +-- - there is no comma after the day-of-week - the time zone is omitted when the local time zone is used diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 72daa20e76..2337a995ec 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -58,7 +58,7 @@ when you run `git merge`. when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from -the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. +the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. @@ -108,7 +108,7 @@ some output processing may assume ref names in UTF-8. `git push` were run while `branchname` was checked out (or the current `HEAD` if no branchname is specified). Since our push destination is in a remote repository, of course, we report the local tracking branch - that corresponds to that branch (i.e., something in 'refs/remotes/'). + that corresponds to that branch (i.e., something in `refs/remotes/`). + Here's an example to make it more clear: + diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt index 5747f442f2..5a57c4a407 100644 --- a/Documentation/sequencer.txt +++ b/Documentation/sequencer.txt @@ -1,6 +1,6 @@ --continue:: Continue the operation in progress using the information in - '.git/sequencer'. Can be used to continue after resolving + `.git/sequencer`. Can be used to continue after resolving conflicts in a failed cherry-pick or revert. --quit:: diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index fa39ac9d71..7d20716c32 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -229,7 +229,7 @@ A `config_set` can be used to construct an in-memory cache for config-like files that the caller specifies (i.e., files like `.gitmodules`, `~/.gitconfig` etc.). For example, ---------------------------------------- +---------------------------------------- struct config_set gm_config; git_configset_init(&gm_config); int b; diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 2b036d7838..2e2e7c10c6 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -198,8 +198,10 @@ There are some macros to easily define options: The filename will be prefixed by passing the filename along with the prefix argument of `parse_options()` to `prefix_filename()`. -`OPT_ARGUMENT(long, description)`:: +`OPT_ARGUMENT(long, &int_var, description)`:: Introduce a long-option argument that will be kept in `argv[]`. + If this option was seen, `int_var` will be set to one (except + if a `NULL` pointer was passed). `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: Recognize numerical options like -123 and feed the integer as diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index ead85ce35c..03264c7d9a 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -1,5 +1,5 @@ - Git Wire Protocol, Version 2 -============================== +Git Wire Protocol, Version 2 +============================ This document presents a specification for a version 2 of Git's wire protocol. Protocol v2 will improve upon v1 in the following ways: @@ -22,8 +22,8 @@ will be commands which a client can request be executed. Once a command has completed, a client can reuse the connection and request that other commands be executed. - Packet-Line Framing ---------------------- +Packet-Line Framing +------------------- All communication is done using packet-line framing, just as in v1. See `Documentation/technical/pack-protocol.txt` and @@ -34,8 +34,8 @@ In protocol v2 these special packets will have the following semantics: * '0000' Flush Packet (flush-pkt) - indicates the end of a message * '0001' Delimiter Packet (delim-pkt) - separates sections of a message - Initial Client Request ------------------------- +Initial Client Request +---------------------- In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being @@ -43,22 +43,22 @@ used which inevitably sets `GIT_PROTOCOL`. More information can be found in `pack-protocol.txt` and `http-protocol.txt`. In all cases the response from the server is the capability advertisement. - Git Transport -~~~~~~~~~~~~~~~ +Git Transport +~~~~~~~~~~~~~ When using the git:// transport, you can request to use protocol v2 by sending "version=2" as an extra parameter: 003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0 - SSH and File Transport -~~~~~~~~~~~~~~~~~~~~~~~~ +SSH and File Transport +~~~~~~~~~~~~~~~~~~~~~~ When using either the ssh:// or file:// transport, the GIT_PROTOCOL environment variable must be set explicitly to include "version=2". - HTTP Transport -~~~~~~~~~~~~~~~~ +HTTP Transport +~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" info/refs request as described in `http-protocol.txt` and requests that @@ -79,8 +79,8 @@ A v2 server would reply: Subsequent requests are then made directly to the service `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack). - Capability Advertisement --------------------------- +Capability Advertisement +------------------------ A server which decides to communicate (based on a request from a client) using protocol version 2, notifies the client by sending a version string @@ -101,8 +101,8 @@ to be executed by the client. key = 1*(ALPHA | DIGIT | "-_") value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;") - Command Request ------------------ +Command Request +--------------- After receiving the capability advertisement, a client can then issue a request to select the command it wants with any particular capabilities @@ -137,8 +137,8 @@ command be executed or can terminate the connection. A client may optionally send an empty request consisting of just a flush-pkt to indicate that no more requests will be made. - Capabilities --------------- +Capabilities +------------ There are two different types of capabilities: normal capabilities, which can be used to to convey information or alter the behavior of a @@ -153,8 +153,8 @@ management on the server side in order to function correctly. This permits simple round-robin load-balancing on the server side, without needing to worry about state management. - agent -~~~~~~~ +agent +~~~~~ The server can advertise the `agent` capability with a value `X` (in the form `agent=X`) to notify the client that the server is running version @@ -168,8 +168,8 @@ printable ASCII characters except space (i.e., the byte range 32 < x < and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features. - ls-refs -~~~~~~~~~ +ls-refs +~~~~~~~ `ls-refs` is the command used to request a reference advertisement in v2. Unlike the current reference advertisement, ls-refs takes in arguments @@ -199,8 +199,8 @@ The output of ls-refs is as follows: symref = "symref-target:" symref-target peeled = "peeled:" obj-id - fetch -~~~~~~~ +fetch +~~~~~ `fetch` is the command used to fetch a packfile in v2. It can be looked at as a modified version of the v1 fetch where the ref-advertisement is @@ -444,8 +444,8 @@ header. 2 - progress messages 3 - fatal error message just before stream aborts - server-option -~~~~~~~~~~~~~~~ +server-option +~~~~~~~~~~~~~ If advertised, indicates that any number of server specific options can be included in a request. This is done by sending each option as a diff --git a/Documentation/urls.txt b/Documentation/urls.txt index b05da95788..bc354fe2dc 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -62,7 +62,7 @@ may be used: where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See linkgit:gitremote-helpers[1] for details. +invoked. See linkgit:gitremote-helpers[7] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you |