doc: pack-refs: factor out common options
In preparation for adding documentation for `git refs optimize`, factor out the common options from the `git-pack-refs` man page into a shareable file `pack-refs-options.adoc` and update `git-pack-refs.adoc` to use an `include::` macro. This change is a pure refactoring and results in no change to the final rendered documentation for `pack-refs`. Mentored-by: Patrick Steinhardt <ps@pks.im> Mentored-by: shejialuo <shejialuo@gmail.com> Signed-off-by: Meet Soni <meetsoni3017@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Meet Soni committed
Sep 19, 2025 at 13:56 UTC
93efe34f5a9a6ef705e6f55d46852717ce242340
2 files changed
+53
-52
Documentation/git-pack-refs.adoc
+1
-52
@@ -45,58 +45,7 @@ unpacked.
45
OPTIONS
46
-------
47
48
---all::
49
-
50
-The command by default packs all tags and refs that are already
51
-packed, and leaves other refs
52
-alone. This is because branches are expected to be actively
53
-developed and packing their tips does not help performance.
54
-This option causes all refs to be packed as well, with the exception
55
-of hidden refs, broken refs, and symbolic refs. Useful for a repository
56
-with many branches of historical interests.
57
-
58
---no-prune::
59
-
60
-The command usually removes loose refs under `$GIT_DIR/refs`
61
-hierarchy after packing them. This option tells it not to.
62
-
63
---auto::
64
-
65
-Pack refs as needed depending on the current state of the ref database. The
66
-behavior depends on the ref format used by the repository and may change in the
67
-future.
68
-+
69
- - "files": Loose references are packed into the `packed-refs` file
70
- based on the ratio of loose references to the size of the
71
- `packed-refs` file. The bigger the `packed-refs` file, the more loose
72
- references need to exist before we repack.
73
-+
74
- - "reftable": Tables are compacted such that they form a geometric
75
- sequence. For two tables N and N+1, where N+1 is newer, this
76
- maintains the property that N is at least twice as big as N+1. Only
77
- tables that violate this property are compacted.
78
-
79
---include <pattern>::
80
-
81
-Pack refs based on a `glob(7)` pattern. Repetitions of this option
82
-accumulate inclusion patterns. If a ref is both included in `--include` and
83
-`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all
84
-tags from being included by default. Symbolic refs and broken refs will never
85
-be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
86
-and reset the list of patterns.
87
-
88
---exclude <pattern>::
89
-
90
-Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
91
-accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
92
-patterns. If a ref is already packed, including it with `--exclude` will not
93
-unpack it.
94
-+
95
-When used with `--all`, pack only loose refs which do not match any of
96
-the provided `--exclude` patterns.
97
-+
98
-When used with `--include`, refs provided to `--include`, minus refs that are
99
-provided to `--exclude` will be packed.
48
+include::pack-refs-options.adoc[]
49
50
51
BUGS
Documentation/pack-refs-options.adoc
new
+52
@@ -0,0 +1,52 @@
1
+--all::
2
+
3
+The command by default packs all tags and refs that are already
4
+packed, and leaves other refs
5
+alone. This is because branches are expected to be actively
6
+developed and packing their tips does not help performance.
7
+This option causes all refs to be packed as well, with the exception
8
+of hidden refs, broken refs, and symbolic refs. Useful for a repository
9
+with many branches of historical interests.
10
+
11
+--no-prune::
12
+
13
+The command usually removes loose refs under `$GIT_DIR/refs`
14
+hierarchy after packing them. This option tells it not to.
15
+
16
+--auto::
17
+
18
+Pack refs as needed depending on the current state of the ref database. The
19
+behavior depends on the ref format used by the repository and may change in the
20
+future.
21
++
22
+ - "files": Loose references are packed into the `packed-refs` file
23
+ based on the ratio of loose references to the size of the
24
+ `packed-refs` file. The bigger the `packed-refs` file, the more loose
25
+ references need to exist before we repack.
26
++
27
+ - "reftable": Tables are compacted such that they form a geometric
28
+ sequence. For two tables N and N+1, where N+1 is newer, this
29
+ maintains the property that N is at least twice as big as N+1. Only
30
+ tables that violate this property are compacted.
31
+
32
+--include <pattern>::
33
+
34
+Pack refs based on a `glob(7)` pattern. Repetitions of this option
35
+accumulate inclusion patterns. If a ref is both included in `--include` and
36
+`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all
37
+tags from being included by default. Symbolic refs and broken refs will never
38
+be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
39
+and reset the list of patterns.
40
+
41
+--exclude <pattern>::
42
+
43
+Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
44
+accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
45
+patterns. If a ref is already packed, including it with `--exclude` will not
46
+unpack it.
47
++
48
+When used with `--all`, pack only loose refs which do not match any of
49
+the provided `--exclude` patterns.
50
++
51
+When used with `--include`, refs provided to `--include`, minus refs that are
52
+provided to `--exclude` will be packed.