From patchwork Sun Mar 24 22:18:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13600980 Received: from mail-wm1-f45.google.com (mail-wm1-f45.google.com [209.85.128.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A5B573FB8B for ; Sun, 24 Mar 2024 22:19:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318750; cv=none; b=pverTlPQ5o3njkajWYwEEDSeLVqSbNElvwFYvosJKbUJyP0/sdH5mDFe/3plPCyIUq+axzaplsDI3Yd1tQdDtUj6yYTy84QohcK3Z8OFygIiZdwAk0crvCYZXi65p1J6g5Ry5iXWCs4oTsuL8Y0OR5J+SFZxwACkYDLZX6tzdUo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318750; c=relaxed/simple; bh=J5PS/X3TltXwi6QdB1XA2pR31RkPq3mNfuGVmC0vY5A=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=p6VZcSltqgag4N/upXoDYem0Cy3dSn6qK+dHCpl7jcD8M9R+S6mO7mMngrKvgV8KFVkYgHjNXxYyyrqpxSkXq0Jpq4q020Td9uPuKsqGIZDbosM4NRYRtulGEGxaNTD+UghuzX/fDc9hloqQPobr1egiHNb3bLMkPEGl6qyrh8Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Sc6+XY8s; arc=none smtp.client-ip=209.85.128.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Sc6+XY8s" Received: by mail-wm1-f45.google.com with SMTP id 5b1f17b1804b1-41485fe355bso4547625e9.1 for ; Sun, 24 Mar 2024 15:19:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711318746; x=1711923546; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=75/8iULr/DRxQooUD8kC6xKdPlg68sjU5vMp4oHaDU0=; b=Sc6+XY8sV6sCjejAIUBvcViPtApmnKmy+uHPp9i5X8QIykv3AzD5IhShrgiMhpGLeh otH52f6dBh8azuHGfY5whi718i5ptSJTDyprhtjwBA/rQPQa0lcDkn8RRhFqhMa53PG+ GA+Ybgt3RGGGGB+rCOWuZlDQvUzf8FBNwaBRLQWhUKf59eIgS4vWVr2kxzF0T60KJZtP 1r4+ucXr+FxtwK1kcQAznKONSJ1plN6ovWrqQ7cdIQaS5q6jo1735Y4M+Fxu+WDA80LL fon34DPy2S/1B6rYFcK4dxQ2O7AQ/XqbfNIVhWfV7nWfUCOGLZEGuOsLb9wUBHa4z6uk BLeQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711318746; x=1711923546; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=75/8iULr/DRxQooUD8kC6xKdPlg68sjU5vMp4oHaDU0=; b=VFQ/FS4+DVIOiGPWGsEl+uvyFJldgp4hsCEIww5iRpByB9xRtrS0x4z35MMbTw8Ojn ahS7KBnDIOh1NsQSFo4Y+Pn8TK9sJoAJadA65AUxueiwrzQ7JuTIR442qsJkh9jrIfWg GtApEbombFris51ZhuY4/y9BTA89eDtkW97CQ5PxQLIdPm1pl+5VopSlWj33VU1DznaZ X9Zf3bR6JJrM9HnBz8qyol9NLzI9hp6yrEgemForaXoN8/e/WmYnxNVFJp8Mo/wbCDhb /2YsdJE30m6IueslfhQ7eEhVsIc3vB8A6H9FGKrjUeu5VMvCNWUc/MmCKgJKubyjgoou OMSA== X-Gm-Message-State: AOJu0Yy4ewlb36Rn/0inlZ+RayCLCT2gzknc2L33HU3RX9MIu887cd2p Oa3iyq0+UjMEXZlaSEAj4lIFygK7xn4GRfMFFvMTX052qXJnZRzVFctCyyg4 X-Google-Smtp-Source: AGHT+IEqEzje8sfJOWmsU8112SNTWhDIIveL4j6u7IGuGc0azGftZI/GbLgiKVZkiVtx+KlXh04r0Q== X-Received: by 2002:a05:600c:1d08:b0:413:3941:d9ae with SMTP id l8-20020a05600c1d0800b004133941d9aemr3432498wms.31.1711318746226; Sun, 24 Mar 2024 15:19:06 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m29-20020a05600c3b1d00b004147b5dd6f8sm6392917wms.9.2024.03.24.15.19.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Mar 2024 15:19:04 -0700 (PDT) Message-Id: <5ae83d3f799e9ab84d5233f77cb91715415ae167.1711318740.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 24 Mar 2024 22:18:59 +0000 Subject: [PATCH 4/4] doc: git-clone: apply new documentation guidelines Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Heavily apply literal and placeholder markup everywhere. Signed-off-by: Jean-Noël Avila --- Documentation/config/clone.txt | 23 +++++-- Documentation/git-clone.txt | 120 ++++++++++++++++----------------- Documentation/urls.txt | 22 +++--- 3 files changed, 88 insertions(+), 77 deletions(-) diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index d037b57f729..0e0a8a1ae4a 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,13 +1,22 @@ -clone.defaultRemoteName:: +`clone.defaultRemoteName`:: The name of the remote to create when cloning a repository. Defaults to - `origin`, and can be overridden by passing the `--origin` command-line + `origin`. +ifdef::git-clone[] + It can be overridden by passing the `--origin` command-line + option. +endif::[] +ifndef::git-clone[] + It can be overridden by passing the `--origin` command-line option to linkgit:git-clone[1]. +endif::[] +`clone.rejectShallow`:: + Reject cloning a repository if it is a shallow one. This can be overridden by + passing the `--reject-shallow` option on the command line. +ifndef::git-clone[] + See linkgit:git-clone[1] +endif::[] -clone.rejectShallow:: - Reject cloning a repository if it is a shallow one; this can be overridden by - passing the `--reject-shallow` option on the command line. See linkgit:git-clone[1] - -clone.filterSubmodules:: +`clone.filterSubmodules`:: If a partial clone filter is provided (see `--filter` in linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply the filter to submodules. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f90977a8519..134b5278ca1 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,15 +9,15 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=] - [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] - [-o ] [-b ] [-u ] [--reference ] - [--dissociate] [--separate-git-dir ] - [--depth ] [--[no-]single-branch] [--no-tags] - [--recurse-submodules[=]] [--[no-]shallow-submodules] - [--[no-]remote-submodules] [--jobs ] [--sparse] [--[no-]reject-shallow] - [--filter= [--also-filter-submodules]] [--] - [] +`git clone` [`--template=`{empty}____] + [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] + [`-o` __] [`-b` __] [`-u` __] [`--reference` __] + [`--dissociate`] [`--separate-git-dir` __] + [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`] + [`--recurse-submodules`[`=`{empty}____]] [`--`[`no-`]`shallow-submodules`] + [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`] + [`--filter=`{empty}____] [`--also-filter-submodules`]] [`--`] __ + [__] DESCRIPTION ----------- @@ -31,7 +31,7 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when "--single-branch" +current master branch, if any (this is untrue when `--single-branch` is given; see below). This default configuration is achieved by creating references to @@ -42,12 +42,12 @@ configuration variables. OPTIONS ------- --l:: ---local:: +`-l`:: +`--local`:: When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of - HEAD and everything under objects and refs directories. + `HEAD` and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked to save space when possible. + @@ -67,14 +67,14 @@ links. source repository, similar to running `cp -r src dst` while modifying `src`. ---no-hardlinks:: +`--no-hardlinks`:: Force the cloning process from a repository on a local filesystem to copy the files under the `.git/objects` directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. --s:: ---shared:: +`-s`:: +`--shared`:: When the repository to clone is on the local machine, instead of using hard links, automatically setup `.git/objects/info/alternates` to share the objects @@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. ---reference[-if-able] :: +`--reference`[`-if-able`] __:: If the reference __ is on the local machine, automatically setup `.git/objects/info/alternates` to obtain objects from the reference __. Using @@ -115,7 +115,7 @@ objects from the source repository into a pack in the cloned repository. *NOTE*: see the NOTE for the `--shared` option, and also the `--dissociate` option. ---dissociate:: +`--dissociate`:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network transfer, and stop borrowing from them after a clone is made @@ -126,43 +126,43 @@ objects from the source repository into a pack in the cloned repository. same repository, and this option can be used to stop the borrowing. --q:: ---quiet:: +`-q`:: +`--quiet`:: Operate quietly. Progress is not reported to the standard error stream. --v:: ---verbose:: +`-v`:: +`--verbose`:: Run verbosely. Does not affect the reporting of progress status to the standard error stream. ---progress:: +`--progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---server-option=