doc hash-function-transition: fix asciidoc output
Asciidoc requires lists to start with an empty line and uses different characters for indentation levels ("-", "*", "**", ...). For special symbols like a dash "--" has to be used and there is no double arrow "<->", so a left and right arrow "<-->" has to be combined for that. Lastly for verbatim output a newline followed by an indentation has to be used. Fix asciidoc output for lists, special characters and verbatim text while retaining the readabilty of the original text file. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Ackermann committed
Feb 5, 2021 at 18:22 UTC
de82095a959df0af307e053df7672c342f2a5551
1 file changed
+45
-34
Documentation/technical/hash-function-transition.txt
+45
-34
@@ -94,7 +94,7 @@ Overview
94
--------
95
We introduce a new repository format extension. Repositories with this
96
extension enabled use SHA-256 instead of SHA-1 to name their objects.
97
-This affects both object names and object content --- both the names
97
+This affects both object names and object content -- both the names
98
of objects and all references to other objects within an object are
99
switched to the new hash function.
100
@@ -191,21 +191,21 @@ hash functions. They have the following format (all integers are in
191
network byte order):
192
193
- A header appears at the beginning and consists of the following:
194
- - The 4-byte pack index signature: '\377t0c'
195
- - 4-byte version number: 3
196
- - 4-byte length of the header section, including the signature and
194
+ * The 4-byte pack index signature: '\377t0c'
195
+ * 4-byte version number: 3
196
+ * 4-byte length of the header section, including the signature and
197
version number
198
- - 4-byte number of objects contained in the pack
199
- - 4-byte number of object formats in this pack index: 2
200
- - For each object format:
201
- - 4-byte format identifier (e.g., 'sha1' for SHA-1)
202
- - 4-byte length in bytes of shortened object names. This is the
198
+ * 4-byte number of objects contained in the pack
199
+ * 4-byte number of object formats in this pack index: 2
200
+ * For each object format:
201
+ ** 4-byte format identifier (e.g., 'sha1' for SHA-1)
202
+ ** 4-byte length in bytes of shortened object names. This is the
203
shortest possible length needed to make names in the shortened
204
object name table unambiguous.
205
- - 4-byte integer, recording where tables relating to this format
205
+ ** 4-byte integer, recording where tables relating to this format
206
are stored in this index file, as an offset from the beginning.
207
- - 4-byte offset to the trailer from the beginning of this file.
208
- - Zero or more additional key/value pairs (4-byte key, 4-byte
207
+ * 4-byte offset to the trailer from the beginning of this file.
208
+ * Zero or more additional key/value pairs (4-byte key, 4-byte
209
value). Only one key is supported: 'PSRC'. See the "Loose objects
210
and unreachable objects" section for supported values and how this
211
is used. All other keys are reserved. Readers must ignore
@@ -213,37 +213,36 @@ network byte order):
213
- Zero or more NUL bytes. This can optionally be used to improve the
214
alignment of the full object name table below.
215
- Tables for the first object format:
216
- - A sorted table of shortened object names. These are prefixes of
216
+ * A sorted table of shortened object names. These are prefixes of
217
the names of all objects in this pack file, packed together
218
without offset values to reduce the cache footprint of the binary
219
search for a specific object name.
220
221
- - A table of full object names in pack order. This allows resolving
221
+ * A table of full object names in pack order. This allows resolving
222
a reference to "the nth object in the pack file" (from a
223
reachability bitmap or from the next table of another object
224
format) to its object name.
225
226
- - A table of 4-byte values mapping object name order to pack order.
226
+ * A table of 4-byte values mapping object name order to pack order.
227
For an object in the table of sorted shortened object names, the
228
value at the corresponding index in this table is the index in the
229
previous table for that same object.
230
-
230
This can be used to look up the object in reachability bitmaps or
231
to look up its name in another object format.
232
234
- - A table of 4-byte CRC32 values of the packed object data, in the
233
+ * A table of 4-byte CRC32 values of the packed object data, in the
234
order that the objects appear in the pack file. This is to allow
235
compressed data to be copied directly from pack to pack during
236
repacking without undetected data corruption.
237
239
- - A table of 4-byte offset values. For an object in the table of
238
+ * A table of 4-byte offset values. For an object in the table of
239
sorted shortened object names, the value at the corresponding
240
index in this table indicates where that object can be found in
241
the pack file. These are usually 31-bit pack file offsets, but
242
large offsets are encoded as an index into the next table with the
243
most significant bit set.
244
246
- - A table of 8-byte offset entries (empty for pack files less than
245
+ * A table of 8-byte offset entries (empty for pack files less than
246
2 GiB). Pack files are organized with heavily used objects toward
247
the front, so most object references should not need to refer to
248
this table.
@@ -252,10 +251,10 @@ network byte order):
251
up to and not including the table of CRC32 values.
252
- Zero or more NUL bytes.
253
- The trailer consists of the following:
255
- - A copy of the 20-byte SHA-256 checksum at the end of the
254
+ * A copy of the 20-byte SHA-256 checksum at the end of the
255
corresponding packfile.
256
258
- - 20-byte SHA-256 checksum of all of the above.
257
+ * 20-byte SHA-256 checksum of all of the above.
258
259
Loose object index
260
~~~~~~~~~~~~~~~~~~
@@ -351,7 +350,7 @@ the following steps:
350
3. convert to sha256: open a new (sha256) packfile. Read the topologically
351
sorted list just generated. For each object, inflate its
352
sha1-content, convert to sha256-content, and write it to the sha256
354
- pack. Record the new sha1<->sha256 mapping entry for use in the idx.
353
+ pack. Record the new sha1<-->sha256 mapping entry for use in the idx.
354
4. sort: reorder entries in the new pack to match the order of objects
355
in the pack the server generated and include blobs. Write a sha256 idx
356
file
@@ -391,6 +390,7 @@ existing "gpgsig" field. Its signed payload is the sha256-content of the
390
commit object with any "gpgsig" and "gpgsig-sha256" fields removed.
391
392
This means commits can be signed
393
+
394
1. using SHA-1 only, as in existing signed commit objects
395
2. using both SHA-1 and SHA-256, by using both gpgsig-sha256 and gpgsig
396
fields.
@@ -408,6 +408,7 @@ sha256-content of the tag with its gpgsig-sha256 field and "-----BEGIN PGP
408
SIGNATURE-----" delimited in-body signature removed.
409
410
This means tags can be signed
411
+
412
1. using SHA-1 only, as in existing signed tag objects
413
2. using both SHA-1 and SHA-256, by using gpgsig-sha256 and an in-body
414
signature.
@@ -598,7 +599,7 @@ The user can also explicitly specify which format to use for a
599
particular revision specifier and for output, overriding the mode. For
600
example:
601
601
-git --output-format=sha1 log abac87a^{sha1}..f787cac^{sha256}
602
+ git --output-format=sha1 log abac87a^{sha1}..f787cac^{sha256}
603
604
Choice of Hash
605
--------------
@@ -636,6 +637,7 @@ We choose SHA-256.
637
Transition plan
638
---------------
639
Some initial steps can be implemented independently of one another:
640
+
641
- adding a hash function API (vtable)
642
- teaching fsck to tolerate the gpgsig-sha256 field
643
- excluding gpgsig-* from the fields copied by "git commit --amend"
@@ -647,9 +649,9 @@ Some initial steps can be implemented independently of one another:
649
- introducing index v3
650
- adding support for the PSRC field and safer object pruning
651
650
-
652
The first user-visible change is the introduction of the objectFormat
653
extension (without compatObjectFormat). This requires:
654
+
655
- teaching fsck about this mode of operation
656
- using the hash function API (vtable) when computing object names
657
- signing objects and verifying signatures
@@ -657,6 +659,7 @@ extension (without compatObjectFormat). This requires:
659
repository
660
661
Next comes introduction of compatObjectFormat:
662
+
663
- implementing the loose-object-idx
664
- translating object names between object formats
665
- translating object content between object formats
@@ -669,6 +672,7 @@ Next comes introduction of compatObjectFormat:
672
"Object names on the command line" above)
673
674
The next step is supporting fetches and pushes to SHA-1 repositories:
675
+
676
- allow pushes to a repository using the compat format
677
- generate a topologically sorted list of the SHA-1 names of fetched
678
objects
@@ -734,6 +738,7 @@ Using hash functions in parallel
738
Objects newly created would be addressed by the new hash, but inside
739
such an object (e.g. commit) it is still possible to address objects
740
using the old hash function.
741
+
742
* You cannot trust its history (needed for bisectability) in the
743
future without further work
744
* Maintenance burden as the number of supported hash functions grows
@@ -749,6 +754,7 @@ sha1-content based signatures.
754
755
In other words, a single signature was used to attest to the object
756
content using both hash functions. This had some advantages:
757
+
758
* Using one signature instead of two speeds up the signing process.
759
* Having one signed payload with both hashes allows the signer to
760
attest to the sha1-name and sha256-name referring to the same object.
@@ -756,6 +762,7 @@ content using both hash functions. This had some advantages:
762
to be detected quickly using current versions of git.
763
764
However, it also came with disadvantages:
765
+
766
* Verifying a signed object requires access to the sha1-names of all
767
objects it references, even after the transition is complete and
768
translation table is no longer needed for anything else. To support
@@ -782,16 +789,17 @@ Document History
789
bmwill@google.com, jonathantanmy@google.com, jrnieder@gmail.com,
790
sbeller@google.com
791
785
-Initial version sent to
786
-http://lore.kernel.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com
792
+* Initial version sent to http://lore.kernel.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com
793
794
2017-03-03 jrnieder@gmail.com
795
Incorporated suggestions from jonathantanmy and sbeller:
796
+
797
* describe purpose of signed objects with each hash type
798
* redefine signed object verification using object content under the
799
first hash function
800
801
2017-03-06 jrnieder@gmail.com
802
+
803
* Use SHA3-256 instead of SHA2 (thanks, Linus and brian m. carlson).[1][2]
804
* Make sha3-based signatures a separate field, avoiding the need for
805
"hash" and "nohash" fields (thanks to peff[3]).
@@ -805,6 +813,7 @@ Incorporated suggestions from jonathantanmy and sbeller:
813
especially Junio).
814
815
2017-09-27 jrnieder@gmail.com, sbeller@google.com
816
+
817
* use placeholder NewHash instead of SHA3-256
818
* describe criteria for picking a hash function.
819
* include a transition plan (thanks especially to Brandon Williams
@@ -816,12 +825,14 @@ Incorporated suggestions from jonathantanmy and sbeller:
825
826
Later history:
827
819
- See the history of this file in git.git for the history of subsequent
820
- edits. This document history is no longer being maintained as it
821
- would now be superfluous to the commit log
828
+* See the history of this file in git.git for the history of subsequent
829
+ edits. This document history is no longer being maintained as it
830
+ would now be superfluous to the commit log
831
+
832
+References:
833
823
-[1] http://lore.kernel.org/git/CA+55aFzJtejiCjV0e43+9oR3QuJK2PiFiLQemytoLpyJWe6P9w@mail.gmail.com/
824
-[2] http://lore.kernel.org/git/CA+55aFz+gkAsDZ24zmePQuEs1XPS9BP_s8O7Q4wQ7LV7X5-oDA@mail.gmail.com/
825
-[3] http://lore.kernel.org/git/20170306084353.nrns455dvkdsfgo5@sigill.intra.peff.net/
826
-[4] http://lore.kernel.org/git/20170304224936.rqqtkdvfjgyezsht@genre.crustytoothpaste.net
827
-[5] https://lore.kernel.org/git/CAJo=hJtoX9=AyLHHpUJS7fueV9ciZ_MNpnEPHUz8Whui6g9F0A@mail.gmail.com/
834
+ [1] http://lore.kernel.org/git/CA+55aFzJtejiCjV0e43+9oR3QuJK2PiFiLQemytoLpyJWe6P9w@mail.gmail.com/
835
+ [2] http://lore.kernel.org/git/CA+55aFz+gkAsDZ24zmePQuEs1XPS9BP_s8O7Q4wQ7LV7X5-oDA@mail.gmail.com/
836
+ [3] http://lore.kernel.org/git/20170306084353.nrns455dvkdsfgo5@sigill.intra.peff.net/
837
+ [4] http://lore.kernel.org/git/20170304224936.rqqtkdvfjgyezsht@genre.crustytoothpaste.net
838
+ [5] https://lore.kernel.org/git/CAJo=hJtoX9=AyLHHpUJS7fueV9ciZ_MNpnEPHUz8Whui6g9F0A@mail.gmail.com/