From 1ccb6699a1fd8355a81c5ac10086b67ab8788510 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 20 Jul 2020 19:56:47 -0400 Subject: [PATCH] guidance on size and mtime fields --- CHANGELOG | 4 ++-- doc/design/external_backend_protocol.mdwn | 12 +++++++++++- .../external_backend_protocol/git-annex-backend-XFOO | 3 ++- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 6b32db0c4c..ff72a98956 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,8 +1,8 @@ -git-annex (8.20200720.1) UNRELEASED; urgency=medium +git-annex (8.20200720.1) upstream; urgency=medium * Fix a bug in find --batch in the previous version. - -- Joey Hess Mon, 20 Jul 2020 19:37:40 -0400 + -- Joey Hess Mon, 20 Jul 2020 19:39:11 -0400 git-annex (8.20200720) upstream; urgency=medium diff --git a/doc/design/external_backend_protocol.mdwn b/doc/design/external_backend_protocol.mdwn index 305f8fbbbe..69f0a6bca5 100644 --- a/doc/design/external_backend_protocol.mdwn +++ b/doc/design/external_backend_protocol.mdwn @@ -131,7 +131,8 @@ These messages can be sent at any time by either git-annex or the program. ## considerations for generating keys -See [[internals/key_format]] for how to format a key. +See [[internals/key_format]] for how to format a key and details about the +parts of a key. The backend name should match the name of the program, eg if the program is git-annex-backend-XFOO, it should generate a key starting with "XFOO-". @@ -159,6 +160,15 @@ in the key name, where users are unlikely to notice it. While git has several things that make sha1 collision attacks difficult, we don't want this chink in the armor. +It's almost always a good idea to include the size field when generating a +key. The size does not need to be checked when verifying content, as +git-annex handles that for you. The only time it would make sense to omit +the size field is if the content of a key is not stable and might have +different sizes (like some URL keys do). + +There's generally no reason to include the mtime field, and it should +never be verified when verifying content. + ## program names must be unique It's important that two different programs don't use the same name, because diff --git a/doc/design/external_backend_protocol/git-annex-backend-XFOO b/doc/design/external_backend_protocol/git-annex-backend-XFOO index 0282fab4ae..6886ab0646 100755 --- a/doc/design/external_backend_protocol/git-annex-backend-XFOO +++ b/doc/design/external_backend_protocol/git-annex-backend-XFOO @@ -33,8 +33,9 @@ while read line; do GENKEY) contentfile="$2" hash=$(hashfile "$contentfile") + sz=$(wc -c "$contentfile" | cut -d ' ' -f 1) if [ -n "$hash" ]; then - echo "GENKEY-SUCCESS" "XFOO--$hash" + echo "GENKEY-SUCCESS" "XFOO-s$sz--$hash" else echo "GENKEY-FAILURE" "md5sum failed" fi