[PATCH 1/2] doc: update the documentation of pack-objects and repack

[Damien Robert <damien.olivier.robert@gmail.com>]

For pack-objects:

  - add a documentation for --reflog, --indexed-objects and
  --write-bitmap-index.

  - clarify --keep-unreachable. Indeed the current description is out of
  date:

      Objects unreachable from the refs in packs named with
      --unpacked= option are added to the resulting pack, in
      addition to the reachable objects that are not in packs marked
      with *.keep files. This implies `--revs`.

  For example --unpacked= option is now a boolean, and objects in .keep
  packs are packed except if --honor-pack-keep is given.
  What --keep-unreachable currently does is simply to add all packed
  objects to the object list. In particular this includes unreachable
  objects (both unreachable from the passed revs or even from all revs).

  - rework the grammar for --pack-loose-unreachable

  - --unpack-unreachable can also accept a time

For repack:

- Unify the notation to `git pack-objects` and not `git-pack-objects`.

- Specify all options that are passed to `git pack-objects`

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-pack-objects.txt | 27 +++++++++----
 Documentation/git-repack.txt       | 61 +++++++++++++++++++-----------
 2 files changed, 58 insertions(+), 30 deletions(-)

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index fecdf2600c..7f4923ddea 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -80,6 +80,14 @@ base-name::
 	as if all refs under `refs/` are specified to be
 	included.
 
+--reflog::
+	This implies `--revs`.
+	Include objects referred by reflog entries.
+
+--indexed-objects::
+	This implies `--revs`.
+	Include objects referred to by the index
+
 --include-tag::
 	Include unasked-for annotated tags if the object they
 	reference was included in the resulting packfile.  This
@@ -123,6 +131,11 @@ depth is 4095.
 	The default is unlimited, unless the config variable
 	`pack.packSizeLimit` is set.
 
+--write-bitmap-index::
+	Write a reachability bitmap index as part of the pack. This
+	only makes sense when used with `--all` and the pack is not
+	outputted to stdout.
+
 --honor-pack-keep::
 	This flag causes an object already in a local pack that
 	has a .keep file to be ignored, even if it would have
@@ -286,17 +299,17 @@ Unexpected missing object will raise an error.
 	promisor remote [with .promisor].)  This is used with partial clone.
 
 --keep-unreachable::
-	Objects unreachable from the refs in packs named with
-	--unpacked= option are added to the resulting pack, in
-	addition to the reachable objects that are not in packs marked
-	with *.keep files. This implies `--revs`.
+	Unreachable packed objects are added to the resulting pack.
+	This implies `--revs`.
 
 --pack-loose-unreachable::
-	Pack unreachable loose objects (and their loose counterparts
-	removed). This implies `--revs`.
+	Pack unreachable loose objects (and remove their loose counterparts).
+	This implies `--revs`.
 
---unpack-unreachable::
+--unpack-unreachable=<when>::
 	Keep unreachable objects in loose form. This implies `--revs`.
+	If `<when>` is specified, do not bother loosening any objects older
+	than `<when>`.
 
 --delta-islands::
 	Restrict delta matches based on "islands". See DELTA ISLANDS
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 92f146d27d..267edce2d6 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -68,11 +68,11 @@ to the new separate pack will be written.
 	linkgit:git-pack-objects[1].
 
 -f::
-	Pass the `--no-reuse-delta` option to `git-pack-objects`, see
+	Pass the `--no-reuse-delta` option to `git pack-objects`, see
 	linkgit:git-pack-objects[1].
 
 -F::
-	Pass the `--no-reuse-object` option to `git-pack-objects`, see
+	Pass the `--no-reuse-object` option to `git pack-objects`, see
 	linkgit:git-pack-objects[1].
 
 -q::
@@ -88,13 +88,14 @@ to the new separate pack will be written.
 
 --window=<n>::
 --depth=<n>::
