From patchwork Wed Mar 22 09:49:32 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sean Allred X-Patchwork-Id: 13183812 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id EFC05C6FD1F for ; Wed, 22 Mar 2023 09:51:31 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230219AbjCVJva (ORCPT ); Wed, 22 Mar 2023 05:51:30 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58590 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230072AbjCVJuz (ORCPT ); Wed, 22 Mar 2023 05:50:55 -0400 Received: from mail-wr1-x436.google.com (mail-wr1-x436.google.com [IPv6:2a00:1450:4864:20::436]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E6B3E6153E for ; Wed, 22 Mar 2023 02:49:36 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id l27so8014612wrb.2 for ; Wed, 22 Mar 2023 02:49:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1679478574; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=AyYRsR3FhUrM6ZSK38Xr53wc2x0CxvJgEc2ZX7R85HQ=; b=ZGTCB1EIADT57RLCuwRooOQY5fWeCY/CZ+zQ/pDOLFWE7y6tqQrkF2TSW64n4Bfval uRMVKPAVAW6ewMbnayjlGgvtJKO479CYgeoU7GNFtip2c7/W5gxOGGex5bUBZRAPhgLY FG8pX3UQbYGzcHD8NEpf6j2bdxJ71ZKMT4x5lxH4YM1CQnLDraaA275Bu/VzH1zCgyhi PLRIhGFs6+TthKk/kn2n/vq8yNG7q5JSVTQ05vTYhAvPZG9qmdqJPybAIp7+cHsh/58t NrmfSCOkKkvnM2UI1uxwK/2v91uh2/XadN2RzIilUaSvhj1T9pkALRSlzo3Nfh5nDs0K TNNg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1679478574; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=AyYRsR3FhUrM6ZSK38Xr53wc2x0CxvJgEc2ZX7R85HQ=; b=UpZ9S7OhETi7r3OL26Mj5LNmn6/bxWfHa3sWBBSjPEUx5LbGN8QMvBOJdOEyDqCqz8 RLw5DnDmAtMU5pYzQKoyJ+ytgjqQ/+25+qM7jWJ3mrMU4bD9Z9jwWRbZT67vizRuX8xg SPDPt60Jik4ZXK6swQVBX9bzZ4591AQYqcVqV/cmFHhu/8eto+CwpIZ8ZXZxd6ag1uk7 V93Q9yT+2d/IRuom78ldHePYQ8w1CD1Cuc9rxBapJ7uxha758OoA87xOp1hYqGbWQ6pA 459YHIXb355ZFMhbJ1mWaGKjYqKpsQ4LCBithsBHYXZxa/b/yyuFEjbhKjUTKCecktOF b8qQ== X-Gm-Message-State: AO0yUKVfCycNEkirSVY02qf4g50TDHd2lKu2Cr+TnDOq7xhD75w3NexV mu/IpGe1zAe+Iax6Epg9lbYk8R0X7Jw= X-Google-Smtp-Source: AK7set95LkjCxTZuVXAAPNpWlvURmNef6R2Ofm/mLShQj7dD17QXbaPA+2OYU/ngJQYE3h2EkHDKNw== X-Received: by 2002:adf:e848:0:b0:2cf:e3d8:5dff with SMTP id d8-20020adfe848000000b002cfe3d85dffmr5228376wrn.9.1679478574737; Wed, 22 Mar 2023 02:49:34 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id j10-20020adff00a000000b002d1bfe3269esm13428431wro.59.2023.03.22.02.49.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Mar 2023 02:49:34 -0700 (PDT) Message-Id: <4408b518810501139a8c7d2f7e2240eabea2839d.1679478573.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 22 Mar 2023 09:49:32 +0000 Subject: [PATCH v2 1/2] Update show-ref documentation for internal consistency Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Sean Allred , Sean Allred Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Sean Allred From: Sean Allred - Use inline-code syntax for options where appropriate. - Use code blocks to clarify output format. This patch also swaps out 'SHA-1' language for the implementation-agnostic 'OID' term where appropriate in preparation for supporting different hashing algorithms. Signed-off-by: Sean Allred --- Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index d1d56f68b43..cb876a342a3 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -23,7 +23,7 @@ particular ref exists. By default, shows the tags, heads, and remote refs. -The --exclude-existing form is a filter that does the inverse. It reads +The `--exclude-existing` form is a filter that does the inverse. It reads refs from stdin, one ref per line, and shows those that don't exist in the local repository. @@ -47,14 +47,14 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "{caret}{}" + Dereference tags into object IDs as well. They will be shown with `{caret}{}` appended. -s:: --hash[=]:: - Only show the SHA-1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA-1. + Only show the OID, not the reference name. When combined with + `--dereference`, the dereferenced tag will still be shown after the OID. --verify:: @@ -70,15 +70,15 @@ OPTIONS -q:: --quiet:: - Do not print any results to stdout. When combined with `--verify` this + Do not print any results to stdout. When combined with `--verify`, this can be used to silently check if a reference exists. --exclude-existing[=]:: - Make 'git show-ref' act as a filter that reads refs from stdin of the - form "`^(?:\s)?(?:\^{})?$`" + Make `git show-ref` act as a filter that reads refs from stdin of the + form `^(?:\s)?(?:\^{})?$` and performs the following actions on each: - (1) strip "{caret}{}" at the end of line if any; + (1) strip `{caret}{}` at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; @@ -96,7 +96,13 @@ OPTIONS OUTPUT ------ -The output is in the format: '' '' ''. +The output is in the format: + +------------ + SP LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --head --dereference @@ -110,7 +116,13 @@ $ git show-ref --head --dereference ... ----------------------------------------------------------------------------- -When using --hash (and not --dereference) the output format is: '' +When using `--hash` (and not `--dereference`), the output is in the format: + +------------ + LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --heads --hash @@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, 'git show-ref' will return an error code of 1, +If nothing matches, `git show-ref` will return an error code of 1, and in the case of verification, it will show an error message. -For scripting, you can ask it to be quiet with the "--quiet" flag, which +For scripting, you can ask it to be quiet with the `--quiet` flag, which allows you to do things like ----------------------------------------------------------------------------- @@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use "--tags" and/or "--heads" +To show only tags, or only proper branch heads, use `--tags` and/or `--heads` respectively (using both means that it shows tags and heads, but not other random references under the refs/ subdirectory). -To do automatic tag object dereferencing, use the "-d" or "--dereference" +To do automatic tag object dereferencing, use the `-d` or `--dereference` flag, so you can do ----------------------------------------------------------------------------- From patchwork Wed Mar 22 09:49:33 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sean Allred X-Patchwork-Id: 13183811 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9F8B3C6FD1F for ; Wed, 22 Mar 2023 09:51:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230175AbjCVJv1 (ORCPT ); Wed, 22 Mar 2023 05:51:27 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58520 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230161AbjCVJuw (ORCPT ); Wed, 22 Mar 2023 05:50:52 -0400 Received: from mail-wr1-x436.google.com (mail-wr1-x436.google.com [IPv6:2a00:1450:4864:20::436]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 12F1A6188B for ; Wed, 22 Mar 2023 02:49:37 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id e18so4789078wra.9 for ; Wed, 22 Mar 2023 02:49:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1679478575; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=EMdTeCz8rJ3p+YPGo6LBNdCbedcwhA8HW3O4dGSn8qo=; b=JZbfA35/x7b4w7I5LDF17NSAB/hmyhx5YPu9gNW/3HkZjrZoeopvAt9MlYix4syADD lfRD9ol5zDXBmUF99479Vxjw+XsX2vcPSnXNidLpTd9KtspOB6M/vu5jqUwyuosVCMnw S3TojISDTNgOByQwoRXa4tebT4QlcOLSINWiZzHCsIQNU3ytPjY49uSuOfM8ZtVFxKpM iCjwz7VV3BEzcfMN+hqbUVR06o+ibZy6QM8wnA/e8bjEhsfZcFqB7z1fjJ3x1ddyGRFn oiNEqZCRyAvT3IaeOMwx4RUS6XsWMBk9sGVO022TDCabKlxbuNaR39kfWUpKe0GH5g+7 39Og== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1679478575; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=EMdTeCz8rJ3p+YPGo6LBNdCbedcwhA8HW3O4dGSn8qo=; b=S1FkhIlCB8jDV6+Ewe/qxzhOPomj83+F+QyiQFma6k/wW7HZBgB0EvmaZu5HlhJW2E k1mONeAUjfW9RZTE3bTr3QnwX6gBzIXEqBEBZ9dEoS89urvIJaEKNE6QU4xlJ2TzS35t Ona1u+M7lHJzDhsU/kafbyM8vhoq4eqUozfKQKyfC0oxqGybsbq0BausTRVsiZuCu5s7 5FGNiHou9ulqIJo64kKJ1mv0uqSfijSXRxKmSvLgpGDDW4ozZGs9kbF2MX0UpgTm/kKO 0AgyjHFbkG4dsoaQp529k8kHsNQzPza4P7MB3tvk/j4GhBgzSZMu4wOL4BH69Y6mi2Qv jxlg== X-Gm-Message-State: AO0yUKUAmhefBXFHgaXgyARw9umgf6V94N+tEJPmB0K7zPaneflw8fWa Q7KdaeeyyhUjIN/Vce3cDzgaAcBmnPA= X-Google-Smtp-Source: AK7set/d4i60Pfum7SLHqEV3wpkeOSrPALJebBZ+5hy1A/zWEJMVj6w+I8HAjtdF1R2FUz412KeCEg== X-Received: by 2002:a5d:5508:0:b0:2d8:57b1:db6c with SMTP id b8-20020a5d5508000000b002d857b1db6cmr4728798wrv.9.1679478575323; Wed, 22 Mar 2023 02:49:35 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n17-20020adff091000000b002c5534db60bsm13488645wro.71.2023.03.22.02.49.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Mar 2023 02:49:35 -0700 (PDT) Message-Id: <44e79f0d69c86e3cf4363aaa10acda91bfa3e9ee.1679478573.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 22 Mar 2023 09:49:33 +0000 Subject: [PATCH v2 2/2] Document the output format of ls-remote Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Sean Allred , Sean Allred Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Sean Allred From: Sean Allred While well-established, the output format of ls-remote was not actually documented. This patch adds an OUTPUT section to the documentation following the format of git-show-ref.txt (which has similar semantics). Signed-off-by: Sean Allred --- Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index ff3da547ddb..9913ab3f83d 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -96,6 +96,30 @@ OPTIONS separator (so `bar` matches `refs/heads/bar` but not `refs/heads/foobar`). +OUTPUT +------ + +The output is in the format: + +------------ + TAB LF +------------ + +For example, + +---- +$ git ls-remote +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/heads/maint +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +74a0ffe000da036ce4ca843d991a7c6b8c246a08 refs/heads/seen +860bc4360c4fcba0fe2df942984d87f8467af3df refs/heads/todo +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +8810a79228a149a9773bf9c75f381fca27a6a80e refs/tags/v2.40.0-rc0 +f899c182d0bffb6e915da7c8db9be202b144c098 refs/tags/v2.40.0-rc1 +6bed3304b2b2f1cf440ca3050b57a7cf3a3fe687 refs/tags/v2.40.0-rc2 +---- + EXAMPLES --------