git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Stefan Beller <sbeller@google.com>
To: git@vger.kernel.org
Cc: gitster@pobox.com, mfick@codeaurora.org, pclouds@gmail.com,
	Stefan Beller <sbeller@google.com>
Subject: [PATCH] RFC/Add documentation for version protocol 2
Date: Tue, 21 Apr 2015 16:19:02 -0700	[thread overview]
Message-ID: <1429658342-5295-1-git-send-email-sbeller@google.com> (raw)

This adds the design document for protocol version 2.
It's better to rewrite the design document instead of trying to
squash it into the existing pack-protocol.txt and then differentiating
between version 1 and 2 all the time.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
  
 As we discussed at Git Merge in Paris, I'd just start out implementing the new
 protocol "to deliver something you can play around with". Unfortunately I
 did not come up with an implementation straight away, but I think we should be
 coming to a consensus on the rough design at first. If there are no objections
 in the design I'll go for implementation.

 Documentation/technical/pack-protocol-2.txt | 88 +++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 Documentation/technical/pack-protocol-2.txt

diff --git a/Documentation/technical/pack-protocol-2.txt b/Documentation/technical/pack-protocol-2.txt
new file mode 100644
index 0000000..36ddf3e
--- /dev/null
+++ b/Documentation/technical/pack-protocol-2.txt
@@ -0,0 +1,88 @@
+Packfile transfer protocols version 2
+=====================================
+
+This document describes an updated protocol to transfer packs over ssh://,
+git:// and file:// links. All three transports (ssh, git, file) use the same
+protocol to transfer data. This document describes the version 2 of the pack
+file protocol, which is incompatible with the previous pack protocol.
+
+The http:// transport is not yet thought about in this phase of the protocol
+design.
+
+As this protocol is introduced rather late in the game, just after Gits 10th
+anniversary, a client SHOULD NOT assume a server speaks protocol version 2
+unless the server advertised protocol in a prior exchange.
+
+General structure
+=================
+
+There are four phases involved in the protocol, which are described below:
+
+1) capability negotiation
+2) goal annoncement
+3) reference advertisement
+4) pack transfer
+
+
+1) Capability negotiation
+-------------------------
+
+In this phase both client and server send their capabilities to the other side
+using the following protocol:
+
+---
+list-of-capabilities = *capability flush-pkt
+capability           =  PKT-LINE(1*(LC_ALPHA / DIGIT / "-" / "_"))
+----
+
+The capabilities itself are described in protocol-capabilities.txt
+Sending the capabilities to the other side MAY happen concurrently or
+one after another. There is no order who sends first.
+
+Note for developers:
+The amount of data SHOULD be kept very small. Future extensions to the protocol
+SHOULD only add a capability flag to this phase, adding possible data
+transfers into later phases. This ensures the protocol is extendable over
+time without having to spent to send huge chunks of data in the first phase.
+If both sides agree on a certain feature being used, it is easy to introduce more
+phases at any convenieant point after the phase 1 is finished.
+
+Notes as a design rationale:
+I thought about caching
+https://www.ll.mit.edu/HPEC/agendas/proc04/invited/patterson_keynote.pdf
+
+2) Goal annoncement
+-------------------
+
+The goal of this phase is for the client to tell the server what
+outcome it expects from this communication, such as pushing or
+pulling data from the server.
+
+---
+list-of-goals    = *goal
+goal             = PKT-LINE(action-line)
+action-line      = action *(SP action-parameter)
+action           = "noop" / "ls-remote" / "fetch" / "push" / "fetch-shallow"
+action-parameter = parameter-key *("=" parameter-value)
+parameter-key    = 1*(LC_ALPHA / DIGIT / "-" / "_")
+---
+
+You MAY specify multiple goals such as fetch and push or fetch-shallow.
+You MAY also specify the same goal multiple times with different parameters.
+You MUST omit goals which are part of other goals, such as ls-remote being part
+of fetch.
+
+The action parameter is dependant on the action itself. For now only fetch and push
+take the parameter "mode", whose only allowed value is "version1".
+
+Note:
+The parameters should follow a key=value pattern, where the value can consist of
+arbitrary characters. Having such a pattern would allow us to easily add a new
+capability for narrow clones (e.g. "fetch-narrow=Documentation/*,.git*,.mailmap"
+to fetch only the Documentation and .gitignore/attributes)
+
+3) Ref advertisement
+--------------------
+3) and 4) are highly dependant on the mode for fetch and push. As currently
+only mode "version1" is supported, the these phases follow the ref advertisement
+in pack protocol version 1 without capabilities on the first line of the refs.
-- 
2.4.0.rc2.5.g4c2045b.dirty

             reply	other threads:[~2015-04-21 23:19 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-04-21 23:19 Stefan Beller [this message]
2015-04-22 19:19 ` [PATCH] RFC/Add documentation for version protocol 2 Junio C Hamano
2015-04-22 19:43   ` Stefan Beller
2015-04-22 23:30     ` Junio C Hamano
2015-04-23  6:16       ` Stefan Beller

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1429658342-5295-1-git-send-email-sbeller@google.com \
    --to=sbeller@google.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=mfick@codeaurora.org \
    --cc=pclouds@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).