From: Meet Soni <meetsoni3017@gmail•com>
To: git@vger•kernel.org
Cc: ps@pks•im, shejialuo@gmail•com, Meet Soni <meetsoni3017@gmail•com>
Subject: [GSoC][PATCH 2/5] doc: factor out common option
Date: Tue, 26 Aug 2025 13:06:42 +0530 [thread overview]
Message-ID: <20250826073645.1074397-3-meetsoni3017@gmail.com> (raw)
In-Reply-To: <20250826073645.1074397-1-meetsoni3017@gmail.com>
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>
---
Documentation/git-pack-refs.adoc | 54 +---------------------------
Documentation/pack-refs-options.adoc | 52 +++++++++++++++++++++++++++
2 files changed, 53 insertions(+), 53 deletions(-)
create mode 100644 Documentation/pack-refs-options.adoc
diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc
index 42b90051e6..dac63e5e12 100644
--- a/Documentation/git-pack-refs.adoc
+++ b/Documentation/git-pack-refs.adoc
@@ -45,59 +45,7 @@ unpacked.
OPTIONS
-------
---all::
-
-The command by default packs all tags and refs that are already
-packed, and leaves other refs
-alone. This is because branches are expected to be actively
-developed and packing their tips does not help performance.
-This option causes all refs to be packed as well, with the exception
-of hidden refs, broken refs, and symbolic refs. Useful for a repository
-with many branches of historical interests.
-
---no-prune::
-
-The command usually removes loose refs under `$GIT_DIR/refs`
-hierarchy after packing them. This option tells it not to.
-
---auto::
-
-Pack refs as needed depending on the current state of the ref database. The
-behavior depends on the ref format used by the repository and may change in the
-future.
-+
- - "files": Loose references are packed into the `packed-refs` file
- based on the ratio of loose references to the size of the
- `packed-refs` file. The bigger the `packed-refs` file, the more loose
- references need to exist before we repack.
-+
- - "reftable": Tables are compacted such that they form a geometric
- sequence. For two tables N and N+1, where N+1 is newer, this
- maintains the property that N is at least twice as big as N+1. Only
- tables that violate this property are compacted.
-
---include <pattern>::
-
-Pack refs based on a `glob(7)` pattern. Repetitions of this option
-accumulate inclusion patterns. If a ref is both included in `--include` and
-`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all
-tags from being included by default. Symbolic refs and broken refs will never
-be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
-and reset the list of patterns.
-
---exclude <pattern>::
-
-Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
-accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
-patterns. If a ref is already packed, including it with `--exclude` will not
-unpack it.
-+
-When used with `--all`, pack only loose refs which do not match any of
-the provided `--exclude` patterns.
-+
-When used with `--include`, refs provided to `--include`, minus refs that are
-provided to `--exclude` will be packed.
-
+include::pack-refs-options.adoc[]
BUGS
----
diff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc
new file mode 100644
index 0000000000..0b11282941
--- /dev/null
+++ b/Documentation/pack-refs-options.adoc
@@ -0,0 +1,52 @@
+--all::
+
+The command by default packs all tags and refs that are already
+packed, and leaves other refs
+alone. This is because branches are expected to be actively
+developed and packing their tips does not help performance.
+This option causes all refs to be packed as well, with the exception
+of hidden refs, broken refs, and symbolic refs. Useful for a repository
+with many branches of historical interests.
+
+--no-prune::
+
+The command usually removes loose refs under `$GIT_DIR/refs`
+hierarchy after packing them. This option tells it not to.
+
+--auto::
+
+Pack refs as needed depending on the current state of the ref database. The
+behavior depends on the ref format used by the repository and may change in the
+future.
++
+ - "files": Loose references are packed into the `packed-refs` file
+ based on the ratio of loose references to the size of the
+ `packed-refs` file. The bigger the `packed-refs` file, the more loose
+ references need to exist before we repack.
++
+ - "reftable": Tables are compacted such that they form a geometric
+ sequence. For two tables N and N+1, where N+1 is newer, this
+ maintains the property that N is at least twice as big as N+1. Only
+ tables that violate this property are compacted.
+
+--include <pattern>::
+
+Pack refs based on a `glob(7)` pattern. Repetitions of this option
+accumulate inclusion patterns. If a ref is both included in `--include` and
+`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all
+tags from being included by default. Symbolic refs and broken refs will never
+be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
+and reset the list of patterns.
+
+--exclude <pattern>::
+
+Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
+accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
+patterns. If a ref is already packed, including it with `--exclude` will not
+unpack it.
++
+When used with `--all`, pack only loose refs which do not match any of
+the provided `--exclude` patterns.
++
+When used with `--include`, refs provided to `--include`, minus refs that are
+provided to `--exclude` will be packed.
--
2.34.1
next prev parent reply other threads:[~2025-08-26 7:36 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-26 7:36 [GSoC][PATCH 0/5] Add refs optimize subcommand Meet Soni
2025-08-26 7:36 ` [GSoC][PATCH 1/5] builtin/pack-refs: factor out core logic into a helper Meet Soni
2025-09-02 10:18 ` Patrick Steinhardt
2025-09-03 3:56 ` Meet Soni
2025-09-03 4:37 ` Patrick Steinhardt
2025-09-03 5:25 ` Junio C Hamano
2025-09-03 6:00 ` Patrick Steinhardt
2025-09-03 18:20 ` Junio C Hamano
2025-08-26 7:36 ` Meet Soni [this message]
2025-08-26 7:36 ` [GSoC][PATCH 3/5] builtin/refs: add optimize subcommand Meet Soni
2025-09-02 10:18 ` Patrick Steinhardt
2025-08-26 7:36 ` [GSoC][PATCH 4/5] t0601: refactor tests to be shareable Meet Soni
2025-08-26 7:36 ` [GSoC][PATCH 5/5] t: add test for git refs optimize subcommand Meet Soni
2025-08-26 15:18 ` shejialuo
2025-08-31 6:20 ` Meet Soni
2025-09-02 10:18 ` Patrick Steinhardt
2025-09-03 3:58 ` Meet Soni
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250826073645.1074397-3-meetsoni3017@gmail.com \
--to=meetsoni3017@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=ps@pks$(echo .)im \
--cc=shejialuo@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox