git-foolscap 20.7.0

• https://github.com/warner/git-foolscap

git-foolscap是Git的一个扩展，允许您通过[Foolscap](http://foolscap.lothar.com/trac)协议发布或访问Git仓库。这提供了ssh或认证HTTPS的所有安全优势，但还有一些重要的优势

• 下游用户不需要在服务器上拥有账户：只需与他们分享秘密FURL字符串就足以提供访问权限

• 访问仅限于一个仓库：用户不会获得完整的shell访问权限

• 服务器快速且易于设置

• 用户可以轻松限制为只读访问

## 安装

只需使用pip install git-foolscap。这将在您的$PATH中安装两个脚本：git-foolscap和git-remote-pb。前者是主要入口点，Git会在您运行git foolscap COMMAND..时运行它。后者实现了远程协议，Git会在您访问以“pb:”开头的仓库（即FURL）时使用它。

git-foolscap依赖于Foolscap的安装，而Foolscap依赖于Twisted和pyOpenSSL。

git-foolscap -h和git-foolscap –help将提供用法说明。（请注意，git foolscap –help（不带连字符）不工作，因为git-foolscap不提供man页）。

## 工作原理

通过运行一个小型服务器（一个名为“Foolscap flappserver”的服务器）来发布仓库，该服务器监听TCP端口以接收加密连接。分配一个“FURL”，它将通过git远程协议（以读取+写入或只读模式）连接到特定仓库。这个FURL可以交给客户端，客户端只需将其用作标准git远程的URL（例如 git clone FURL 或 git remote add NAME FURL）。Foolscap FURL是URI，其方案使用“pb:”而不是“http:”或“https:”。

当git客户端遇到pb: FURL时，它将控制权委托给名为git-remote-pb的程序（这是git的标准功能，对任意方案名称都适用）。git-remote-pb程序知道如何使用Foolscap连接到目标FURL并通过它使用git远程协议。

技术上，这意味着服务器只需要git-foolscap可执行文件，客户端只需要git-remote-pb可执行文件，但为了简单起见，它们都包含在同一个包中。

## 使用方法：服务器

请参阅git foolscap –help获取完整详细信息。基本上，服务器只执行以下部分

` % git foolscap init --port=tcp:3116 --location=tcp:HOSTNAME:3116 % git foolscap start `

并为每个新的客户端执行以下部分

` % git foolscap invite read-write "关于接收者的注释" `

“邀请”将生成一个“虫洞代码”，接收用户必须将其输入到他们的“接受”命令中。然后，安全的FURL将通过虫洞发送。

FURL也可以使用git foolscap add添加（无需邀请）。然后必须将其粘贴给接收者。

要提供对单个仓库的只读访问，请将read-write替换为read-only。您可以通过多次运行git foolscap add或invite来创建任意数量的FURL。每个FURL可以单独撤销。要撤销访问，运行git foolscap list，找到索引号，并将其传递给git foolscap revoke。

您可能希望安排在系统重启时通过cron @reboot作业或其他启动脚本运行git foolscap start，以确保访问保留。

@reboot cd PATH/TO/REPO && git foolscap start

## 使用方法：客户端

如果仓库所有者使用了git foolscap invite，则只需将此代码输入到

` % git foolscap accept clone `

客户端可以使用代码词的tab补全，单词表被专门设计为可以通过嘈杂的语音信道可靠地转录。

除了克隆仓库的新副本之外，您还可以通过在仓库内部运行此命令将新的FURL添加到现有仓库中

` % git foolscap accept add-remote `

如果发布者使用了git foolscap add并向您发送了完整的FURL（而不是虫洞代码），则您可以像正常HTTPS（https://github.com/warner/git-foolscap.git）或SSH（git@github.com:warner/git-foolscap.git）URL一样从它克隆。只要您安装了git-foolscap，git就会弄清楚如何正确处理。

## 清理FURL

flappserver使用您提供的–location=来构造FURL的“连接提示”部分。这告诉客户端如何连接到服务器。服务器必须有一个公开可访问的地址（或者至少可以被您的客户端访问），或者您必须配置端口转发，并将公开可访问的地址+端口号放入FURL中。

如果您主机名错误，或者您使用了IP地址并且它已经更改，您可以在以后编辑FURL。您还可以使用多个提示，客户端将尝试连接到它们中的每一个，直到至少有一个工作

pb://tvzddtbzbldthde5kdsvjvzpweifx7ae@tcp:example.com:57306,tcp:example.org:57306/jmxpcs6lsmgtuzdomxbgtfcmhgfmfbpc/my-repo

在FURL中的第一个大随机字符串准确地标识了期望的服务器公钥：它提供了加密保证，连接将连接到正确的服务器。不使用证书授权机构或可信第三方。第二个随机字符串是一个秘密的“swissnum”，它安全地标识了正在访问的资源（在这种情况下，一个指向git仓库和读写/只读模式的表条目）。了解这个秘密即可访问：要共享访问，请共享秘密（以及使用FURL所需的所有其余部分）；要阻止访问，不要泄露秘密。

## 配置flappserver

每个flappserver都有一个“基本目录”，其中存储所有状态。 git foolscap create 默认使用 .git/foolscap/ 用于此目的，如果需要，则创建它，然后添加一个新FURL的条目。

如果您发布多个仓库，您可能希望在不同之间共享flappserver，尤其是如果您必须为每个服务器配置端口转发。为此，首先使用Foolscap的 flappserver create BASEDIR 命令创建一个共享服务器，然后在运行 git foolscap init 时使用 –flappserver=BASEDIR 参数。这将从 .git/foolscap 到真实的BASEDIR建立一个符号链接，因此后续的git-foolscap命令将直接添加到该flappserver的条目中。如果BASEDIR尚未存在，它将被创建。

请注意，目前，git foolscap init –flappserver=BASEDIR 需要 –port= 和 –location= 参数，即使BASEDIR已经存在。然而，在这种情况下，它们的值被忽略，以优先考虑BASEDIR的现有配置。希望这将在未来的版本中得到修复。

如果您使用一个 @reboot crontab，您可能想直接使用 flappserver start，而不是 git foolscap start。

## 错误、补丁

请在Github问题跟踪器中为git-foolscap报告错误和补丁，网址为 https://github.com/warner/git-foolscap .

对于foolscap本身的错误和补丁，请在Foolscap Trac上使用，网址为 http://foolscap.lothar.com/trac . Foolscap源代码发布在Github上，网址为 https://github.com/warner/foolscap .

谢谢！