@matheusbsbs / matheus-bagliano / commits / 227c4f33a0

doc: add a blank line around block delimiters

The documentation is using the historical mode for titles, which is a setext-style (i.e., two-line) section title. The issue with this mode is that starting block delimiters (e.g., `----`) can be confused with a section title when they are exactly the same length as the preceding line. In the original documentation, this is taken care of for English by the writer, but it is not the case for translations where these delimiters are hidden. A translator can generate a line that is exactly the same length as the following block delimiter, which leads to this line being considered as a title. To safeguard against this issue, add a blank line before and after block delimiters where block is at root level, else add a "+" line before block delimiters to link it to the preceding paragraph. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jean-Noël Avila committed Mar 9, 2025 at 19:45 UTC 227c4f33a0351d12b04660a9f03ca96dbab1310a

17 files changed +73 -11

Documentation/MyFirstContribution.adoc

@@ -367,6 +367,7 @@ But as we drill down, we can find that `status_init_config()` wraps a call

367 to `git_config()`. Let's modify the code we wrote in the previous commit.

368

369 Be sure to include the header to allow you to use `struct wt_status`:

370 +

371 ----

372 #include "wt-status.h"

373 ----

Documentation/MyFirstObjectWalk.adoc

@@ -287,6 +287,7 @@ static void final_rev_info_setup(struct rev_info *rev)

287 ====

288 Instead of using the shorthand `add_head_to_pending()`, you could do

289 something like this:

290 +

291 ----

292 struct setup_revision_opt opt;

293

@@ -295,6 +296,7 @@ something like this:

296 opt.revarg_opt = REVARG_COMMITTISH;

297 setup_revisions(argc, argv, rev, &opt);

298 ----

299 +

300 Using a `setup_revision_opt` gives you finer control over your walk's starting

301 point.

302 ====

Documentation/ToolsForGit.adoc

@@ -34,6 +34,7 @@ This is adapted from Linux's suggestion in its CodingStyle document:

35 - To follow the rules in CodingGuidelines, it's useful to put the following in

36 GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:

37 +

38 ----

39 ;; note the first part is useful for C editing, too

