Merge branch 'ab/gc-docs'
authorJunio C Hamano <gitster@pobox.com>
Thu, 25 Apr 2019 07:41:18 +0000 (16:41 +0900)
committerJunio C Hamano <gitster@pobox.com>
Thu, 25 Apr 2019 07:41:18 +0000 (16:41 +0900)
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"

1  2 
Documentation/config/gc.txt
Documentation/git-fast-import.txt
index 73c08b0c00cb124b3de230f770a1c48cc27e4a21,f732fe5bfdf4df4fc7bc755e245506000d2ad391..02b92b18b5c2cf6f9d509483a4bb995f3677d519
@@@ -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.<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
index 33cce1e150ad0644004ef687d43be62e09406482,2248755cb7cff490e0f4a64a6037e6f9d09d2790..d65cdb3d08fd745bd4996d0e45259077ea8eb000
@@@ -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 ':' <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.
  
@@@ -997,10 -996,9 +997,10 @@@ Output uses the same format as `git cat
        <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.
@@@ -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
  ------------------