ff233d8dda
After eff45daab8 ("repository: enable SHA-256 support by default",
2020-07-29), vanilla builds of Git enable the user to run, e.g.,
git init --object-format=sha256
and hack away. This can be a good way to gain experience with the
SHA-256 world, e.g., to find bugs that
GIT_TEST_DEFAULT_HASH=sha256 make test
doesn't spot.
But it really is a separate world: Such SHA-256 repos will live entirely
separate from the (by now fairly large) set of SHA-1 repos. Interacting
across the border is possible in principle, e.g., through "diff + apply"
(or "format-patch + am"), but even that has its limitations: Applying a
SHA-256 diff in a SHA-1 repo works in the simple case, but if you need
to resort to `-3`, you're out of luck.
Similarly, "push + pull" should work, but you really will be operating
mostly offset from the rest of the world. That might be ok by the time
you initialize your repository, and it might be ok for several months
after that, but there might come a day when you're starting to regret
your use of `git init --object-format=sha256` and have dug yourself into
a fairly deep hole.
There are currently topics in flight to document our data formats and
protocols regarding SHA-256 and in some cases (midx and commit-graph),
we're considering adjusting how the file formats indicate which object
format to use.
Wherever `--object-format` is mentioned in our documentation, let's make
it clear that using it with "sha256" is experimental. If we later need
to explain why we can't handle data we generated back in 2020, we can
always point to this paragraph we're adding here.
By "include::"-ing a small blurb, we should be able to be consistent
throughout the documentation and can eventually gradually tone down the
severity of this text. One day, we might even use it to start phasing
out `--object-format=sha1`, but let's not get ahead of ourselves...
There's also `extensions.objectFormat`, but it's only mentioned three
times. Twice where we're adding this new disclaimer and in the third
spot we already have a "do not edit" warning. From there, interested
readers should eventually find this new one that we're adding here.
Because `GIT_DEFAULT_HASH` provides another entry point to this
functionality, document the experimental nature of it too.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
53 lines
1.4 KiB
Plaintext
53 lines
1.4 KiB
Plaintext
git-show-index(1)
|
|
=================
|
|
|
|
NAME
|
|
----
|
|
git-show-index - Show packed archive index
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git show-index' [--object-format=<hash-algorithm>]
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
Read the `.idx` file for a Git packfile (created with
|
|
linkgit:git-pack-objects[1] or linkgit:git-index-pack[1]) from the
|
|
standard input, and dump its contents. The output consists of one object
|
|
per line, with each line containing two or three space-separated
|
|
columns:
|
|
|
|
- the first column is the offset in bytes of the object within the
|
|
corresponding packfile
|
|
|
|
- the second column is the object id of the object
|
|
|
|
- if the index version is 2 or higher, the third column contains the
|
|
CRC32 of the object data
|
|
|
|
The objects are output in the order in which they are found in the index
|
|
file, which should be (in a correctly constructed file) sorted by object
|
|
id.
|
|
|
|
Note that you can get more information on a packfile by calling
|
|
linkgit:git-verify-pack[1]. However, as this command considers only the
|
|
index file itself, it's both faster and more flexible.
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
--object-format=<hash-algorithm>::
|
|
Specify the given object format (hash algorithm) for the index file. The
|
|
valid values are 'sha1' and (if enabled) 'sha256'. The default is the
|
|
algorithm for the current repository (set by `extensions.objectFormat`), or
|
|
'sha1' if no value is set or outside a repository..
|
|
+
|
|
include::object-format-disclaimer.txt[]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|