Doc formatting fix.
* nd/doc-header:
doc: keep first level section header in upper case
linkgit:git-config[1]).
-p<n>::
- Remove <n> leading slashes from traditional diff paths. The
- default is 1.
+ Remove <n> 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<n>::
Ensure at least <n> lines of surrounding context match before
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::
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.
<repository>::
The (possibly remote) repository to clone from. See the
- <<URLS,URLS>> section below for more information on specifying
+ <<URLS,GIT URLS>> section below for more information on specifying
repositories.
<directory>::
:git-clone: 1
include::urls.txt[]
- Examples
+ EXAMPLES
--------
* Clone from upstream:
any other non-zero value.
- Examples
+ EXAMPLES
--------
Suppose you want to remove a file (containing confidential information
or even simpler:
-----------------------------------------------
-echo "$commit-id $graft-id" >> .git/info/grafts
+git replace --graft $commit-id $graft-id
git filter-branch $graft-id..HEAD
-----------------------------------------------
- Checklist for Shrinking a Repository
+ CHECKLIST FOR SHRINKING A REPOSITORY
------------------------------------
git-filter-branch can be used to get rid of a subset of files,
(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
SYNOPSIS
--------
[verse]
-'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force]
+'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
DESCRIPTION
-----------
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
Force `git gc` to run even if there may be another `git gc`
instance running on this repository.
- Configuration
+--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
-------------
The optional configuration variable `gc.reflogExpire` can be
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`
it. Default is "3 months ago".
- Notes
+ NOTES
-----
'git gc' tries very hard not to delete objects that are referenced
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::
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
a case where you do mean to lose history.
- Examples
+ EXAMPLES
--------
`git push`::
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`
^^^^^^^
------------
- EXAMPLE
- -------
+ EXAMPLES
+ --------
If you have these three `gitattributes` file: