From patchwork Sat Aug 15 17:17:35 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jiang Xin X-Patchwork-Id: 11715789 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D1658109B for ; Sat, 15 Aug 2020 22:02:44 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B2B8820781 for ; Sat, 15 Aug 2020 22:02:44 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="n3FW6jKJ" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729735AbgHOWC1 (ORCPT ); Sat, 15 Aug 2020 18:02:27 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45624 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728732AbgHOVvY (ORCPT ); Sat, 15 Aug 2020 17:51:24 -0400 Received: from mail-pf1-x444.google.com (mail-pf1-x444.google.com [IPv6:2607:f8b0:4864:20::444]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 078BCC0068F8 for ; Sat, 15 Aug 2020 10:17:53 -0700 (PDT) Received: by mail-pf1-x444.google.com with SMTP id f193so6053747pfa.12 for ; Sat, 15 Aug 2020 10:17:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=kvitj2ntuR2/UytI/5U9IbwHvrC6MX8tJb6rNyP+GYE=; b=n3FW6jKJrrdEl7gyEeKp1Cqv7M8+Mxw6cBJf1CWGyIYo1QqxaPbE1axM4KlO/FmeT/ ktCgpyX3Upg8XT9ubmUAPgT/WacB5lHF1RLd228W9mQyPkP2FwzFhShWVoTbLXFazGUC dbecuFPD4R5nIVCQMYMa0x1HyT3gFh5wxhzjnEfeJyOYuWNArH6ahLoDcyl8Zi9yBvnB 5muPWsL61CM/qDjZOcG+Y+Emd8SwT5F+iUqjfvBK/HSr7wy/6MUZohsUE3lgYUNhdUKI hCCFw86IFQ/d3FRcy23pji0XWNkuRJ2qJrMxZ/OcTpd7mYhzKGnT/AZBFNdHVd2kFdK5 kQ7Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=kvitj2ntuR2/UytI/5U9IbwHvrC6MX8tJb6rNyP+GYE=; b=Iug/2L76w/CLtRXwCs9siDfI73zCZxtt1KpL4FtkzqomJznG/QmtBqMBUE0U3dBGue J+8BS2TwlkdI2ElYU8i3ECkhTAMfMwZVZeZ22/sGD3xAuuHBLad6+QL6RITXDh1lPKCk J6gGY86/LAwGXEKJW9LS/Zq3y3H9VIXfnEL5t0HzBEq+AFcOKYNWP5BCRdecek9kxKRo 9Fs9EkBCFKASklIkbZZ8mkhzjPfxWKk+xW/h2Sz4EUIX6oL+EWWyddpRQYh2kAvk5JgW Wb7rPZ1csqQ5rqyF/mCkCqTwL9wnn49D57EgrTpSFilU6OH98xeLt69FGq2bjZjbhsyb xq0A== X-Gm-Message-State: AOAM530x0Qlh68E1aNd6hVHJevR//7FlFzYwm3GX5HhypLwV1oArXaZW DfFMxY0MC8DXgc4azeSyu04= X-Google-Smtp-Source: ABdhPJwsDbIC6AcbaAoHRvtl56npF6VTf3HYrgDGU+oudHQZh7QQXf0GGE9G2wxTDWDPbl3x7h3fig== X-Received: by 2002:a63:fe0a:: with SMTP id p10mr5009227pgh.255.1597511873414; Sat, 15 Aug 2020 10:17:53 -0700 (PDT) Received: from tigtog.localdomain.localdomain ([144.34.163.219]) by smtp.gmail.com with ESMTPSA id x13sm11040596pga.30.2020.08.15.10.17.52 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 15 Aug 2020 10:17:52 -0700 (PDT) From: Jiang Xin To: Junio C Hamano , Git List Cc: Jiang Xin Subject: [PATCH v17 05/10] doc: add document for capability report-status-v2 Date: Sat, 15 Aug 2020 13:17:35 -0400 Message-Id: <20200815171740.6257-6-worldhello.net@gmail.com> X-Mailer: git-send-email 2.26.0.rc0 In-Reply-To: <20200518094039.757-1-worldhello.net@gmail.com> References: <20200518094039.757-1-worldhello.net@gmail.com> MIME-Version: 1.0 Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Jiang Xin Add ABNF notation for capability 'report-status-v2' which extends capability 'report-status' by adding additional option lines. Signed-off-by: Jiang Xin --- Documentation/technical/pack-protocol.txt | 43 +++++++++++++++++-- .../technical/protocol-capabilities.txt | 17 ++++++-- 2 files changed, 54 insertions(+), 6 deletions(-) diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index a4573d12ce..01eb1629a8 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -503,8 +503,8 @@ The reference discovery phase is done nearly the same way as it is in the fetching protocol. Each reference obj-id and name on the server is sent in packet-line format to the client, followed by a flush-pkt. The only real difference is that the capability listing is different - the only -possible values are 'report-status', 'delete-refs', 'ofs-delta' and -'push-options'. +possible values are 'report-status', 'report-status-v2', 'delete-refs', +'ofs-delta', 'atomic' and 'push-options'. Reference Update Request and Packfile Transfer ---------------------------------------------- @@ -625,7 +625,7 @@ Report Status ------------- After receiving the pack data from the sender, the receiver sends a -report if 'report-status' capability is in effect. +report if 'report-status' or 'report-status-v2' capability is in effect. It is a short listing of what happened in that update. It will first list the status of the packfile unpacking as either 'unpack ok' or 'unpack [error]'. Then it will list the status for each of the references @@ -647,6 +647,43 @@ update was successful, or 'ng [refname] [error]' if the update was not. error-msg = 1*(OCTET) ; where not "ok" ---- +New capability "report-status-v2" extends the protocol by adding new option +lines in order to support reporting of reference rewritten by the +"proc-receive" hook. The "proc-receive" hook may handle a command for a +pseudo-reference which may create or update one or more references, and each +reference may have different name, different new-oid, and different old-oid. + +---- + report-status-v2 = unpack-status + 1*(command-status-v2) + flush-pkt + + unpack-status = PKT-LINE("unpack" SP unpack-result) + unpack-result = "ok" / error-msg + + command-status-v2 = command-ok-v2 / command-fail-v2 + command-ok-v2 = command-ok + *option-line + command-fail-v2 = command-fail + *option-line + + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) + + error-msg = 1*(OCTET) ; where not "ok" + + option-line = *1(option-refname) + *1(option-old-oid) + *1(option-new-oid) + *1(option-forced-update) + + option-refname = PKT-LINE("option" SP "refname" SP refname) + option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id) + option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id) + option-force = PKT-LINE("option" SP "forced-update") + +---- + Updates can be unsuccessful for a number of reasons. The reference can have changed since the reference discovery phase was originally sent, meaning someone pushed in the meantime. The reference being pushed could be a diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 36ccd14f97..78c0c4b3e2 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -22,9 +22,9 @@ was sent. Server MUST NOT ignore capabilities that client requested and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand. -The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert' -capabilities are sent and recognized by the receive-pack (push to server) -process. +The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet', +and 'push-cert' capabilities are sent and recognized by the receive-pack +(push to server) process. The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized by both upload-pack and receive-pack protocols. The 'agent' capability @@ -284,6 +284,17 @@ each reference was updated successfully. If any of those were not successful, it will send back an error message. See pack-protocol.txt for example messages. +report-status-v2 +---------------- + +Capability 'report-status-v2' extends capability 'report-status' by +adding new option lines in order to support reference rewritten by +the"proc-receive" hook. The "proc-receive" hook may handle a command +for a pseudo-reference which may create or update a reference with +different name, new-oid, and old-oid. While the capability +"report-status" cannot report for such case. See pack-protocol.txt +for details. + delete-refs -----------