-	These two options affect how the objects contained in the pack are
-	stored using delta compression. The objects are first internally
-	sorted by type, size and optionally names and compared against the
-	other objects within `--window` to see if using delta compression saves
-	space. `--depth` limits the maximum delta depth; making it too deep
-	affects the performance on the unpacker side, because delta data needs
-	to be applied that many times to get to the necessary object.
+	These two options are passed to `git pack-objects` and affect how
+	the objects contained in the pack are stored using delta
+	compression. The objects are first internally sorted by type, size
+	and optionally names and compared against the other objects within
+	`--window` to see if using delta compression saves space. `--depth`
+	limits the maximum delta depth; making it too deep affects the
+	performance on the unpacker side, because delta data needs to be
+	applied that many times to get to the necessary object.
 +
 The default value for --window is 10 and --depth is 50. The maximum
 depth is 4095.
@@ -103,13 +104,13 @@ depth is 4095.
 	This option is passed through to `git pack-objects`.
 
 --window-memory=<n>::
-	This option provides an additional limit on top of `--window`;
-	the window size will dynamically scale down so as to not take
-	up more than '<n>' bytes in memory.  This is useful in
-	repositories with a mix of large and small objects to not run
-	out of memory with a large window, but still be able to take
-	advantage of the large window for the smaller objects.  The
-	size can be suffixed with "k", "m", or "g".
+	This option is passed to `git pack-objects` and provides an
+	additional limit on top of `--window`; the window size will
+	dynamically scale down so as to not take up more than '<n>' bytes
+	in memory.  This is useful in repositories with a mix of large and
+	small objects to not run out of memory with a large window, but
+	still be able to take advantage of the large window for the smaller
+	objects.  The size can be suffixed with "k", "m", or "g".
 	`--window-memory=0` makes memory usage unlimited.  The default
 	is taken from the `pack.windowMemory` configuration variable.
 	Note that the actual memory usage will be the limit multiplied
@@ -122,6 +123,7 @@ depth is 4095.
 	prevents the creation of a bitmap index.
 	The default is unlimited, unless the config variable
 	`pack.packSizeLimit` is set.
+	This option is passed to `git pack-objects`.
 
 -b::
 --write-bitmap-index::
@@ -129,7 +131,8 @@ depth is 4095.
 	only makes sense when used with `-a` or `-A`, as the bitmaps
 	must be able to refer to all reachable objects. This option
 	overrides the setting of `repack.writeBitmaps`.  This option
-	has no effect if multiple packfiles are created.
+	has no effect if multiple packfiles are created, and is passed to
+	`git pack-objects`.
 
 --pack-kept-objects::
 	Include objects in `.keep` files when repacking.  Note that we
@@ -145,26 +148,38 @@ depth is 4095.
 	of having `.keep` file on the pack. `<pack-name>` is the
 	pack file name without leading directory (e.g. `pack-123.pack`).
 	The option could be specified multiple times to keep multiple
-	packs.
+	packs, and is passed to `git pack-objects`.
 
 --unpack-unreachable=<when>::
+	When used with `-ad`, this option is passed to `git pack-objects`.
 	When loosening unreachable objects, do not bother loosening any
 	objects older than `<when>`. This can be used to optimize out
 	the write of any objects that would be immediately pruned by
 	a follow-up `git prune`.
+	The `-A` option is synonymous with `-a --unpack-unreachable`.
 
 -k::
 --keep-unreachable::
-	When used with `-ad`, any unreachable objects from existing
-	packs will be appended to the end of the packfile instead of
-	being removed. In addition, any unreachable loose objects will
-	be packed (and their loose counterparts removed).
+	When used with `-ad`, '--keep-unreachable' and
+	'--pack-loose-unreachable' are passed to `git pack-objects`.
+	Any unreachable objects from existing packs will be appended to the
+	end of the packfile instead of being removed. In addition, any
+	unreachable loose objects will be packed (and their loose
+	counterparts removed).
 
 -i::
 --delta-islands::
-	Pass the `--delta-islands` option to `git-pack-objects`, see
+	Pass the `--delta-islands` option to `git pack-objects`, see
 	linkgit:git-pack-objects[1].
 
+Default options
+---------------
+
+The command passes the following options to `git pack-objects`:
+`--keep-true-parents`, `--no-empty`, `--all`, `--reflog`, `--indexed-objects`.
+It also add `--exclude-promisor-objects` if there exists a promisor remote,
+and `--honor-pack-keep` except if `--pack-kept-objects` is passed.
+
 Configuration
 -------------
 
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)