core.fsync: documentation and user-friendly aggregate options
This commit adds aggregate options for the core.fsync setting that are more user-friendly. These options are specified in terms of 'levels of safety', indicating which Git operations are considered to be sync points for durability. The new documentation is also included here in its entirety for ease of review. Signed-off-by: Neeraj Singh <neerajsi@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Neeraj Singh committed
Mar 15, 2022 at 12:12 UTC
b9f5d0358d2e882d47f496c1a5589f6cebc25578
3 files changed
+65
-3
Documentation/config/core.txt
+40
@@ -547,6 +547,46 @@ core.whitespace::
547
is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent`
548
errors. The default tab width is 8. Allowed values are 1 to 63.
549
550
+core.fsync::
551
+ A comma-separated list of components of the repository that
552
+ should be hardened via the core.fsyncMethod when created or
553
+ modified. You can disable hardening of any component by
554
+ prefixing it with a '-'. Items that are not hardened may be
555
+ lost in the event of an unclean system shutdown. Unless you
556
+ have special requirements, it is recommended that you leave
557
+ this option empty or pick one of `committed`, `added`,
558
+ or `all`.
559
++
560
+When this configuration is encountered, the set of components starts with
561
+the platform default value, disabled components are removed, and additional
562
+components are added. `none` resets the state so that the platform default
563
+is ignored.
564
++
565
+The empty string resets the fsync configuration to the platform
566
+default. The default on most platforms is equivalent to
567
+`core.fsync=committed,-loose-object`, which has good performance,
568
+but risks losing recent work in the event of an unclean system shutdown.
569
++
570
+* `none` clears the set of fsynced components.
571
+* `loose-object` hardens objects added to the repo in loose-object form.
572
+* `pack` hardens objects added to the repo in packfile form.
573
+* `pack-metadata` hardens packfile bitmaps and indexes.
574
+* `commit-graph` hardens the commit graph file.
575
+* `index` hardens the index when it is modified.
576
+* `objects` is an aggregate option that is equivalent to
577
+ `loose-object,pack`.
578
+* `derived-metadata` is an aggregate option that is equivalent to
579
+ `pack-metadata,commit-graph`.
580
+* `committed` is an aggregate option that is currently equivalent to
581
+ `objects`. This mode sacrifices some performance to ensure that work
582
+ that is committed to the repository with `git commit` or similar commands
583
+ is hardened.
584
+* `added` is an aggregate option that is currently equivalent to
585
+ `committed,index`. This mode sacrifices additional performance to
586
+ ensure that the results of commands like `git add` and similar operations
587
+ are hardened.
588
+* `all` is an aggregate option that syncs all individual components above.
589
+
590
core.fsyncMethod::
591
A value indicating the strategy Git will use to harden repository data
592
using fsync and related primitives.
cache.h
+20
-3
@@ -1007,9 +1007,26 @@ enum fsync_component {
1007
FSYNC_COMPONENT_INDEX = 1 << 4,
1008
};
1009
1010
-#define FSYNC_COMPONENTS_DEFAULT (FSYNC_COMPONENT_PACK | \
1011
- FSYNC_COMPONENT_PACK_METADATA | \
1012
- FSYNC_COMPONENT_COMMIT_GRAPH)
1010
+#define FSYNC_COMPONENTS_OBJECTS (FSYNC_COMPONENT_LOOSE_OBJECT | \
1011
+ FSYNC_COMPONENT_PACK)
1012
+
1013
+#define FSYNC_COMPONENTS_DERIVED_METADATA (FSYNC_COMPONENT_PACK_METADATA | \
1014
+ FSYNC_COMPONENT_COMMIT_GRAPH)
1015
+
1016
+#define FSYNC_COMPONENTS_DEFAULT (FSYNC_COMPONENTS_OBJECTS | \
1017
+ FSYNC_COMPONENTS_DERIVED_METADATA | \
1018
+ ~FSYNC_COMPONENT_LOOSE_OBJECT)
1019
+
1020
+#define FSYNC_COMPONENTS_COMMITTED (FSYNC_COMPONENTS_OBJECTS)
1021
+
1022
+#define FSYNC_COMPONENTS_ADDED (FSYNC_COMPONENTS_COMMITTED | \
1023
+ FSYNC_COMPONENT_INDEX)
1024
+
1025
+#define FSYNC_COMPONENTS_ALL (FSYNC_COMPONENT_LOOSE_OBJECT | \
1026
+ FSYNC_COMPONENT_PACK | \
1027
+ FSYNC_COMPONENT_PACK_METADATA | \
1028
+ FSYNC_COMPONENT_COMMIT_GRAPH | \
1029
+ FSYNC_COMPONENT_INDEX)
1030
1031
/*
1032
* A bitmask indicating which components of the repo should be fsynced.
config.c
+5
@@ -1332,6 +1332,11 @@ static const struct fsync_component_name {
1332
{ "pack-metadata", FSYNC_COMPONENT_PACK_METADATA },
1333
{ "commit-graph", FSYNC_COMPONENT_COMMIT_GRAPH },
1334
{ "index", FSYNC_COMPONENT_INDEX },
1335
+ { "objects", FSYNC_COMPONENTS_OBJECTS },
1336
+ { "derived-metadata", FSYNC_COMPONENTS_DERIVED_METADATA },
1337
+ { "committed", FSYNC_COMPONENTS_COMMITTED },
1338
+ { "added", FSYNC_COMPONENTS_ADDED },
1339
+ { "all", FSYNC_COMPONENTS_ALL },
1340
};
1341
1342
static enum fsync_component parse_fsync_components(const char *var, const char *string)