From: Junio C Hamano Date: Wed, 23 May 2018 05:38:21 +0000 (+0900) Subject: Merge branch 'nd/doc-header' X-Git-Tag: v2.18.0-rc0~45 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/6b0f1d9c475038a54343c007193f1c81ae82b959?hp=-c Merge branch 'nd/doc-header' Doc formatting fix. * nd/doc-header: doc: keep first level section header in upper case --- 6b0f1d9c475038a54343c007193f1c81ae82b959 diff --combined Documentation/git-apply.txt index c993fbf714,ad0888bfcb..67228494c0 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@@ -113,10 -113,8 +113,10 @@@ explained for the configuration variabl linkgit:git-config[1]). -p:: - Remove leading slashes from traditional diff paths. The - default is 1. + Remove leading path components (separated by slashes) from + traditional diff paths. E.g., with `-p2`, a patch against + `a/dir/file` will be applied directly to `file`. The default is + 1. -C:: Ensure at least lines of surrounding context match before @@@ -242,7 -240,7 +242,7 @@@ When `git apply` is used as a "better G the `--unsafe-paths` option to override this safety check. This option has no effect when `--index` or `--cached` is in use. - Configuration + CONFIGURATION ------------- apply.ignoreWhitespace:: @@@ -253,7 -251,7 +253,7 @@@ apply.whitespace: When no `--whitespace` flag is given from the command line, this configuration item is used as the default. - Submodules + SUBMODULES ---------- If the patch contains any changes to submodules then 'git apply' treats these changes as follows. diff --combined Documentation/git-clone.txt index b844b9957c,5a863f9a4c..a55536f0bf --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@@ -260,7 -260,7 +260,7 @@@ or `--mirror` is given :: The (possibly remote) repository to clone from. See the - <> section below for more information on specifying + <> section below for more information on specifying repositories. :: @@@ -273,7 -273,7 +273,7 @@@ :git-clone: 1 include::urls.txt[] - Examples + EXAMPLES -------- * Clone from upstream: diff --combined Documentation/git-filter-branch.txt index 1d4d2f8604,aae0253379..e6f08ab189 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@@ -230,7 -230,7 +230,7 @@@ rewrite, the exit status is `2`. On an any other non-zero value. - Examples + EXAMPLES -------- Suppose you want to remove a file (containing confidential information @@@ -288,7 -288,7 +288,7 @@@ git filter-branch --parent-filter or even simpler: ----------------------------------------------- -echo "$commit-id $graft-id" >> .git/info/grafts +git replace --graft $commit-id $graft-id git filter-branch $graft-id..HEAD ----------------------------------------------- @@@ -406,7 -406,7 +406,7 @@@ git filter-branch --index-filter - Checklist for Shrinking a Repository + CHECKLIST FOR SHRINKING A REPOSITORY ------------------------------------ git-filter-branch can be used to get rid of a subset of files, @@@ -445,7 -445,7 +445,7 @@@ warned (or if your git-gc is not new enough to support arguments to `--prune`, use `git repack -ad; git prune` instead). - Notes + NOTES ----- git-filter-branch allows you to make complex shell-scripted rewrites diff --combined Documentation/git-gc.txt index bb376ac584,b61fb5751f..24b2dd44fe --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@@ -9,7 -9,7 +9,7 @@@ git-gc - Cleanup unnecessary files and SYNOPSIS -------- [verse] -'git gc' [--aggressive] [--auto] [--quiet] [--prune= | --no-prune] [--force] +'git gc' [--aggressive] [--auto] [--quiet] [--prune= | --no-prune] [--force] [--keep-largest-pack] DESCRIPTION ----------- @@@ -56,16 -56,10 +56,16 @@@ single pack using `git repack -d -l`. 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) +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'. Setting `gc.autoPackLimit` to 0 disables -automatic consolidation of packs. +'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. + If houskeeping is required due to many loose objects or packs, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will @@@ -90,12 -84,7 +90,12 @@@ be performed as well Force `git gc` to run even if there may be another `git gc` instance running on this repository. +--keep-largest-pack:: + All packs except the largest pack and those marked with a + `.keep` files are consolidated into a single pack. When this + option is used, `gc.bigPackThreshold` is ignored. + - Configuration + CONFIGURATION ------------- The optional configuration variable `gc.reflogExpire` can be @@@ -140,7 -129,7 +140,7 @@@ The optional configuration variable `gc 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 +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` @@@ -155,7 -144,7 +155,7 @@@ old a stale working tree should be befo it. Default is "3 months ago". - Notes + NOTES ----- 'git gc' tries very hard not to delete objects that are referenced diff --combined Documentation/git-push.txt index 34410f9fca,241c4ddbbe..02f6501399 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@@ -300,7 -300,7 +300,7 @@@ origin +master` to force a push to the These options are passed to linkgit:git-send-pack[1]. A thin transfer significantly reduces the amount of sent data when the sender and receiver share many of the same objects in common. The default is - \--thin. + `--thin`. -q:: --quiet:: @@@ -423,7 -423,7 +423,7 @@@ reason: refs, no explanation is needed. For a failed ref, the reason for failure is described. - Note about fast-forwards + NOTE ABOUT FAST-FORWARDS ------------------------ When an update changes a branch (or more in general, a ref) that used to @@@ -510,7 -510,7 +510,7 @@@ overwrite it. In other words, "git pus a case where you do mean to lose history. - Examples + EXAMPLES -------- `git push`:: diff --combined Documentation/gitattributes.txt index ee210be3ec,ee95d8531d..b72936a885 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@@ -279,94 -279,6 +279,94 @@@ few exceptions. Even though.. catch potential problems early, safety triggers. +`working-tree-encoding` +^^^^^^^^^^^^^^^^^^^^^^^ + +Git recognizes files encoded in ASCII or one of its supersets (e.g. +UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other +encodings (e.g. UTF-16) are interpreted as binary and consequently +built-in Git text processing tools (e.g. 'git diff') as well as most Git +web front ends do not visualize the contents of these files by default. + +In these cases you can tell Git the encoding of a file in the working +directory with the `working-tree-encoding` attribute. If a file with this +attribute is added to Git, then Git reencodes the content from the +specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded +content in its internal data structure (called "the index"). On checkout +the content is reencoded back to the specified encoding. + +Please note that using the `working-tree-encoding` attribute may have a +number of pitfalls: + +- Alternative Git implementations (e.g. JGit or libgit2) and older Git + versions (as of March 2018) do not support the `working-tree-encoding` + attribute. If you decide to use the `working-tree-encoding` attribute + in your repository, then it is strongly recommended to ensure that all + clients working with the repository support it. + + For example, Microsoft Visual Studio resources files (`*.rc`) or + PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16. + If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with + a `working-tree-encoding` enabled Git client, then `foo.ps1` will be + stored as UTF-8 internally. A client without `working-tree-encoding` + support will checkout `foo.ps1` as UTF-8 encoded file. This will + typically cause trouble for the users of this file. + + If a Git client, that does not support the `working-tree-encoding` + attribute, adds a new file `bar.ps1`, then `bar.ps1` will be + stored "as-is" internally (in this example probably as UTF-16). + A client with `working-tree-encoding` support will interpret the + internal contents as UTF-8 and try to convert it to UTF-16 on checkout. + That operation will fail and cause an error. + +- Reencoding content to non-UTF encodings can cause errors as the + conversion might not be UTF-8 round trip safe. If you suspect your + encoding to not be round trip safe, then add it to + `core.checkRoundtripEncoding` to make Git check the round trip + encoding (see linkgit:git-config[1]). SHIFT-JIS (Japanese character + set) is known to have round trip issues with UTF-8 and is checked by + default. + +- Reencoding content requires resources that might slow down certain + Git operations (e.g 'git checkout' or 'git add'). + +Use the `working-tree-encoding` attribute only if you cannot store a file +in UTF-8 encoding and if you want Git to be able to process the content +as text. + +As an example, use the following attributes if your '*.ps1' files are +UTF-16 encoded with byte order mark (BOM) and you want Git to perform +automatic line ending conversion based on your platform. + +------------------------ +*.ps1 text working-tree-encoding=UTF-16 +------------------------ + +Use the following attributes if your '*.ps1' files are UTF-16 little +endian encoded without BOM and you want Git to use Windows line endings +in the working directory. Please note, it is highly recommended to +explicitly define the line endings with `eol` if the `working-tree-encoding` +attribute is used to avoid ambiguity. + +------------------------ +*.ps1 text working-tree-encoding=UTF-16LE eol=CRLF +------------------------ + +You can get a list of all available encodings on your platform with the +following command: + +------------------------ +iconv --list +------------------------ + +If you do not know the encoding of a file, then you can use the `file` +command to guess the encoding: + +------------------------ +file foo.ps1 +------------------------ + + `ident` ^^^^^^^ @@@ -1229,8 -1141,8 +1229,8 @@@ to ------------ - EXAMPLE - ------- + EXAMPLES + -------- If you have these three `gitattributes` file: