doc/reftable: document how to handle windows
On Windows we can't delete or overwrite files opened by other processes. Here we sketch how to handle this situation. We propose to use a random element in the filename. It's possible to design an alternate solution based on counters, but that would assign semantics to the filenames that complicates implementation. Signed-off-by: Han-Wen Nienhuys <hanwen@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Han-Wen Nienhuys committed
Feb 23, 2021 at 16:57 UTC
00f68732e5371d6cc5bb17fbd2fa99c8786571da
1 file changed
+26
-16
Documentation/technical/reftable.txt
+26
-16
@@ -872,17 +872,11 @@ A repository must set its `$GIT_DIR/config` to configure reftable:
872
Layout
873
^^^^^^
874
875
-A collection of reftable files are stored in the `$GIT_DIR/reftable/`
876
-directory:
877
-
878
-....
879
-00000001-00000001.log
880
-00000002-00000002.ref
881
-00000003-00000003.ref
882
-....
883
-
884
-where reftable files are named by a unique name such as produced by the
885
-function `${min_update_index}-${max_update_index}.ref`.
875
+A collection of reftable files are stored in the `$GIT_DIR/reftable/` directory.
876
+Their names should have a random element, such that each filename is globally
877
+unique; this helps avoid spurious failures on Windows, where open files cannot
878
+be removed or overwritten. It suggested to use
879
+`${min_update_index}-${max_update_index}-${random}.ref` as a naming convention.
880
881
Log-only files use the `.log` extension, while ref-only and mixed ref
882
and log files use `.ref`. extension.
@@ -893,9 +887,9 @@ current files, one per line, in order, from oldest (base) to newest
887
888
....
889
$ cat .git/reftable/tables.list
896
-00000001-00000001.log
897
-00000002-00000002.ref
898
-00000003-00000003.ref
890
+00000001-00000001-RANDOM1.log
891
+00000002-00000002-RANDOM2.ref
892
+00000003-00000003-RANDOM3.ref
893
....
894
895
Readers must read `$GIT_DIR/reftable/tables.list` to determine which
@@ -940,7 +934,7 @@ new reftable and atomically appending it to the stack:
934
3. Select `update_index` to be most recent file's
935
`max_update_index + 1`.
936
4. Prepare temp reftable `tmp_XXXXXX`, including log entries.
943
-5. Rename `tmp_XXXXXX` to `${update_index}-${update_index}.ref`.
937
+5. Rename `tmp_XXXXXX` to `${update_index}-${update_index}-${random}.ref`.
938
6. Copy `tables.list` to `tables.list.lock`, appending file from (5).
939
7. Rename `tables.list.lock` to `tables.list`.
940
@@ -993,7 +987,7 @@ prevents other processes from trying to compact these files.
987
should always be the case, assuming that other processes are adhering to
988
the locking protocol.
989
7. Rename `${min_update_index}-${max_update_index}_XXXXXX` to
996
-`${min_update_index}-${max_update_index}.ref`.
990
+`${min_update_index}-${max_update_index}-${random}.ref`.
991
8. Write the new stack to `tables.list.lock`, replacing `B` and `C`
992
with the file from (4).
993
9. Rename `tables.list.lock` to `tables.list`.
@@ -1005,6 +999,22 @@ This strategy permits compactions to proceed independently of updates.
999
Each reftable (compacted or not) is uniquely identified by its name, so
1000
open reftables can be cached by their name.
1001
1002
+Windows
1003
+^^^^^^^
1004
+
1005
+On windows, and other systems that do not allow deleting or renaming to open
1006
+files, compaction may succeed, but other readers may prevent obsolete tables
1007
+from being deleted.
1008
+
1009
+On these platforms, the following strategy can be followed: on closing a
1010
+reftable stack, reload `tables.list`, and delete any tables no longer mentioned
1011
+in `tables.list`.
1012
+
1013
+Irregular program exit may still leave about unused files. In this case, a
1014
+cleanup operation can read `tables.list`, note its modification timestamp, and
1015
+delete any unreferenced `*.ref` files that are older.
1016
+
1017
+
1018
Alternatives considered
1019
~~~~~~~~~~~~~~~~~~~~~~~
1020