From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-3.8 required=3.0 tests=AWL,BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by dcvr.yhbt.net (Postfix) with ESMTP id 992781F5AE for ; Tue, 4 Aug 2020 00:56:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727083AbgHDA41 (ORCPT ); Mon, 3 Aug 2020 20:56:27 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45218 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726130AbgHDA41 (ORCPT ); Mon, 3 Aug 2020 20:56:27 -0400 Received: from mail-io1-xd41.google.com (mail-io1-xd41.google.com [IPv6:2607:f8b0:4864:20::d41]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 07F69C06174A for ; Mon, 3 Aug 2020 17:56:27 -0700 (PDT) Received: by mail-io1-xd41.google.com with SMTP id g19so28446336ioh.8 for ; Mon, 03 Aug 2020 17:56:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=kdhTo9Spni/rvfOlsm8efpUz+8QEbGejshuMF/PJKuc=; b=dNEInTwLoD5Tibh8kILWPo3LylGeBcnarMEdCN9S20SV1wEdRUhOty3oqXA1TgaGYJ y8wErg7C/H04BDHajC6/wkaON/IOptlbZyqqDx7zNRrtHE3RDm8YoMBTzM+XmCll68wV FF4oli9QNXniwdC211vJaOk3iiZgvesTEcgWLbBxxVc3pYk4joLqqn4LMeWsCanTOYlD i91P3HxxchKibFdrHYLJJbKF7iNQmKdAFi9pSEFn471t1Gpar47rTJ9X+uhNW3EPglff 4ktHoAzyJcgQdhMrOW2Kc01A/1Hc64XPm4bFXiGHpaZLIOUhkH259D5I5dSvsuAlIleA 6fGw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=kdhTo9Spni/rvfOlsm8efpUz+8QEbGejshuMF/PJKuc=; b=kLfv9BlmqbIaSBLHwtsrbioEoq5xOvN3EWobmXHdJoALpKKbc72zbhIcnmKoTB+KX3 KB+CnlwxUfj0Fn5cOiGh9kVT7L/NFvsS/v4iVTAqfI3DgSdNJeLuidRs52MKiznfSUWE g0OrQv6hvi6/uNGMsBTuOcXGgSi05qf8b44y8P/uLXAaRIUSPH20F3vtRs9hocH9i1L8 zDn9GZTkC54w+/QJjACwS0uC15zroHqSWlBj8AE8QQj+nfXBQ/RUm6/QmTbMVwQkrlaK TNKweKVd6qPv5O+V7vtO+K+yYVYeiUlGrGWPAE4ulV8HElulMpnITceohepvqqgDewh9 68HA== X-Gm-Message-State: AOAM5332vZ9MD60BLbn9V1wpzrWlOudV9O0JL6bBY1sd6whH1uGXzdRu OY2wy5AUCsY70Tc68pt4J6t1dGwnl9U= X-Google-Smtp-Source: ABdhPJz62sm3/I+swmruT1TFDCgtiN6HAPktxMmbY+e0fDnAHBpl0TKbA900yIDr1QdFzJrq+5mSeQ== X-Received: by 2002:a02:8806:: with SMTP id r6mr2776319jai.88.1596502585647; Mon, 03 Aug 2020 17:56:25 -0700 (PDT) Received: from localhost.localdomain (user-12l2dpj.cable.mindspring.com. [69.81.55.51]) by smtp.gmail.com with ESMTPSA id e84sm11878453ill.60.2020.08.03.17.56.24 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 03 Aug 2020 17:56:25 -0700 (PDT) From: Eric Sunshine To: git@vger.kernel.org Cc: Duy Nguyen , Junio C Hamano , Taylor Blau , =?UTF-8?q?Martin=20=C3=85gren?= , Eric Sunshine Subject: [PATCH v2 0/5] git-worktree documentation cleanups Date: Mon, 3 Aug 2020 20:55:30 -0400 Message-Id: <20200804005535.5126-1-sunshine@sunshineco.com> X-Mailer: git-send-email 2.28.0.236.gb10cc79966 In-Reply-To: <20200803053612.50095-1-sunshine@sunshineco.com> References: <20200803053612.50095-1-sunshine@sunshineco.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org This is a re-roll of [1] which fixes some problems I ran across in the git-worktree documentation while working on another worktree-related topic. This version adds some `linkgit:` invocations, typesets `HEAD` as fixed-width, and covers a few additional places where backticks should have been applied in place of other quotes, as suggested by Martin[2], as well as a few more I noticed beyond those found by him. Although I had planned on adding backticks around `HEAD` in a separate patch, I ended up folding that change into patch 1 since there are relatively few such instances, and since, upon reflection, such a change didn't seem to warrant its own patch. I omitted Taylor's Reviewed-by:[4] since the patches have changed since he reviewed them, but he's welcome to give it again. [1]: https://lore.kernel.org/git/20200803053612.50095-1-sunshine@sunshineco.com/ [2]: https://lore.kernel.org/git/20200803175717.7465-1-martin.agren@gmail.com/ [3]: https://lore.kernel.org/git/CAPig+cQtcxqQDAQ5bO6ica+Z7dd2+r8B+kXm0RK7qhpsAiX_xg@mail.gmail.com/ [4]: https://lore.kernel.org/git/20200803161102.GB50799@syl.lan/ Eric Sunshine (5): git-worktree.txt: employ fixed-width typeface consistently git-worktree.txt: consistently use term "working tree" git-worktree.txt: fix minor grammatical issues git-worktree.txt: make start of new sentence more obvious git-wortkree.txt: link to man pages when citing other Git commands Documentation/git-worktree.txt | 123 +++++++++++++++++---------------- 1 file changed, 62 insertions(+), 61 deletions(-) Interdiff against v1: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 260bfe9105..6ee6ec7982 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -25,8 +25,9 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by "git -init" or "git clone". A repository has one main working tree (if it's not a +"linked working tree" as opposed to the "main working tree" prepared by +linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main working tree (if it's not a bare repository) and zero or more linked working trees. When you are done with a linked working tree, remove it with `git worktree remove`. @@ -48,7 +49,7 @@ add []:: Create `` and checkout `` into it. The new working directory is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. As a convenience, +directory specific files such as `HEAD`, `index`, etc. As a convenience, `` may be a bare "`-`", which is synonymous with `@{-1}`. + If `` is a branch name (call it ``) and is not found, @@ -66,13 +67,13 @@ one for the purposes of disambiguation, even if the `` isn't unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` to always checkout remote branches from there if `` is ambiguous but exists on the -'origin' remote. See also `checkout.defaultRemote` in +`origin` remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + If `` is omitted and neither `-b` nor `-B` nor `--detach` used, then, as a convenience, the new working tree is associated with a branch (call it ``) named after `$(basename )`. If `` -doesn't exist, a new branch based on HEAD is automatically created as +doesn't exist, a new branch based on `HEAD` is automatically created as if `-b ` was given. If `` does exist, it will be checked out in the new working tree, if it's not checked out anywhere else, otherwise the command will refuse to create the working tree (unless @@ -137,13 +138,13 @@ To remove a locked working tree, specify `--force` twice. -B :: With `add`, create a new branch named `` starting at ``, and check out `` into the new working tree. - If `` is omitted, it defaults to HEAD. + If `` is omitted, it defaults to `HEAD`. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `` to ``. --detach:: - With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" + With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: @@ -154,7 +155,7 @@ To remove a locked working tree, specify `--force` twice. --[no-]guess-remote:: With `worktree add `, without ``, instead - of creating a new branch from HEAD, if there exists a tracking + of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of ``, base the new branch on the remote-tracking branch, and mark the remote-tracking branch as "upstream" from the new branch. @@ -166,7 +167,7 @@ This can also be set up as the default behaviour by using the When creating a new branch, if `` is a branch, mark it as "upstream" from the new branch. This is the default if `` is a remote-tracking branch. See - "--track" in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. --lock:: Keep the working tree locked after creation. This is the @@ -185,14 +186,14 @@ This can also be set up as the default behaviour by using the -q:: --quiet:: - With 'add', suppress feedback messages. + With `add`, suppress feedback messages. -v:: --verbose:: With `prune`, report all removals. --expire