Merge branch 'ph/describe-match'
[gitweb.git] / Documentation / git-gc.txt
index b9d5660eacee03bde2360b97b80f3378972fe678..4b2dfefa6ac6088322f7928836e7bb59f27a51e2 100644 (file)
@@ -15,11 +15,12 @@ DESCRIPTION
 Runs a number of housekeeping tasks within the current repository,
 such as compressing file revisions (to reduce disk space and increase
 performance) and removing unreachable objects which may have been
-created from prior invocations of gitlink:git-add[1].
+created from prior invocations of linkgit:git-add[1].
 
 Users are encouraged to run this task on a regular basis within
 each repository to maintain good disk space utilization and good
-operating performance.
+operating performance. Some git commands may automatically run
+`git-gc`; see the `--auto` flag below for details.
 
 OPTIONS
 -------
@@ -44,18 +45,23 @@ OPTIONS
        few hundred changesets or so.
 
 --auto::
-       With this option, `git gc` checks if there are too many
-       loose objects in the repository and runs
-       gitlink:git-repack[1] with `-d -l` option to pack them.
-       The threshold for loose objects is set with `gc.auto` configuration
-       variable, and can be disabled by setting it to 0.  Some
-       Porcelain commands use this after they perform operation
-       that could create many loose objects automatically.
-       Additionally, when there are too many packs are present,
-       they are consolidated into one larger pack by running
-       the `git-repack` command with `-A` option.  The
-       threshold for number of packs is set with
-       `gc.autopacklimit` configuration variable.
+       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)
+are consolidated into a single pack by using the `-A` option of
+`git-repack`. Setting `gc.autopacklimit` to 0 disables
+automatic consolidation of packs.
 
 Configuration
 -------------
@@ -84,23 +90,23 @@ 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`.  Without the configuration, `git-pack-refs`
-is not run in bare repositories by default, to allow older dumb-transport
-clients fetch from the repository,  but this will change in the future.
+`git gc` runs `git-pack-refs`. This can be set to "nobare" 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.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 gitlink:git-repack[1] for
+the documentation for the --window' option in linkgit:git-repack[1] for
 more details.  This defaults to 10.
 
 See Also
 --------
-gitlink:git-prune[1]
-gitlink:git-reflog[1]
-gitlink:git-repack[1]
-gitlink:git-rerere[1]
+linkgit:git-prune[1]
+linkgit:git-reflog[1]
+linkgit:git-repack[1]
+linkgit:git-rerere[1]
 
 Author
 ------
@@ -108,4 +114,4 @@ Written by Shawn O. Pearce <spearce@spearce.org>
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite