From: Jonathan Tan <jonathantanmy@google.com>
To: git@vger.kernel.org
Cc: Jonathan Tan <jonathantanmy@google.com>
Subject: [PATCH 4/4] Doc: push with --base
Date: Mon, 2 Nov 2020 16:26:13 -0800 [thread overview]
Message-ID: <6250c13897e3cc01f247d80c148cf8dc5e7f3ad0.1604362701.git.jonathantanmy@google.com> (raw)
In-Reply-To: <cover.1604362701.git.jonathantanmy@google.com>
Includes protocol documentation and a design document.
Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
---
Documentation/technical/pack-protocol.txt | 10 ++--
Documentation/technical/push-with-base.txt | 61 ++++++++++++++++++++++
2 files changed, 68 insertions(+), 3 deletions(-)
create mode 100644 Documentation/technical/push-with-base.txt
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index e13a2c064d..0485616701 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -59,9 +59,9 @@ Parameters", and are supported by the Git, SSH, and HTTP protocols.
Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
Servers that receive any such Extra Parameters MUST ignore all
-unrecognized keys. Currently, the only Extra Parameter recognized is
-"version" with a value of '1' or '2'. See protocol-v2.txt for more
-information on protocol version 2.
+unrecognized keys. Currently, the only Extra Parameters recognized are
+"version" with a value of '1' or '2' and, for push, "base" with an OID. See
+protocol-v2.txt for more information on protocol version 2.
Git Transport
-------------
@@ -506,6 +506,10 @@ real difference is that the capability listing is different - the only
possible values are 'report-status', 'report-status-v2', 'delete-refs',
'ofs-delta', 'atomic' and 'push-options'.
+If a "base=<oid>" Extra Parameter was sent by the client, and the
+server recognizes that object, the server MAY send "<oid> .have" in
+lieu of all the reference obj-ids and names.
+
Reference Update Request and Packfile Transfer
----------------------------------------------
diff --git a/Documentation/technical/push-with-base.txt b/Documentation/technical/push-with-base.txt
new file mode 100644
index 0000000000..d56aa7f900
--- /dev/null
+++ b/Documentation/technical/push-with-base.txt
@@ -0,0 +1,61 @@
+Push with base design notes
+===========================
+
+This feature allows clients, when pushing, to indicate that a
+certain object is an ancestor of all pushed commits and that they
+believe that the server knows of this object. This in turn allows
+servers to send an abbreviated ref advertisement containing only that
+object.
+
+Besides bandwidth savings, this also ensures that the ref
+advertisement contains information relevant to the client. For
+example, at least one project (Gerrit [1]) have included workarounds
+to send ancestors of refs that move often, even though the ref
+advertisement is only meant to contain refs.
+
+[1] https://gerrit.googlesource.com/gerrit/+/refs/heads/master/java/com/google/gerrit/server/git/receive/HackPushNegotiateHook.java
+
+
+Design overview
+---------------
+
+The "base" being sent is sent as an Extra Parameter, supported in the
+git://, ssh://, and http(s):// protocols. By sending it as an Extra
+Parameter, the server is aware of this parameter before it generates
+the ref advertisement, thus making it able to tailor the ref
+advertisement accordingly. Sending it as an Extra Parameter also makes
+this protocol backwards-compatible, as servers will ignore any Extra
+Parameters they do not understand. (The push will then proceed as if
+neither party had this feature.)
+
+The remote helper protocol has been extended to support the
+"push-base" capability and an option of the same name. When a remote
+helper advertises this capability, it thus indicates that it supports
+this option. Git then will send "option push-base" if the user
+specifies it when invoking "git push".
+
+The remote-curl remote helper bundled with Git has been updated to
+support this capability and option.
+
+
+Future work
+-----------
+
+In the future, we might want a way to automatically determine the base
+instead of always having the user specify it. However, this does not
+make obsolete any of the current work - once the base is automatically
+determined, we still need this protocol to communicate it to the
+server, and allowing the user to specify the base manually is still
+useful.
+
+
+Alternatives
+------------
+
+- Making a more substantial protocol change like "fetch" protocol v2.
+ This would eliminate the need for some of the remote helper updates;
+ as part of the protocol change, the protocol could be made to
+ support "stateless-connect" and thus no remote helper updates (like
+ "push-base") would be needed. For "fetch", the protocol change has
+ enabled features like wanted-refs and packfile-uris, but I do not
+ have any similar ideas in mind for "push".
--
2.29.1.341.ge80a0c044ae-goog
next prev parent reply other threads:[~2020-11-03 0:27 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-03 0:26 [PATCH 0/4] "Push" protocol change proposal: user-specified base Jonathan Tan
2020-11-03 0:26 ` [PATCH 1/4] connect: refactor building of Extra Parameters Jonathan Tan
2020-11-03 0:26 ` [PATCH 2/4] push: teach --base for ssh:// and file:// Jonathan Tan
2020-11-03 10:23 ` SZEDER Gábor
2020-11-08 19:31 ` Junio C Hamano
2020-11-03 13:57 ` Derrick Stolee
2020-11-08 19:30 ` Junio C Hamano
2020-11-03 0:26 ` [PATCH 3/4] remote-curl: teach --base for http(s):// Jonathan Tan
2020-11-03 1:13 ` Junio C Hamano
2020-11-03 0:26 ` Jonathan Tan [this message]
2020-11-03 5:35 ` [PATCH 4/4] Doc: push with --base Jonathan Nieder
2020-11-03 15:18 ` Jeff King
2020-11-03 17:35 ` Junio C Hamano
2020-11-09 19:56 ` Jonathan Tan
2020-11-09 21:00 ` Derrick Stolee
2020-11-09 22:22 ` Jonathan Tan
2020-11-09 21:20 ` Junio C Hamano
2020-11-09 21:40 ` Jeff King
2020-11-09 22:47 ` Jonathan Tan
2020-11-03 13:53 ` Derrick Stolee
2020-11-03 0:46 ` [PATCH 0/4] "Push" protocol change proposal: user-specified base Junio C Hamano
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=6250c13897e3cc01f247d80c148cf8dc5e7f3ad0.1604362701.git.jonathantanmy@google.com \
--to=jonathantanmy@google.com \
--cc=git@vger.kernel.org \
/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).