40 ((nil . ((indent-tabs-mode . t)

Documentation/git-bisect.adoc

@@ -495,6 +495,7 @@ $ git bisect old HEAD~10 # the tenth commit from now is marked as old

495 ------------

496 +

497 or:

498 ++

499 ------------

500 $ git bisect start --term-old broken --term-new fixed

501 $ git bisect fixed

Documentation/git-cat-file.adoc

+2 -2

@@ -322,10 +322,10 @@ of `%(objectsize)` bytes), followed by a newline.

322

323 For example, `--batch` without a custom format would produce:

324

325 -------------

325 +-----------

326 <oid> SP <type> SP <size> LF

327 <contents> LF

328 -------------

328 +-----------

329

330 Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:

331

Documentation/git-check-attr.adoc

@@ -76,6 +76,7 @@ EXAMPLES

76 --------

78 In the examples, the following '.gitattributes' file is used:

79 +

80 ---------------

81 *.java diff=java -crlf myAttr

82 NoMyAttr.java !myAttr

@@ -83,12 +84,14 @@ README caveat=unspecified

84 ---------------

86 * Listing a single attribute:

87 ++

88 ---------------

89 $ git check-attr diff org/example/MyClass.java

90 org/example/MyClass.java: diff: java

91 ---------------

93 * Listing multiple attributes for a file:

94 ++

95 ---------------

96 $ git check-attr crlf diff myAttr -- org/example/MyClass.java

97 org/example/MyClass.java: crlf: unset

@@ -97,6 +100,7 @@ org/example/MyClass.java: myAttr: set

100 ---------------

101

102 * Listing all attributes for a file:

103 ++

104 ---------------

105 $ git check-attr --all -- org/example/MyClass.java

106 org/example/MyClass.java: diff: java

@@ -104,6 +108,7 @@ org/example/MyClass.java: myAttr: set

108 ---------------

109

110 * Listing an attribute for multiple files:

111 ++

112 ---------------

113 $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java

114 org/example/MyClass.java: myAttr: set

@@ -111,6 +116,7 @@ org/example/NoMyAttr.java: myAttr: unspecified

116 ---------------

117

118 * Not all values are equally unambiguous:

119 ++

120 ---------------

121 $ git check-attr caveat README

122 README: caveat: unspecified

Documentation/git-column.adoc

@@ -50,6 +50,7 @@ EXAMPLES

50 --------

52 Format data by columns:

53 ++

54 ------------

55 $ seq 1 24 | git column --mode=column --padding=5

56 1 4 7 10 13 16 19 22

@@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5

59 ------------

61 Format data by rows:

62 ++

63 ------------

64 $ seq 1 21 | git column --mode=row --padding=5

65 1 2 3 4 5 6 7

@@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5

68 ------------

70 List some tags in a table with unequal column widths:

71 ++

72 ------------

73 $ git tag --list 'v2.4.*' --column=row,dense

74 v2.4.0 v2.4.0-rc0 v2.4.0-rc1 v2.4.0-rc2 v2.4.0-rc3

Documentation/git-cvsserver.adoc

@@ -125,9 +125,11 @@ creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or

125 pwhash in NetBSD) and paste it in the right location.

126

127 Then provide your password via the pserver method, for example:

128 +

129 ------

130 cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name>

131 ------

132 +

133 No special setup is needed for SSH access, other than having Git tools

134 in the PATH. If you have clients that do not accept the CVS_SERVER

135 environment variable, you can rename 'git-cvsserver' to `cvs`.

@@ -138,6 +140,7 @@ CVS_SERVER directly in CVSROOT like

140 ------

141 cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>

142 ------

143 +

144 This has the advantage that it will be saved in your 'CVS/Root' files and

145 you don't need to worry about always setting the correct environment

146 variable. SSH users restricted to 'git-shell' don't need to override the default

@@ -168,6 +171,7 @@ All configuration variables can also be overridden for a specific method of

171 access. Valid method names are "ext" (for SSH access) and "pserver". The

172 following example configuration would disable pserver access while still

173 allowing access over SSH.

174 +

175 ------

176 [gitcvs]

177 enabled=0

Documentation/git-for-each-ref.adoc

@@ -441,6 +441,7 @@ Ref: %(*refname)

441

442 A simple example showing the use of shell eval on the output,

443 demonstrating the use of --shell. List the prefixes of all heads:

444 +

445 ------------

446 #!/bin/sh

447

@@ -455,6 +456,7 @@ done

456

457 A bit more elaborate report on tags, demonstrating that the format

458 may be an entire script:

459 +

460 ------------

461 #!/bin/sh

462

Documentation/git-p4.adoc

+14

@@ -80,6 +80,7 @@ This:

81 To reproduce the entire p4 history in Git, use the '@all' modifier on

82 the depot path:

83 +

84 ------------

85 $ git p4 clone //depot/path/project@all

86 ------------

@@ -89,19 +90,23 @@ Sync

90 ~~~~

91 As development continues in the p4 repository, those changes can

92 be included in the Git repository using:

93 +

94 ------------

95 $ git p4 sync

96 ------------

97 +

98 This command finds new changes in p4 and imports them as Git commits.

100 P4 repositories can be added to an existing Git repository using

101 'git p4 sync' too:

102 +

103 ------------

104 $ mkdir repo-git

105 $ cd repo-git

106 $ git init

107 $ git p4 sync //path/in/your/perforce/depot

108 ------------

109 +

110 This imports the specified depot into

111 'refs/remotes/p4/master' in an existing Git repository. The

112 `--branch` option can be used to specify a different branch to

@@ -125,6 +130,7 @@ and merge them with local uncommitted changes. Often, the p4 repository

130 is the ultimate location for all code, thus a rebase workflow makes

131 sense. This command does 'git p4 sync' followed by 'git rebase' to move

132 local commits on top of updated p4 changes.

133 +

134 ------------

135 $ git p4 rebase

136 ------------

@@ -140,16 +146,19 @@ will be created and populated if it does not already exist.

146

147 To submit all changes that are in the current Git branch but not in

148 the 'p4/master' branch, use:

149 +

150 ------------

151 $ git p4 submit

152 ------------

153

154 To specify a branch other than the current one, use:

155 +

156 ------------

157 $ git p4 submit topicbranch

158 ------------

159

160 To specify a single commit or a range of commits, use:

161 +

162 ------------

163 $ git p4 submit --commit <sha1>

164 $ git p4 submit --commit <sha1..sha1>

@@ -510,20 +519,24 @@ when cloning or syncing to have 'git p4' automatically find

519 subdirectories in p4, and to generate these as branches in Git.

520

521 For example, if the P4 repository structure is:

522 +

523 ----

524 //depot/main/...

525 //depot/branch1/...

526 ----

527

528 And "p4 branch -o branch1" shows a View line that looks like:

529 +

530 ----

531 //depot/main/... //depot/branch1/...

532 ----

533

534 Then this 'git p4 clone' command:

535 +

536 ----

537 git p4 clone --detect-branches //depot@all

538 ----

539 +

540 produces a separate branch in 'refs/remotes/p4/' for //depot/main,

541 called 'master', and one for //depot/branch1 called 'depot/branch1'.

542

@@ -536,6 +549,7 @@ simple p4 branch specification, where the "source" and "destination" are

549 the path elements in the p4 repository. The example above relied on the

550 presence of the p4 branch. Without p4 branches, the same result will

551 occur with:

552 +

553 ----

554 git init depot

555 cd depot

Documentation/git-rebase.adoc

@@ -1107,10 +1107,12 @@ In that case, the fix is easy because 'git rebase' knows to skip

1107 changes that are already present in the new upstream (unless

1108 `--reapply-cherry-picks` is given). So if you say

1109 (assuming you're on 'topic')

1110 +

1111 ------------

1112 $ git rebase subsystem

1113 ------------

1114 you will end up with the fixed history

1115 +

1116 ------------

1117 o---o---o---o---o---o---o---o master

1118 \

@@ -1145,6 +1147,7 @@ of the old 'subsystem', for example:

1147

1148 You can then transplant the old `subsystem..topic` to the new tip by

1149 saying (for the reflog case, and assuming you are on 'topic' already):

1150 +

1151 ------------

1152 $ git rebase --onto subsystem subsystem@{1}

1153 ------------

Documentation/gitattributes.adoc

+16 -8

@@ -531,13 +531,14 @@ must not send any response before it received the content and the

531 final flush packet. Also note that the "value" of a "key=value" pair

532 can contain the "=" character whereas the key would never contain

533 that character.

534 -------------------------

534 +

535 +-----------------------

536 packet: git> command=smudge

537 packet: git> pathname=path/testfile.dat

538 packet: git> 0000

539 packet: git> CONTENT

540 packet: git> 0000

540 -------------------------

541 +-----------------------

542

543 The filter is expected to respond with a list of "key=value" pairs

544 terminated with a flush packet. If the filter does not experience

@@ -559,6 +560,7 @@ packet: git< 0000 # empty list, keep "status=success" unchanged!

560

561 If the result content is empty then the filter is expected to respond

562 with a "success" status and a flush packet to signal the empty content.

563 +

564 ------------------------

565 packet: git< status=success

566 packet: git< 0000

@@ -568,14 +570,16 @@ packet: git< 0000 # empty list, keep "status=success" unchanged!

570

571 In case the filter cannot or does not want to process the content,

572 it is expected to respond with an "error" status.

571 -------------------------

573 +

574 +-----------------------

575 packet: git< status=error

576 packet: git< 0000

574 -------------------------

577 +-----------------------

578

579 If the filter experiences an error during processing, then it can

580 send the status "error" after the content was (partially or

581 completely) sent.

582 +

583 ------------------------

584 packet: git< status=success

585 packet: git< 0000

@@ -589,10 +593,11 @@ In case the filter cannot or does not want to process the content

593 as well as any future content for the lifetime of the Git process,

594 then it is expected to respond with an "abort" status at any point

595 in the protocol.

592 -------------------------

596 +

597 +-----------------------

598 packet: git< status=abort

599 packet: git< 0000

595 -------------------------

600 +-----------------------

601

602 Git neither stops nor restarts the filter process in case the

603 "error"/"abort" status is set. However, Git sets its exit code

@@ -613,7 +618,8 @@ flag "can-delay" after the filter command and pathname. This flag

618 denotes that the filter can delay filtering the current blob (e.g. to

619 compensate network latencies) by responding with no content but with

620 the status "delayed" and a flush packet.

616 -------------------------

621 +

622 +-----------------------

623 packet: git> command=smudge

624 packet: git> pathname=path/testfile.dat

625 packet: git> can-delay=1

@@ -622,7 +628,7 @@ packet: git> CONTENT

628 packet: git> 0000

629 packet: git< status=delayed

630 packet: git< 0000

625 -------------------------

631 +-----------------------

632

633 If the filter supports the "delay" capability then it must support the

634 "list_available_blobs" command. If Git sends this command, then the

@@ -647,10 +653,12 @@ packet: git< status=success

653 packet: git< 0000

654 ------------------------

655

656 +

657 After Git received the pathnames, it will request the corresponding

658 blobs again. These requests contain a pathname and an empty content

659 section. The filter is expected to respond with the smudged content

660 in the usual way as explained above.

661 +

662 ------------------------

663 packet: git> command=smudge

664 packet: git> pathname=path/testfile.dat

Documentation/gitcli.adoc

+1 -1

@@ -209,13 +209,13 @@ $ git foo -o Arg

209

210 However, this is *NOT* allowed for switches with an optional value, where the

211 'stuck' form must be used:

212 +

213 ----------------------------

214 $ git describe --abbrev HEAD # correct

215 $ git describe --abbrev=10 HEAD # correct

216 $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT

217 ----------------------------

218

218 -

219 NOTES ON FREQUENTLY CONFUSED OPTIONS

220 ------------------------------------

221

Documentation/gitprotocol-common.adoc

@@ -21,11 +21,13 @@ ABNF Notation

22 ABNF notation as described by RFC 5234 is used within the protocol documents,

23 except the following replacement core rules are used:

24 +

25 ----

26 HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"

27 ----

29 We also define the following common rules:

30 +

31 ----

32 NUL = %x00

33 zero-id = 40*"0"

Documentation/gitweb.adoc

+11

@@ -103,6 +103,7 @@ You can generate the projects list index file using the project_index action

103 "Generating projects list using gitweb" section below.

104

105 Example contents:

106 +

107 -----------------------------------------------------------------------

108 foo.git Joe+R+Hacker+<joe@example.com>

109 foo/bar.git O+W+Ner+<owner@example.org>

@@ -124,6 +125,7 @@ Generating projects list using gitweb

125

126 We assume that GITWEB_CONFIG has its default Makefile value, namely

127 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:

128 +

129 ----------------------------------------------------------------------------

130 read_config_file("gitweb_config.perl");

131 $projects_list = $projectroot;

@@ -518,12 +520,14 @@ rules.

520 If you use the rewrite rules from the example you *might* also need

521 something like the following in your gitweb configuration file

522 (`/etc/gitweb.conf` following example):

523 +

524 ----------------------------------------------------------------------------

525 @stylesheets = ("/some/absolute/path/gitweb.css");

526 $my_uri = "/";

527 $home_link = "/";

528 $per_request_config = 1;

529 ----------------------------------------------------------------------------

530 +

531 Nowadays though gitweb should create HTML base tag when needed (to set base

532 URI for relative links), so it should work automatically.

533

@@ -535,6 +539,7 @@ Apache virtual host and gitweb configuration files in the following way.

539

540 The virtual host configuration (in Apache configuration file) should look

541 like this:

542 +

543 --------------------------------------------------------------------------

544 <VirtualHost *:80>

545 ServerName git.example.org

@@ -575,9 +580,11 @@ like this:

580 Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`

581 environment variable from a web server, so you need to put the following

582 line in gitweb configuration file (`/etc/gitweb.conf` in above example):

583 +

584 --------------------------------------------------------------------------

585 $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";

586 --------------------------------------------------------------------------

587 +

588 *Note* that this requires to be set for each request, so either

589 `$per_request_config` must be false, or the above must be put in code

590 referenced by `$per_request_config`;

@@ -604,9 +611,11 @@ the third and the fourth.

611 PATH_INFO usage

612 ~~~~~~~~~~~~~~~

613 If you enable PATH_INFO usage in gitweb by putting

614 +

615 ----------------------------------------------------------------------------

616 $feature{'pathinfo'}{'default'} = [1];

617 ----------------------------------------------------------------------------

618 +

619 in your gitweb configuration file, it is possible to set up your server so

620 that it consumes and produces URLs in the form

621

@@ -636,6 +645,7 @@ complementary static files (stylesheet, favicon, JavaScript):

645 </Directory>

646 </VirtualHost>

647 ----------------------------------------------------------------------------

648 +

649 The rewrite rule guarantees that existing static files will be properly

650 served, whereas any other URL will be passed to gitweb as PATH_INFO

651 parameter.

@@ -647,6 +657,7 @@ for fetching" section). A possible workaround for the latter is the

657 following: in your project root dir (e.g. `/pub/git`) have the projects

658 named *without* a .git extension (e.g. `/pub/git/project` instead of

659 `/pub/git/project.git`) and configure Apache as follows:

660 +

661 ----------------------------------------------------------------------------

662 <VirtualHost *:80>

663 ServerAlias git.example.com

Documentation/gitweb.conf.adoc

@@ -603,6 +603,7 @@ Many gitweb features can be enabled (or disabled) and configured using the

603

604 Each `%feature` hash element is a hash reference and has the following

605 structure:

606 +

607 ----------------------------------------------------------------------

608 "<feature-name>" => {

609 "sub" => <feature-sub-(subroutine)>,

@@ -613,6 +614,7 @@ structure:

614 Some features cannot be overridden per project. For those

615 features the structure of appropriate `%feature` hash element has a simpler

616 form:

617 +

618 ----------------------------------------------------------------------

619 "<feature-name>" => {

620 "override" => 0,

Documentation/rev-list-options.adoc

@@ -429,6 +429,7 @@ filtered for `foo`, they look different and equal, respectively.)

429 In the following, we will always refer to the same example history to

430 illustrate the differences between simplification settings. We assume

431 that you are filtering for a file `foo` in this commit graph:

432 +

433 -----------------------------------------------------------------------

434 .-A---M---N---O---P---Q

435 / / / / / /

@@ -436,6 +437,7 @@ that you are filtering for a file `foo` in this commit graph:

437 \ / / / / /

438 `-------------' X

439 -----------------------------------------------------------------------

440 +

441 The horizontal line of history A---Q is taken to be the first parent of

442 each merge. The commits are:

443