external protocol VERSION 2

Support VERSION 2 in the external special remote protocol, which is
identical to VERSION 1, but avoids external remote programs neededing to
work around the above bug. External remote program that support
exporttree=yes are recommended to be updated to send VERSION 2.

Sponsored-by: Kevin Mueller on Patreon

diff --git a/Remote/External/Types.hs b/Remote/External/Types.hs
index a12a0d70ebef2209576b0d04a4ca707c03870c0d..512913ba8a31d3f8a386107f7812ece08a0f605f 100644 (file)
--- a/Remote/External/Types.hs
+++ b/Remote/External/Types.hs
@@ -415,7 +415,7 @@ newtype JobId = JobId Integer
        deriving (Eq, Ord, Show)
 
 supportedProtocolVersions :: [ProtocolVersion]
-supportedProtocolVersions = [1]
+supportedProtocolVersions = [1, 2]
 
 instance Proto.Serializable JobId where
        serialize (JobId n) = show n

diff --git a/doc/design/external_special_remote_protocol.mdwn b/doc/design/external_special_remote_protocol.mdwn
index 3d2f0588aea6ec94568d9dd7e16a0917f20c6bd7..d4bf6bcf3d3f8501990690cc44a0d04e009646ef 100644 (file)
--- a/doc/design/external_special_remote_protocol.mdwn
+++ b/doc/design/external_special_remote_protocol.mdwn
@@ -39,7 +39,7 @@ empty, but the separating spaces are still required in that case.
 The special remote is responsible for sending the first message, indicating
 the version of the protocol it is using.
 
-       VERSION 1
+       VERSION 2
 
 Recent versions of git-annex respond with a message indicating
 protocol extensions that it supports. Older versions of
@@ -271,7 +271,7 @@ These messages may be sent by the special remote at any time that it's
 handling a request.
 
 * `VERSION Int`  
-  Supported protocol version. Current version is 1. Must be sent first
+  Supported protocol version. Current version is 2. Must be sent first
   thing at startup, as until it sees this git-annex does not know how to
   talk with the special remote program!  
   (git-annex does not send a reply to this message, but may give up if it
@@ -428,6 +428,18 @@ remote.
   git-annex will not talk to it any further. If the program receives
   an ERROR from git-annex, it can exit with its own ERROR.
 
+## protocol versions
+
+Currently git-annex supports `VERSION 1` and `VERSION 2`.
+The two protocol versions are actually identical. 
+
+Old versions of git-annex that supported only `VERSION 1`
+had a bug in their implementation of the 
+part of the protocol documented in the [[export_and_import_appendix]].
+The bug could result in ontent being exported to the wrong file.
+External special remotes that implement that should use `VERSION 2` to
+avoid talking to the buggy old version of git-annex.
+
 ## extensions
 
 These protocol extensions are currently supported.

diff --git a/doc/special_remotes/external/example.sh b/doc/special_remotes/external/example.sh
index cfae74ae25a791a8dbf8b476fe17d5c6feacd8b0..413065d1e04f2e1250ef56becb85937a526db0c9 100755 (executable)
--- a/doc/special_remotes/external/example.sh
+++ b/doc/special_remotes/external/example.sh
@@ -150,7 +150,7 @@ doremove () {
 }
 
 # This has to come first, to get the protocol started.
-echo VERSION 1
+echo VERSION 2
 
 while read line; do
        set -- $line

diff --git a/doc/special_remotes/external/git-annex-remote-ipfs b/doc/special_remotes/external/git-annex-remote-ipfs
index f255f9bc596968c104251fef2409453aef7389aa..f546a1ae81aa7425ec662ed33ab3f3f5c862f740 100755 (executable)
--- a/doc/special_remotes/external/git-annex-remote-ipfs
+++ b/doc/special_remotes/external/git-annex-remote-ipfs
@@ -54,7 +54,7 @@ getaddrs () {
 }
 
 # This has to come first, to get the protocol started.
-echo VERSION 1
+echo VERSION 2
 
 while read line; do
        set -- $line

diff --git a/doc/special_remotes/external/git-annex-remote-torrent b/doc/special_remotes/external/git-annex-remote-torrent
index a3b2bb85807a6e6f7cfc86e490d144cd3f0502b7..f41585b7c25d63ab8db2fc36f673b4130a6f059f 100755 (executable)
--- a/doc/special_remotes/external/git-annex-remote-torrent
+++ b/doc/special_remotes/external/git-annex-remote-torrent
@@ -100,7 +100,7 @@ downloadtorrent () {
 }
 
 # This has to come first, to get the protocol started.
-echo VERSION 1
+echo VERSION 2
 
 while read line; do
        set -- $line