From: Junio C Hamano Date: Thu, 25 Apr 2019 07:41:18 +0000 (+0900) Subject: Merge branch 'ab/gc-docs' X-Git-Tag: v2.22.0-rc0~54 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ac70c5313351630e44b1fe0267fb4850ebcf1f25?hp=-c Merge branch 'ab/gc-docs' Update docs around "gc". * ab/gc-docs: gc docs: remove incorrect reference to gc.auto=0 gc docs: clarify that "gc" doesn't throw away referenced objects gc docs: note "gc --aggressive" in "fast-import" gc docs: downplay the usefulness of --aggressive gc docs: note how --aggressive impacts --window & --depth gc docs: fix formatting for "gc.writeCommitGraph" gc docs: re-flow the "gc.*" section in "config" gc docs: include the "gc.*" section from "config" in "gc" gc docs: clean grammar for "gc.bigPackThreshold" gc docs: stop noting "repack" flags gc docs: modernize the advice for manually running "gc" --- ac70c5313351630e44b1fe0267fb4850ebcf1f25 diff --combined Documentation/config/gc.txt index 73c08b0c00,f732fe5bfd..02b92b18b5 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@@ -1,25 -1,42 +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. + 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 +53,16 @@@ Note that if the number of kept packs i 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 +116,12 @@@ gc..reflogExpireUnreachable: With "" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the . + + + 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 --combined Documentation/git-fast-import.txt index 33cce1e150,2248755cb7..d65cdb3d08 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@@ -422,12 -422,7 +422,12 @@@ However it is recommended that a `filed 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` ^^^^^^^^ @@@ -971,6 -966,10 +971,6 @@@ might want to refer to in their commit 'get-mark' SP ':' 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. @@@ -997,10 -996,9 +997,10 @@@ Output uses the same format as `git cat 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. @@@ -1013,8 -1011,8 +1013,8 @@@ printing a blob from the active commit 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`. @@@ -1398,6 -1396,13 +1398,13 @@@ deltas are suboptimal (see above) then 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 ------------------