From 5ec6074f0633939fd17d94111d10c6c6b062978c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 11:49:36 +0200 Subject: Adding upstream version 1:2.30.2. Signed-off-by: Daniel Baumann --- Documentation/.gitattributes | 1 + Documentation/.gitignore | 17 + Documentation/CodingGuidelines | 640 +++ Documentation/Makefile | 479 ++ Documentation/MyFirstContribution.txt | 1232 ++++++ Documentation/MyFirstObjectWalk.txt | 870 ++++ Documentation/RelNotes/1.5.0.1.txt | 42 + Documentation/RelNotes/1.5.0.2.txt | 65 + Documentation/RelNotes/1.5.0.3.txt | 58 + Documentation/RelNotes/1.5.0.4.txt | 22 + Documentation/RelNotes/1.5.0.5.txt | 26 + Documentation/RelNotes/1.5.0.6.txt | 21 + Documentation/RelNotes/1.5.0.7.txt | 18 + Documentation/RelNotes/1.5.0.txt | 469 ++ Documentation/RelNotes/1.5.1.1.txt | 65 + Documentation/RelNotes/1.5.1.2.txt | 50 + Documentation/RelNotes/1.5.1.3.txt | 45 + Documentation/RelNotes/1.5.1.4.txt | 30 + Documentation/RelNotes/1.5.1.5.txt | 42 + Documentation/RelNotes/1.5.1.6.txt | 45 + Documentation/RelNotes/1.5.1.txt | 371 ++ Documentation/RelNotes/1.5.2.1.txt | 47 + Documentation/RelNotes/1.5.2.2.txt | 61 + Documentation/RelNotes/1.5.2.3.txt | 27 + Documentation/RelNotes/1.5.2.4.txt | 28 + Documentation/RelNotes/1.5.2.5.txt | 30 + Documentation/RelNotes/1.5.2.txt | 197 + Documentation/RelNotes/1.5.3.1.txt | 10 + Documentation/RelNotes/1.5.3.2.txt | 58 + Documentation/RelNotes/1.5.3.3.txt | 31 + Documentation/RelNotes/1.5.3.4.txt | 35 + Documentation/RelNotes/1.5.3.5.txt | 94 + Documentation/RelNotes/1.5.3.6.txt | 48 + Documentation/RelNotes/1.5.3.7.txt | 45 + Documentation/RelNotes/1.5.3.8.txt | 25 + Documentation/RelNotes/1.5.3.txt | 366 ++ Documentation/RelNotes/1.5.4.1.txt | 17 + Documentation/RelNotes/1.5.4.2.txt | 43 + Documentation/RelNotes/1.5.4.3.txt | 27 + Documentation/RelNotes/1.5.4.4.txt | 66 + Documentation/RelNotes/1.5.4.5.txt | 56 + Documentation/RelNotes/1.5.4.6.txt | 43 + Documentation/RelNotes/1.5.4.7.txt | 10 + Documentation/RelNotes/1.5.4.txt | 377 ++ Documentation/RelNotes/1.5.5.1.txt | 44 + Documentation/RelNotes/1.5.5.2.txt | 27 + Documentation/RelNotes/1.5.5.3.txt | 12 + Documentation/RelNotes/1.5.5.4.txt | 7 + Documentation/RelNotes/1.5.5.5.txt | 11 + Documentation/RelNotes/1.5.5.6.txt | 10 + Documentation/RelNotes/1.5.5.txt | 207 + Documentation/RelNotes/1.5.6.1.txt | 28 + Documentation/RelNotes/1.5.6.2.txt | 40 + Documentation/RelNotes/1.5.6.3.txt | 52 + Documentation/RelNotes/1.5.6.4.txt | 47 + Documentation/RelNotes/1.5.6.5.txt | 29 + Documentation/RelNotes/1.5.6.6.txt | 10 + Documentation/RelNotes/1.5.6.txt | 115 + Documentation/RelNotes/1.6.0.1.txt | 36 + Documentation/RelNotes/1.6.0.2.txt | 81 + Documentation/RelNotes/1.6.0.3.txt | 117 + Documentation/RelNotes/1.6.0.4.txt | 39 + Documentation/RelNotes/1.6.0.5.txt | 56 + Documentation/RelNotes/1.6.0.6.txt | 33 + Documentation/RelNotes/1.6.0.txt | 258 ++ Documentation/RelNotes/1.6.1.1.txt | 59 + Documentation/RelNotes/1.6.1.2.txt | 39 + Documentation/RelNotes/1.6.1.3.txt | 28 + Documentation/RelNotes/1.6.1.4.txt | 41 + Documentation/RelNotes/1.6.1.txt | 280 ++ Documentation/RelNotes/1.6.2.1.txt | 19 + Documentation/RelNotes/1.6.2.2.txt | 45 + Documentation/RelNotes/1.6.2.3.txt | 22 + Documentation/RelNotes/1.6.2.4.txt | 39 + Documentation/RelNotes/1.6.2.5.txt | 21 + Documentation/RelNotes/1.6.2.txt | 164 + Documentation/RelNotes/1.6.3.1.txt | 10 + Documentation/RelNotes/1.6.3.2.txt | 61 + Documentation/RelNotes/1.6.3.3.txt | 38 + Documentation/RelNotes/1.6.3.4.txt | 36 + Documentation/RelNotes/1.6.3.txt | 182 + Documentation/RelNotes/1.6.4.1.txt | 46 + Documentation/RelNotes/1.6.4.2.txt | 32 + Documentation/RelNotes/1.6.4.3.txt | 29 + Documentation/RelNotes/1.6.4.4.txt | 26 + Documentation/RelNotes/1.6.4.5.txt | 20 + Documentation/RelNotes/1.6.4.txt | 147 + Documentation/RelNotes/1.6.5.1.txt | 20 + Documentation/RelNotes/1.6.5.2.txt | 19 + Documentation/RelNotes/1.6.5.3.txt | 63 + Documentation/RelNotes/1.6.5.4.txt | 32 + Documentation/RelNotes/1.6.5.5.txt | 49 + Documentation/RelNotes/1.6.5.6.txt | 23 + Documentation/RelNotes/1.6.5.7.txt | 19 + Documentation/RelNotes/1.6.5.8.txt | 28 + Documentation/RelNotes/1.6.5.9.txt | 18 + Documentation/RelNotes/1.6.5.txt | 169 + Documentation/RelNotes/1.6.6.1.txt | 37 + Documentation/RelNotes/1.6.6.2.txt | 46 + Documentation/RelNotes/1.6.6.3.txt | 23 + Documentation/RelNotes/1.6.6.txt | 224 + Documentation/RelNotes/1.7.0.1.txt | 35 + Documentation/RelNotes/1.7.0.2.txt | 40 + Documentation/RelNotes/1.7.0.3.txt | 34 + Documentation/RelNotes/1.7.0.4.txt | 27 + Documentation/RelNotes/1.7.0.5.txt | 26 + Documentation/RelNotes/1.7.0.6.txt | 13 + Documentation/RelNotes/1.7.0.7.txt | 16 + Documentation/RelNotes/1.7.0.8.txt | 10 + Documentation/RelNotes/1.7.0.9.txt | 8 + Documentation/RelNotes/1.7.0.txt | 214 + Documentation/RelNotes/1.7.1.1.txt | 96 + Documentation/RelNotes/1.7.1.2.txt | 28 + Documentation/RelNotes/1.7.1.3.txt | 10 + Documentation/RelNotes/1.7.1.4.txt | 8 + Documentation/RelNotes/1.7.1.txt | 89 + Documentation/RelNotes/1.7.10.1.txt | 78 + Documentation/RelNotes/1.7.10.2.txt | 85 + Documentation/RelNotes/1.7.10.3.txt | 43 + Documentation/RelNotes/1.7.10.4.txt | 29 + Documentation/RelNotes/1.7.10.5.txt | 12 + Documentation/RelNotes/1.7.10.txt | 219 + Documentation/RelNotes/1.7.11.1.txt | 9 + Documentation/RelNotes/1.7.11.2.txt | 53 + Documentation/RelNotes/1.7.11.3.txt | 53 + Documentation/RelNotes/1.7.11.4.txt | 31 + Documentation/RelNotes/1.7.11.5.txt | 36 + Documentation/RelNotes/1.7.11.6.txt | 84 + Documentation/RelNotes/1.7.11.7.txt | 46 + Documentation/RelNotes/1.7.11.txt | 139 + Documentation/RelNotes/1.7.12.1.txt | 134 + Documentation/RelNotes/1.7.12.2.txt | 40 + Documentation/RelNotes/1.7.12.3.txt | 34 + Documentation/RelNotes/1.7.12.4.txt | 23 + Documentation/RelNotes/1.7.12.txt | 136 + Documentation/RelNotes/1.7.2.1.txt | 25 + Documentation/RelNotes/1.7.2.2.txt | 22 + Documentation/RelNotes/1.7.2.3.txt | 39 + Documentation/RelNotes/1.7.2.4.txt | 10 + Documentation/RelNotes/1.7.2.5.txt | 8 + Documentation/RelNotes/1.7.2.txt | 151 + Documentation/RelNotes/1.7.3.1.txt | 14 + Documentation/RelNotes/1.7.3.2.txt | 5 + Documentation/RelNotes/1.7.3.3.txt | 54 + Documentation/RelNotes/1.7.3.4.txt | 45 + Documentation/RelNotes/1.7.3.5.txt | 34 + Documentation/RelNotes/1.7.3.txt | 76 + Documentation/RelNotes/1.7.4.1.txt | 27 + Documentation/RelNotes/1.7.4.2.txt | 58 + Documentation/RelNotes/1.7.4.3.txt | 32 + Documentation/RelNotes/1.7.4.4.txt | 35 + Documentation/RelNotes/1.7.4.5.txt | 4 + Documentation/RelNotes/1.7.4.txt | 156 + Documentation/RelNotes/1.7.5.1.txt | 47 + Documentation/RelNotes/1.7.5.2.txt | 57 + Documentation/RelNotes/1.7.5.3.txt | 32 + Documentation/RelNotes/1.7.5.4.txt | 21 + Documentation/RelNotes/1.7.5.txt | 132 + Documentation/RelNotes/1.7.6.1.txt | 63 + Documentation/RelNotes/1.7.6.2.txt | 8 + Documentation/RelNotes/1.7.6.3.txt | 24 + Documentation/RelNotes/1.7.6.4.txt | 32 + Documentation/RelNotes/1.7.6.5.txt | 26 + Documentation/RelNotes/1.7.6.6.txt | 16 + Documentation/RelNotes/1.7.6.txt | 136 + Documentation/RelNotes/1.7.7.1.txt | 60 + Documentation/RelNotes/1.7.7.2.txt | 44 + Documentation/RelNotes/1.7.7.3.txt | 19 + Documentation/RelNotes/1.7.7.4.txt | 14 + Documentation/RelNotes/1.7.7.5.txt | 14 + Documentation/RelNotes/1.7.7.6.txt | 20 + Documentation/RelNotes/1.7.7.7.txt | 13 + Documentation/RelNotes/1.7.7.txt | 134 + Documentation/RelNotes/1.7.8.1.txt | 38 + Documentation/RelNotes/1.7.8.2.txt | 71 + Documentation/RelNotes/1.7.8.3.txt | 16 + Documentation/RelNotes/1.7.8.4.txt | 23 + Documentation/RelNotes/1.7.8.5.txt | 19 + Documentation/RelNotes/1.7.8.6.txt | 22 + Documentation/RelNotes/1.7.8.txt | 161 + Documentation/RelNotes/1.7.9.1.txt | 63 + Documentation/RelNotes/1.7.9.2.txt | 69 + Documentation/RelNotes/1.7.9.3.txt | 51 + Documentation/RelNotes/1.7.9.4.txt | 24 + Documentation/RelNotes/1.7.9.5.txt | 23 + Documentation/RelNotes/1.7.9.6.txt | 12 + Documentation/RelNotes/1.7.9.7.txt | 13 + Documentation/RelNotes/1.7.9.txt | 112 + Documentation/RelNotes/1.8.0.1.txt | 64 + Documentation/RelNotes/1.8.0.2.txt | 34 + Documentation/RelNotes/1.8.0.3.txt | 14 + Documentation/RelNotes/1.8.0.txt | 267 ++ Documentation/RelNotes/1.8.1.1.txt | 87 + Documentation/RelNotes/1.8.1.2.txt | 25 + Documentation/RelNotes/1.8.1.3.txt | 47 + Documentation/RelNotes/1.8.1.4.txt | 11 + Documentation/RelNotes/1.8.1.5.txt | 47 + Documentation/RelNotes/1.8.1.6.txt | 39 + Documentation/RelNotes/1.8.1.txt | 241 ++ Documentation/RelNotes/1.8.2.1.txt | 115 + Documentation/RelNotes/1.8.2.2.txt | 61 + Documentation/RelNotes/1.8.2.3.txt | 19 + Documentation/RelNotes/1.8.2.txt | 495 +++ Documentation/RelNotes/1.8.3.1.txt | 14 + Documentation/RelNotes/1.8.3.2.txt | 59 + Documentation/RelNotes/1.8.3.3.txt | 47 + Documentation/RelNotes/1.8.3.4.txt | 20 + Documentation/RelNotes/1.8.3.txt | 436 ++ Documentation/RelNotes/1.8.4.1.txt | 71 + Documentation/RelNotes/1.8.4.2.txt | 77 + Documentation/RelNotes/1.8.4.3.txt | 54 + Documentation/RelNotes/1.8.4.4.txt | 10 + Documentation/RelNotes/1.8.4.5.txt | 13 + Documentation/RelNotes/1.8.4.txt | 486 +++ Documentation/RelNotes/1.8.5.1.txt | 9 + Documentation/RelNotes/1.8.5.2.txt | 20 + Documentation/RelNotes/1.8.5.3.txt | 27 + Documentation/RelNotes/1.8.5.4.txt | 48 + Documentation/RelNotes/1.8.5.5.txt | 37 + Documentation/RelNotes/1.8.5.6.txt | 34 + Documentation/RelNotes/1.8.5.txt | 456 ++ Documentation/RelNotes/1.9.0.txt | 345 ++ Documentation/RelNotes/1.9.1.txt | 59 + Documentation/RelNotes/1.9.2.txt | 67 + Documentation/RelNotes/1.9.3.txt | 21 + Documentation/RelNotes/1.9.4.txt | 16 + Documentation/RelNotes/1.9.5.txt | 34 + Documentation/RelNotes/2.0.0.txt | 364 ++ Documentation/RelNotes/2.0.1.txt | 115 + Documentation/RelNotes/2.0.2.txt | 32 + Documentation/RelNotes/2.0.3.txt | 17 + Documentation/RelNotes/2.0.4.txt | 5 + Documentation/RelNotes/2.0.5.txt | 34 + Documentation/RelNotes/2.1.0.txt | 391 ++ Documentation/RelNotes/2.1.1.txt | 44 + Documentation/RelNotes/2.1.2.txt | 20 + Documentation/RelNotes/2.1.3.txt | 26 + Documentation/RelNotes/2.1.4.txt | 34 + Documentation/RelNotes/2.10.0.txt | 675 +++ Documentation/RelNotes/2.10.1.txt | 131 + Documentation/RelNotes/2.10.2.txt | 111 + Documentation/RelNotes/2.10.3.txt | 55 + Documentation/RelNotes/2.10.4.txt | 4 + Documentation/RelNotes/2.10.5.txt | 17 + Documentation/RelNotes/2.11.0.txt | 593 +++ Documentation/RelNotes/2.11.1.txt | 168 + Documentation/RelNotes/2.11.2.txt | 12 + Documentation/RelNotes/2.11.3.txt | 4 + Documentation/RelNotes/2.11.4.txt | 17 + Documentation/RelNotes/2.12.0.txt | 500 +++ Documentation/RelNotes/2.12.1.txt | 41 + Documentation/RelNotes/2.12.2.txt | 83 + Documentation/RelNotes/2.12.3.txt | 64 + Documentation/RelNotes/2.12.4.txt | 4 + Documentation/RelNotes/2.12.5.txt | 17 + Documentation/RelNotes/2.13.0.txt | 618 +++ Documentation/RelNotes/2.13.1.txt | 114 + Documentation/RelNotes/2.13.2.txt | 54 + Documentation/RelNotes/2.13.3.txt | 62 + Documentation/RelNotes/2.13.4.txt | 28 + Documentation/RelNotes/2.13.5.txt | 4 + Documentation/RelNotes/2.13.6.txt | 17 + Documentation/RelNotes/2.13.7.txt | 20 + Documentation/RelNotes/2.14.0.txt | 517 +++ Documentation/RelNotes/2.14.1.txt | 4 + Documentation/RelNotes/2.14.2.txt | 105 + Documentation/RelNotes/2.14.3.txt | 99 + Documentation/RelNotes/2.14.4.txt | 5 + Documentation/RelNotes/2.14.5.txt | 16 + Documentation/RelNotes/2.14.6.txt | 54 + Documentation/RelNotes/2.15.0.txt | 508 +++ Documentation/RelNotes/2.15.1.txt | 88 + Documentation/RelNotes/2.15.2.txt | 50 + Documentation/RelNotes/2.15.3.txt | 6 + Documentation/RelNotes/2.15.4.txt | 11 + Documentation/RelNotes/2.16.0.txt | 482 +++ Documentation/RelNotes/2.16.1.txt | 11 + Documentation/RelNotes/2.16.2.txt | 30 + Documentation/RelNotes/2.16.3.txt | 49 + Documentation/RelNotes/2.16.4.txt | 5 + Documentation/RelNotes/2.16.5.txt | 6 + Documentation/RelNotes/2.16.6.txt | 8 + Documentation/RelNotes/2.17.0.txt | 398 ++ Documentation/RelNotes/2.17.1.txt | 16 + Documentation/RelNotes/2.17.2.txt | 12 + Documentation/RelNotes/2.17.3.txt | 12 + Documentation/RelNotes/2.17.4.txt | 16 + Documentation/RelNotes/2.17.5.txt | 22 + Documentation/RelNotes/2.17.6.txt | 16 + Documentation/RelNotes/2.18.0.txt | 583 +++ Documentation/RelNotes/2.18.1.txt | 6 + Documentation/RelNotes/2.18.2.txt | 8 + Documentation/RelNotes/2.18.3.txt | 5 + Documentation/RelNotes/2.18.4.txt | 5 + Documentation/RelNotes/2.18.5.txt | 6 + Documentation/RelNotes/2.19.0.txt | 615 +++ Documentation/RelNotes/2.19.1.txt | 6 + Documentation/RelNotes/2.19.2.txt | 108 + Documentation/RelNotes/2.19.3.txt | 8 + Documentation/RelNotes/2.19.4.txt | 5 + Documentation/RelNotes/2.19.5.txt | 5 + Documentation/RelNotes/2.19.6.txt | 6 + Documentation/RelNotes/2.2.0.txt | 313 ++ Documentation/RelNotes/2.2.1.txt | 34 + Documentation/RelNotes/2.2.2.txt | 63 + Documentation/RelNotes/2.2.3.txt | 9 + Documentation/RelNotes/2.20.0.txt | 700 +++ Documentation/RelNotes/2.20.1.txt | 20 + Documentation/RelNotes/2.20.2.txt | 18 + Documentation/RelNotes/2.20.3.txt | 5 + Documentation/RelNotes/2.20.4.txt | 5 + Documentation/RelNotes/2.20.5.txt | 6 + Documentation/RelNotes/2.21.0.txt | 451 ++ Documentation/RelNotes/2.21.1.txt | 12 + Documentation/RelNotes/2.21.2.txt | 5 + Documentation/RelNotes/2.21.3.txt | 5 + Documentation/RelNotes/2.21.4.txt | 6 + Documentation/RelNotes/2.22.0.txt | 597 +++ Documentation/RelNotes/2.22.1.txt | 150 + Documentation/RelNotes/2.22.2.txt | 8 + Documentation/RelNotes/2.22.3.txt | 5 + Documentation/RelNotes/2.22.4.txt | 5 + Documentation/RelNotes/2.22.5.txt | 7 + Documentation/RelNotes/2.23.0.txt | 348 ++ Documentation/RelNotes/2.23.1.txt | 8 + Documentation/RelNotes/2.23.2.txt | 5 + Documentation/RelNotes/2.23.3.txt | 5 + Documentation/RelNotes/2.23.4.txt | 7 + Documentation/RelNotes/2.24.0.txt | 398 ++ Documentation/RelNotes/2.24.1.txt | 8 + Documentation/RelNotes/2.24.2.txt | 5 + Documentation/RelNotes/2.24.3.txt | 5 + Documentation/RelNotes/2.24.4.txt | 7 + Documentation/RelNotes/2.25.0.txt | 370 ++ Documentation/RelNotes/2.25.1.txt | 55 + Documentation/RelNotes/2.25.2.txt | 60 + Documentation/RelNotes/2.25.3.txt | 5 + Documentation/RelNotes/2.25.4.txt | 5 + Documentation/RelNotes/2.25.5.txt | 7 + Documentation/RelNotes/2.26.0.txt | 341 ++ Documentation/RelNotes/2.26.1.txt | 5 + Documentation/RelNotes/2.26.2.txt | 5 + Documentation/RelNotes/2.26.3.txt | 7 + Documentation/RelNotes/2.27.0.txt | 525 +++ Documentation/RelNotes/2.27.1.txt | 7 + Documentation/RelNotes/2.28.0.txt | 236 + Documentation/RelNotes/2.28.1.txt | 7 + Documentation/RelNotes/2.29.0.txt | 514 +++ Documentation/RelNotes/2.29.1.txt | 11 + Documentation/RelNotes/2.29.2.txt | 12 + Documentation/RelNotes/2.29.3.txt | 8 + Documentation/RelNotes/2.3.0.txt | 300 ++ Documentation/RelNotes/2.3.1.txt | 52 + Documentation/RelNotes/2.3.10.txt | 18 + Documentation/RelNotes/2.3.2.txt | 79 + Documentation/RelNotes/2.3.3.txt | 39 + Documentation/RelNotes/2.3.4.txt | 32 + Documentation/RelNotes/2.3.5.txt | 44 + Documentation/RelNotes/2.3.6.txt | 13 + Documentation/RelNotes/2.3.7.txt | 21 + Documentation/RelNotes/2.3.8.txt | 22 + Documentation/RelNotes/2.3.9.txt | 9 + Documentation/RelNotes/2.30.0.txt | 401 ++ Documentation/RelNotes/2.30.1.txt | 55 + Documentation/RelNotes/2.30.2.txt | 8 + Documentation/RelNotes/2.4.0.txt | 514 +++ Documentation/RelNotes/2.4.1.txt | 40 + Documentation/RelNotes/2.4.10.txt | 18 + Documentation/RelNotes/2.4.11.txt | 11 + Documentation/RelNotes/2.4.12.txt | 12 + Documentation/RelNotes/2.4.2.txt | 45 + Documentation/RelNotes/2.4.3.txt | 76 + Documentation/RelNotes/2.4.4.txt | 35 + Documentation/RelNotes/2.4.5.txt | 28 + Documentation/RelNotes/2.4.6.txt | 23 + Documentation/RelNotes/2.4.7.txt | 53 + Documentation/RelNotes/2.4.8.txt | 21 + Documentation/RelNotes/2.4.9.txt | 9 + Documentation/RelNotes/2.5.0.txt | 564 +++ Documentation/RelNotes/2.5.1.txt | 65 + Documentation/RelNotes/2.5.2.txt | 63 + Documentation/RelNotes/2.5.3.txt | 17 + Documentation/RelNotes/2.5.4.txt | 18 + Documentation/RelNotes/2.5.5.txt | 11 + Documentation/RelNotes/2.5.6.txt | 12 + Documentation/RelNotes/2.6.0.txt | 370 ++ Documentation/RelNotes/2.6.1.txt | 18 + Documentation/RelNotes/2.6.2.txt | 65 + Documentation/RelNotes/2.6.3.txt | 111 + Documentation/RelNotes/2.6.4.txt | 63 + Documentation/RelNotes/2.6.5.txt | 58 + Documentation/RelNotes/2.6.6.txt | 11 + Documentation/RelNotes/2.6.7.txt | 12 + Documentation/RelNotes/2.7.0.txt | 414 ++ Documentation/RelNotes/2.7.1.txt | 87 + Documentation/RelNotes/2.7.2.txt | 41 + Documentation/RelNotes/2.7.3.txt | 62 + Documentation/RelNotes/2.7.4.txt | 11 + Documentation/RelNotes/2.7.5.txt | 14 + Documentation/RelNotes/2.7.6.txt | 25 + Documentation/RelNotes/2.8.0.txt | 439 ++ Documentation/RelNotes/2.8.1.txt | 9 + Documentation/RelNotes/2.8.2.txt | 70 + Documentation/RelNotes/2.8.3.txt | 101 + Documentation/RelNotes/2.8.4.txt | 69 + Documentation/RelNotes/2.8.5.txt | 12 + Documentation/RelNotes/2.8.6.txt | 4 + Documentation/RelNotes/2.9.0.txt | 512 +++ Documentation/RelNotes/2.9.1.txt | 117 + Documentation/RelNotes/2.9.2.txt | 13 + Documentation/RelNotes/2.9.3.txt | 170 + Documentation/RelNotes/2.9.4.txt | 90 + Documentation/RelNotes/2.9.5.txt | 4 + Documentation/SubmittingPatches | 581 +++ Documentation/asciidoc.conf | 78 + Documentation/asciidoctor-extensions.rb | 48 + Documentation/blame-options.txt | 140 + Documentation/build-docdep.perl | 46 + Documentation/cat-texi.perl | 46 + Documentation/cmd-list.perl | 79 + Documentation/config.txt | 477 ++ Documentation/config/add.txt | 12 + Documentation/config/advice.txt | 122 + Documentation/config/alias.txt | 28 + Documentation/config/am.txt | 14 + Documentation/config/apply.txt | 11 + Documentation/config/blame.txt | 37 + Documentation/config/branch.txt | 103 + Documentation/config/browser.txt | 9 + Documentation/config/checkout.txt | 23 + Documentation/config/clean.txt | 3 + Documentation/config/clone.txt | 4 + Documentation/config/color.txt | 201 + Documentation/config/column.txt | 55 + Documentation/config/commit.txt | 29 + Documentation/config/commitgraph.txt | 8 + Documentation/config/completion.txt | 7 + Documentation/config/core.txt | 628 +++ Documentation/config/credential.txt | 36 + Documentation/config/diff.txt | 235 + Documentation/config/difftool.txt | 14 + Documentation/config/extensions.txt | 8 + Documentation/config/fastimport.txt | 8 + Documentation/config/feature.txt | 26 + Documentation/config/fetch.txt | 96 + Documentation/config/filter.txt | 9 + Documentation/config/fmt-merge-msg.txt | 22 + Documentation/config/format.txt | 137 + Documentation/config/fsck.txt | 67 + Documentation/config/gc.txt | 136 + Documentation/config/gitcvs.txt | 67 + Documentation/config/gitweb.txt | 16 + Documentation/config/gpg.txt | 35 + Documentation/config/grep.txt | 24 + Documentation/config/gui.txt | 57 + Documentation/config/guitool.txt | 50 + Documentation/config/help.txt | 24 + Documentation/config/http.txt | 309 ++ Documentation/config/i18n.txt | 10 + Documentation/config/imap.txt | 44 + Documentation/config/index.txt | 27 + Documentation/config/init.txt | 7 + Documentation/config/instaweb.txt | 20 + Documentation/config/interactive.txt | 17 + Documentation/config/log.txt | 50 + Documentation/config/mailinfo.txt | 6 + Documentation/config/mailmap.txt | 15 + Documentation/config/maintenance.txt | 59 + Documentation/config/man.txt | 12 + Documentation/config/merge.txt | 116 + Documentation/config/mergetool.txt | 63 + Documentation/config/notes.txt | 59 + Documentation/config/pack.txt | 135 + Documentation/config/pager.txt | 8 + Documentation/config/pretty.txt | 9 + Documentation/config/protocol.txt | 63 + Documentation/config/pull.txt | 37 + Documentation/config/push.txt | 122 + Documentation/config/rebase.txt | 70 + Documentation/config/receive.txt | 145 + Documentation/config/remote.txt | 86 + Documentation/config/remotes.txt | 3 + Documentation/config/repack.txt | 27 + Documentation/config/rerere.txt | 12 + Documentation/config/reset.txt | 2 + Documentation/config/sendemail.txt | 68 + Documentation/config/sequencer.txt | 5 + Documentation/config/showbranch.txt | 3 + Documentation/config/splitindex.txt | 24 + Documentation/config/ssh.txt | 35 + Documentation/config/stash.txt | 16 + Documentation/config/status.txt | 77 + Documentation/config/submodule.txt | 92 + Documentation/config/tag.txt | 17 + Documentation/config/tar.txt | 6 + Documentation/config/trace2.txt | 71 + Documentation/config/transfer.txt | 75 + Documentation/config/uploadarchive.txt | 6 + Documentation/config/uploadpack.txt | 83 + Documentation/config/url.txt | 30 + Documentation/config/user.txt | 38 + Documentation/config/versionsort.txt | 33 + Documentation/config/web.txt | 4 + Documentation/config/worktree.txt | 9 + Documentation/date-formats.txt | 28 + Documentation/diff-format.txt | 185 + Documentation/diff-generate-patch.txt | 202 + Documentation/diff-options.txt | 777 ++++ Documentation/doc-diff | 186 + Documentation/docbook-xsl.css | 296 ++ Documentation/docbook.xsl | 8 + Documentation/everyday.txto | 9 + Documentation/fetch-options.txt | 282 ++ Documentation/fix-texi.perl | 15 + Documentation/git-add.txt | 438 ++ Documentation/git-am.txt | 250 ++ Documentation/git-annotate.txt | 33 + Documentation/git-apply.txt | 285 ++ Documentation/git-archimport.txt | 113 + Documentation/git-archive.txt | 203 + Documentation/git-bisect-lk2009.txt | 1358 ++++++ Documentation/git-bisect.txt | 510 +++ Documentation/git-blame.txt | 238 + Documentation/git-branch.txt | 385 ++ Documentation/git-bugreport.txt | 54 + Documentation/git-bundle.txt | 252 ++ Documentation/git-cat-file.txt | 319 ++ Documentation/git-check-attr.txt | 120 + Documentation/git-check-ignore.txt | 126 + Documentation/git-check-mailmap.txt | 47 + Documentation/git-check-ref-format.txt | 140 + Documentation/git-checkout-index.txt | 177 + Documentation/git-checkout.txt | 610 +++ Documentation/git-cherry-pick.txt | 246 ++ Documentation/git-cherry.txt | 145 + Documentation/git-citool.txt | 25 + Documentation/git-clean.txt | 142 + Documentation/git-clone.txt | 359 ++ Documentation/git-column.txt | 79 + Documentation/git-commit-graph.txt | 148 + Documentation/git-commit-tree.txt | 101 + Documentation/git-commit.txt | 540 +++ Documentation/git-config.txt | 509 +++ Documentation/git-count-objects.txt | 54 + Documentation/git-credential-cache--daemon.txt | 30 + Documentation/git-credential-cache.txt | 80 + Documentation/git-credential-store.txt | 110 + Documentation/git-credential.txt | 161 + Documentation/git-cvsexportcommit.txt | 118 + Documentation/git-cvsimport.txt | 228 + Documentation/git-cvsserver.txt | 433 ++ Documentation/git-daemon.txt | 340 ++ Documentation/git-describe.txt | 207 + Documentation/git-diff-files.txt | 52 + Documentation/git-diff-index.txt | 127 + Documentation/git-diff-tree.txt | 131 + Documentation/git-diff.txt | 224 + Documentation/git-difftool.txt | 149 + Documentation/git-fast-export.txt | 284 ++ Documentation/git-fast-import.txt | 1573 +++++++ Documentation/git-fetch-pack.txt | 132 + Documentation/git-fetch.txt | 303 ++ Documentation/git-filter-branch.txt | 703 +++ Documentation/git-fmt-merge-msg.txt | 78 + Documentation/git-for-each-ref.txt | 420 ++ Documentation/git-for-each-repo.txt | 59 + Documentation/git-format-patch.txt | 727 ++++ Documentation/git-fsck-objects.txt | 22 + Documentation/git-fsck.txt | 167 + Documentation/git-gc.txt | 161 + Documentation/git-get-tar-commit-id.txt | 30 + Documentation/git-grep.txt | 368 ++ Documentation/git-gui.txt | 121 + Documentation/git-hash-object.txt | 63 + Documentation/git-help.txt | 204 + Documentation/git-http-backend.txt | 277 ++ Documentation/git-http-fetch.txt | 56 + Documentation/git-http-push.txt | 97 + Documentation/git-imap-send.txt | 144 + Documentation/git-index-pack.txt | 118 + Documentation/git-init-db.txt | 23 + Documentation/git-init.txt | 171 + Documentation/git-instaweb.txt | 94 + Documentation/git-interpret-trailers.txt | 390 ++ Documentation/git-log.txt | 276 ++ Documentation/git-ls-files.txt | 250 ++ Documentation/git-ls-remote.txt | 121 + Documentation/git-ls-tree.txt | 105 + Documentation/git-mailinfo.txt | 101 + Documentation/git-mailsplit.txt | 57 + Documentation/git-maintenance.txt | 224 + Documentation/git-merge-base.txt | 247 ++ Documentation/git-merge-file.txt | 95 + Documentation/git-merge-index.txt | 83 + Documentation/git-merge-one-file.txt | 21 + Documentation/git-merge-tree.txt | 29 + Documentation/git-merge.txt | 377 ++ Documentation/git-mergetool--lib.txt | 49 + Documentation/git-mergetool.txt | 114 + Documentation/git-mktag.txt | 39 + Documentation/git-mktree.txt | 40 + Documentation/git-multi-pack-index.txt | 96 + Documentation/git-mv.txt | 69 + Documentation/git-name-rev.txt | 89 + Documentation/git-notes.txt | 405 ++ Documentation/git-p4.txt | 764 ++++ Documentation/git-pack-objects.txt | 411 ++ Documentation/git-pack-redundant.txt | 50 + Documentation/git-pack-refs.txt | 73 + Documentation/git-patch-id.txt | 61 + Documentation/git-prune-packed.txt | 47 + Documentation/git-prune.txt | 89 + Documentation/git-pull.txt | 255 ++ Documentation/git-push.txt | 697 +++ Documentation/git-quiltimport.txt | 64 + Documentation/git-range-diff.txt | 273 ++ Documentation/git-read-tree.txt | 443 ++ Documentation/git-rebase.txt | 1285 ++++++ Documentation/git-receive-pack.txt | 256 ++ Documentation/git-reflog.txt | 138 + Documentation/git-remote-ext.txt | 125 + Documentation/git-remote-fd.txt | 59 + Documentation/git-remote-helpers.txto | 9 + Documentation/git-remote.txt | 267 ++ Documentation/git-repack.txt | 188 + Documentation/git-replace.txt | 161 + Documentation/git-request-pull.txt | 79 + Documentation/git-rerere.txt | 222 + Documentation/git-reset.txt | 503 +++ Documentation/git-restore.txt | 219 + Documentation/git-rev-list.txt | 36 + Documentation/git-rev-parse.txt | 468 ++ Documentation/git-revert.txt | 145 + Documentation/git-rm.txt | 196 + Documentation/git-send-email.txt | 530 +++ Documentation/git-send-pack.txt | 156 + Documentation/git-sh-i18n--envsubst.txt | 36 + Documentation/git-sh-i18n.txt | 43 + Documentation/git-sh-setup.txt | 95 + Documentation/git-shell.txt | 106 + Documentation/git-shortlog.txt | 122 + Documentation/git-show-branch.txt | 204 + Documentation/git-show-index.txt | 52 + Documentation/git-show-ref.txt | 186 + Documentation/git-show.txt | 87 + Documentation/git-sparse-checkout.txt | 239 + Documentation/git-stage.txt | 23 + Documentation/git-stash.txt | 358 ++ Documentation/git-status.txt | 455 ++ Documentation/git-stripspace.txt | 94 + Documentation/git-submodule.txt | 456 ++ Documentation/git-svn.txt | 1175 +++++ Documentation/git-switch.txt | 276 ++ Documentation/git-symbolic-ref.txt | 69 + Documentation/git-tag.txt | 392 ++ Documentation/git-tools.txt | 10 + Documentation/git-unpack-file.txt | 28 + Documentation/git-unpack-objects.txt | 52 + Documentation/git-update-index.txt | 575 +++ Documentation/git-update-ref.txt | 180 + Documentation/git-update-server-info.txt | 35 + Documentation/git-upload-archive.txt | 62 + Documentation/git-upload-pack.txt | 53 + Documentation/git-var.txt | 70 + Documentation/git-verify-commit.txt | 32 + Documentation/git-verify-pack.txt | 53 + Documentation/git-verify-tag.txt | 32 + Documentation/git-web--browse.txt | 124 + Documentation/git-whatchanged.txt | 43 + Documentation/git-worktree.txt | 421 ++ Documentation/git-write-tree.txt | 42 + Documentation/git.txt | 1010 +++++ Documentation/gitattributes.txt | 1303 ++++++ Documentation/gitcli.txt | 237 + Documentation/gitcore-tutorial.txt | 1660 +++++++ Documentation/gitcredentials.txt | 298 ++ Documentation/gitcvs-migration.txt | 206 + Documentation/gitdiffcore.txt | 292 ++ Documentation/giteveryday.txt | 455 ++ Documentation/gitfaq.txt | 441 ++ Documentation/gitglossary.txt | 27 + Documentation/githooks.txt | 694 +++ Documentation/gitignore.txt | 238 + Documentation/gitk.txt | 188 + Documentation/gitmodules.txt | 127 + Documentation/gitnamespaces.txt | 64 + Documentation/gitremote-helpers.txt | 556 +++ Documentation/gitrepository-layout.txt | 308 ++ Documentation/gitrevisions.txt | 36 + Documentation/gitsubmodules.txt | 287 ++ Documentation/gittutorial-2.txt | 436 ++ Documentation/gittutorial.txt | 677 +++ Documentation/gitweb.conf.txt | 970 +++++ Documentation/gitweb.txt | 703 +++ Documentation/gitworkflows.txt | 479 ++ Documentation/glossary-content.txt | 671 +++ Documentation/howto-index.sh | 56 + .../howto/keep-canonical-history-correct.txt | 216 + Documentation/howto/maintain-git.txt | 475 ++ Documentation/howto/new-command.txt | 106 + .../howto/rebase-from-internal-branch.txt | 164 + Documentation/howto/rebuild-from-update-hook.txt | 90 + .../howto/recover-corrupted-blob-object.txt | 144 + .../howto/recover-corrupted-object-harder.txt | 479 ++ Documentation/howto/revert-a-faulty-merge.txt | 273 ++ Documentation/howto/revert-branch-rebase.txt | 187 + Documentation/howto/separating-topic-branches.txt | 94 + Documentation/howto/setup-git-server-over-http.txt | 285 ++ Documentation/howto/update-hook-example.txt | 192 + Documentation/howto/use-git-daemon.txt | 54 + Documentation/howto/using-merge-subtree.txt | 75 + .../howto/using-signed-tag-in-pull-request.txt | 217 + Documentation/i18n.txt | 70 + Documentation/install-doc-quick.sh | 40 + Documentation/install-webdoc.sh | 39 + Documentation/line-range-format.txt | 32 + Documentation/line-range-options.txt | 15 + Documentation/lint-gitlink.perl | 71 + Documentation/mailmap.txt | 75 + Documentation/manpage-base-url.xsl.in | 10 + Documentation/manpage-bold-literal.xsl | 16 + Documentation/manpage-normal.xsl | 26 + Documentation/manpage-quote-apos.xsl | 16 + Documentation/manpage.xsl | 3 + Documentation/merge-options.txt | 168 + Documentation/merge-strategies.txt | 136 + Documentation/object-format-disclaimer.txt | 6 + Documentation/pretty-formats.txt | 334 ++ Documentation/pretty-options.txt | 96 + Documentation/pull-fetch-param.txt | 119 + Documentation/ref-reachability-filters.txt | 7 + Documentation/rev-list-description.txt | 61 + Documentation/rev-list-options.txt | 1118 +++++ Documentation/revisions.txt | 380 ++ Documentation/sequencer.txt | 16 + Documentation/signoff-option.txt | 18 + Documentation/technical/.gitignore | 1 + Documentation/technical/api-error-handling.txt | 75 + Documentation/technical/api-index-skel.txt | 13 + Documentation/technical/api-index.sh | 28 + Documentation/technical/api-merge.txt | 36 + Documentation/technical/api-parse-options.txt | 313 ++ Documentation/technical/api-trace2.txt | 1171 +++++ Documentation/technical/bitmap-format.txt | 164 + Documentation/technical/bundle-format.txt | 76 + Documentation/technical/commit-graph-format.txt | 139 + Documentation/technical/commit-graph.txt | 350 ++ .../technical/directory-rename-detection.txt | 116 + .../technical/hash-function-transition.txt | 827 ++++ Documentation/technical/http-protocol.txt | 519 +++ Documentation/technical/index-format.txt | 365 ++ .../technical/long-running-process-protocol.txt | 50 + Documentation/technical/multi-pack-index.txt | 105 + Documentation/technical/pack-format.txt | 358 ++ Documentation/technical/pack-heuristics.txt | 460 ++ Documentation/technical/pack-protocol.txt | 709 +++ Documentation/technical/packfile-uri.txt | 81 + Documentation/technical/partial-clone.txt | 368 ++ Documentation/technical/protocol-capabilities.txt | 380 ++ Documentation/technical/protocol-common.txt | 99 + Documentation/technical/protocol-v2.txt | 507 +++ Documentation/technical/racy-git.txt | 201 + Documentation/technical/reftable.txt | 1083 +++++ Documentation/technical/repository-version.txt | 102 + Documentation/technical/rerere.txt | 186 + Documentation/technical/send-pack-pipeline.txt | 63 + Documentation/technical/shallow.txt | 60 + Documentation/technical/signature-format.txt | 186 + Documentation/technical/trivial-merge.txt | 121 + Documentation/texi.xsl | 26 + Documentation/trace2-target-values.txt | 12 + Documentation/transfer-data-leaks.txt | 30 + Documentation/urls-remotes.txt | 94 + Documentation/urls.txt | 108 + Documentation/user-manual.conf | 11 + Documentation/user-manual.txt | 4578 ++++++++++++++++++++ 776 files changed, 112856 insertions(+) create mode 100644 Documentation/.gitattributes create mode 100644 Documentation/.gitignore create mode 100644 Documentation/CodingGuidelines create mode 100644 Documentation/Makefile create mode 100644 Documentation/MyFirstContribution.txt create mode 100644 Documentation/MyFirstObjectWalk.txt create mode 100644 Documentation/RelNotes/1.5.0.1.txt create mode 100644 Documentation/RelNotes/1.5.0.2.txt create mode 100644 Documentation/RelNotes/1.5.0.3.txt create mode 100644 Documentation/RelNotes/1.5.0.4.txt create mode 100644 Documentation/RelNotes/1.5.0.5.txt create mode 100644 Documentation/RelNotes/1.5.0.6.txt create mode 100644 Documentation/RelNotes/1.5.0.7.txt create mode 100644 Documentation/RelNotes/1.5.0.txt create mode 100644 Documentation/RelNotes/1.5.1.1.txt create mode 100644 Documentation/RelNotes/1.5.1.2.txt create mode 100644 Documentation/RelNotes/1.5.1.3.txt create mode 100644 Documentation/RelNotes/1.5.1.4.txt create mode 100644 Documentation/RelNotes/1.5.1.5.txt create mode 100644 Documentation/RelNotes/1.5.1.6.txt create mode 100644 Documentation/RelNotes/1.5.1.txt create mode 100644 Documentation/RelNotes/1.5.2.1.txt create mode 100644 Documentation/RelNotes/1.5.2.2.txt create mode 100644 Documentation/RelNotes/1.5.2.3.txt create mode 100644 Documentation/RelNotes/1.5.2.4.txt create mode 100644 Documentation/RelNotes/1.5.2.5.txt create mode 100644 Documentation/RelNotes/1.5.2.txt create mode 100644 Documentation/RelNotes/1.5.3.1.txt create mode 100644 Documentation/RelNotes/1.5.3.2.txt create mode 100644 Documentation/RelNotes/1.5.3.3.txt create mode 100644 Documentation/RelNotes/1.5.3.4.txt create mode 100644 Documentation/RelNotes/1.5.3.5.txt create mode 100644 Documentation/RelNotes/1.5.3.6.txt create mode 100644 Documentation/RelNotes/1.5.3.7.txt create mode 100644 Documentation/RelNotes/1.5.3.8.txt create mode 100644 Documentation/RelNotes/1.5.3.txt create mode 100644 Documentation/RelNotes/1.5.4.1.txt create mode 100644 Documentation/RelNotes/1.5.4.2.txt create mode 100644 Documentation/RelNotes/1.5.4.3.txt create mode 100644 Documentation/RelNotes/1.5.4.4.txt create mode 100644 Documentation/RelNotes/1.5.4.5.txt create mode 100644 Documentation/RelNotes/1.5.4.6.txt create mode 100644 Documentation/RelNotes/1.5.4.7.txt create mode 100644 Documentation/RelNotes/1.5.4.txt create mode 100644 Documentation/RelNotes/1.5.5.1.txt create mode 100644 Documentation/RelNotes/1.5.5.2.txt create mode 100644 Documentation/RelNotes/1.5.5.3.txt create mode 100644 Documentation/RelNotes/1.5.5.4.txt create mode 100644 Documentation/RelNotes/1.5.5.5.txt create mode 100644 Documentation/RelNotes/1.5.5.6.txt create mode 100644 Documentation/RelNotes/1.5.5.txt create mode 100644 Documentation/RelNotes/1.5.6.1.txt create mode 100644 Documentation/RelNotes/1.5.6.2.txt create mode 100644 Documentation/RelNotes/1.5.6.3.txt create mode 100644 Documentation/RelNotes/1.5.6.4.txt create mode 100644 Documentation/RelNotes/1.5.6.5.txt create mode 100644 Documentation/RelNotes/1.5.6.6.txt create mode 100644 Documentation/RelNotes/1.5.6.txt create mode 100644 Documentation/RelNotes/1.6.0.1.txt create mode 100644 Documentation/RelNotes/1.6.0.2.txt create mode 100644 Documentation/RelNotes/1.6.0.3.txt create mode 100644 Documentation/RelNotes/1.6.0.4.txt create mode 100644 Documentation/RelNotes/1.6.0.5.txt create mode 100644 Documentation/RelNotes/1.6.0.6.txt create mode 100644 Documentation/RelNotes/1.6.0.txt create mode 100644 Documentation/RelNotes/1.6.1.1.txt create mode 100644 Documentation/RelNotes/1.6.1.2.txt create mode 100644 Documentation/RelNotes/1.6.1.3.txt create mode 100644 Documentation/RelNotes/1.6.1.4.txt create mode 100644 Documentation/RelNotes/1.6.1.txt create mode 100644 Documentation/RelNotes/1.6.2.1.txt create mode 100644 Documentation/RelNotes/1.6.2.2.txt create mode 100644 Documentation/RelNotes/1.6.2.3.txt create mode 100644 Documentation/RelNotes/1.6.2.4.txt create mode 100644 Documentation/RelNotes/1.6.2.5.txt create mode 100644 Documentation/RelNotes/1.6.2.txt create mode 100644 Documentation/RelNotes/1.6.3.1.txt create mode 100644 Documentation/RelNotes/1.6.3.2.txt create mode 100644 Documentation/RelNotes/1.6.3.3.txt create mode 100644 Documentation/RelNotes/1.6.3.4.txt create mode 100644 Documentation/RelNotes/1.6.3.txt create mode 100644 Documentation/RelNotes/1.6.4.1.txt create mode 100644 Documentation/RelNotes/1.6.4.2.txt create mode 100644 Documentation/RelNotes/1.6.4.3.txt create mode 100644 Documentation/RelNotes/1.6.4.4.txt create mode 100644 Documentation/RelNotes/1.6.4.5.txt create mode 100644 Documentation/RelNotes/1.6.4.txt create mode 100644 Documentation/RelNotes/1.6.5.1.txt create mode 100644 Documentation/RelNotes/1.6.5.2.txt create mode 100644 Documentation/RelNotes/1.6.5.3.txt create mode 100644 Documentation/RelNotes/1.6.5.4.txt create mode 100644 Documentation/RelNotes/1.6.5.5.txt create mode 100644 Documentation/RelNotes/1.6.5.6.txt create mode 100644 Documentation/RelNotes/1.6.5.7.txt create mode 100644 Documentation/RelNotes/1.6.5.8.txt create mode 100644 Documentation/RelNotes/1.6.5.9.txt create mode 100644 Documentation/RelNotes/1.6.5.txt create mode 100644 Documentation/RelNotes/1.6.6.1.txt create mode 100644 Documentation/RelNotes/1.6.6.2.txt create mode 100644 Documentation/RelNotes/1.6.6.3.txt create mode 100644 Documentation/RelNotes/1.6.6.txt create mode 100644 Documentation/RelNotes/1.7.0.1.txt create mode 100644 Documentation/RelNotes/1.7.0.2.txt create mode 100644 Documentation/RelNotes/1.7.0.3.txt create mode 100644 Documentation/RelNotes/1.7.0.4.txt create mode 100644 Documentation/RelNotes/1.7.0.5.txt create mode 100644 Documentation/RelNotes/1.7.0.6.txt create mode 100644 Documentation/RelNotes/1.7.0.7.txt create mode 100644 Documentation/RelNotes/1.7.0.8.txt create mode 100644 Documentation/RelNotes/1.7.0.9.txt create mode 100644 Documentation/RelNotes/1.7.0.txt create mode 100644 Documentation/RelNotes/1.7.1.1.txt create mode 100644 Documentation/RelNotes/1.7.1.2.txt create mode 100644 Documentation/RelNotes/1.7.1.3.txt create mode 100644 Documentation/RelNotes/1.7.1.4.txt create mode 100644 Documentation/RelNotes/1.7.1.txt create mode 100644 Documentation/RelNotes/1.7.10.1.txt create mode 100644 Documentation/RelNotes/1.7.10.2.txt create mode 100644 Documentation/RelNotes/1.7.10.3.txt create mode 100644 Documentation/RelNotes/1.7.10.4.txt create mode 100644 Documentation/RelNotes/1.7.10.5.txt create mode 100644 Documentation/RelNotes/1.7.10.txt create mode 100644 Documentation/RelNotes/1.7.11.1.txt create mode 100644 Documentation/RelNotes/1.7.11.2.txt create mode 100644 Documentation/RelNotes/1.7.11.3.txt create mode 100644 Documentation/RelNotes/1.7.11.4.txt create mode 100644 Documentation/RelNotes/1.7.11.5.txt create mode 100644 Documentation/RelNotes/1.7.11.6.txt create mode 100644 Documentation/RelNotes/1.7.11.7.txt create mode 100644 Documentation/RelNotes/1.7.11.txt create mode 100644 Documentation/RelNotes/1.7.12.1.txt create mode 100644 Documentation/RelNotes/1.7.12.2.txt create mode 100644 Documentation/RelNotes/1.7.12.3.txt create mode 100644 Documentation/RelNotes/1.7.12.4.txt create mode 100644 Documentation/RelNotes/1.7.12.txt create mode 100644 Documentation/RelNotes/1.7.2.1.txt create mode 100644 Documentation/RelNotes/1.7.2.2.txt create mode 100644 Documentation/RelNotes/1.7.2.3.txt create mode 100644 Documentation/RelNotes/1.7.2.4.txt create mode 100644 Documentation/RelNotes/1.7.2.5.txt create mode 100644 Documentation/RelNotes/1.7.2.txt create mode 100644 Documentation/RelNotes/1.7.3.1.txt create mode 100644 Documentation/RelNotes/1.7.3.2.txt create mode 100644 Documentation/RelNotes/1.7.3.3.txt create mode 100644 Documentation/RelNotes/1.7.3.4.txt create mode 100644 Documentation/RelNotes/1.7.3.5.txt create mode 100644 Documentation/RelNotes/1.7.3.txt create mode 100644 Documentation/RelNotes/1.7.4.1.txt create mode 100644 Documentation/RelNotes/1.7.4.2.txt create mode 100644 Documentation/RelNotes/1.7.4.3.txt create mode 100644 Documentation/RelNotes/1.7.4.4.txt create mode 100644 Documentation/RelNotes/1.7.4.5.txt create mode 100644 Documentation/RelNotes/1.7.4.txt create mode 100644 Documentation/RelNotes/1.7.5.1.txt create mode 100644 Documentation/RelNotes/1.7.5.2.txt create mode 100644 Documentation/RelNotes/1.7.5.3.txt create mode 100644 Documentation/RelNotes/1.7.5.4.txt create mode 100644 Documentation/RelNotes/1.7.5.txt create mode 100644 Documentation/RelNotes/1.7.6.1.txt create mode 100644 Documentation/RelNotes/1.7.6.2.txt create mode 100644 Documentation/RelNotes/1.7.6.3.txt create mode 100644 Documentation/RelNotes/1.7.6.4.txt create mode 100644 Documentation/RelNotes/1.7.6.5.txt create mode 100644 Documentation/RelNotes/1.7.6.6.txt create mode 100644 Documentation/RelNotes/1.7.6.txt create mode 100644 Documentation/RelNotes/1.7.7.1.txt create mode 100644 Documentation/RelNotes/1.7.7.2.txt create mode 100644 Documentation/RelNotes/1.7.7.3.txt create mode 100644 Documentation/RelNotes/1.7.7.4.txt create mode 100644 Documentation/RelNotes/1.7.7.5.txt create mode 100644 Documentation/RelNotes/1.7.7.6.txt create mode 100644 Documentation/RelNotes/1.7.7.7.txt create mode 100644 Documentation/RelNotes/1.7.7.txt create mode 100644 Documentation/RelNotes/1.7.8.1.txt create mode 100644 Documentation/RelNotes/1.7.8.2.txt create mode 100644 Documentation/RelNotes/1.7.8.3.txt create mode 100644 Documentation/RelNotes/1.7.8.4.txt create mode 100644 Documentation/RelNotes/1.7.8.5.txt create mode 100644 Documentation/RelNotes/1.7.8.6.txt create mode 100644 Documentation/RelNotes/1.7.8.txt create mode 100644 Documentation/RelNotes/1.7.9.1.txt create mode 100644 Documentation/RelNotes/1.7.9.2.txt create mode 100644 Documentation/RelNotes/1.7.9.3.txt create mode 100644 Documentation/RelNotes/1.7.9.4.txt create mode 100644 Documentation/RelNotes/1.7.9.5.txt create mode 100644 Documentation/RelNotes/1.7.9.6.txt create mode 100644 Documentation/RelNotes/1.7.9.7.txt create mode 100644 Documentation/RelNotes/1.7.9.txt create mode 100644 Documentation/RelNotes/1.8.0.1.txt create mode 100644 Documentation/RelNotes/1.8.0.2.txt create mode 100644 Documentation/RelNotes/1.8.0.3.txt create mode 100644 Documentation/RelNotes/1.8.0.txt create mode 100644 Documentation/RelNotes/1.8.1.1.txt create mode 100644 Documentation/RelNotes/1.8.1.2.txt create mode 100644 Documentation/RelNotes/1.8.1.3.txt create mode 100644 Documentation/RelNotes/1.8.1.4.txt create mode 100644 Documentation/RelNotes/1.8.1.5.txt create mode 100644 Documentation/RelNotes/1.8.1.6.txt create mode 100644 Documentation/RelNotes/1.8.1.txt create mode 100644 Documentation/RelNotes/1.8.2.1.txt create mode 100644 Documentation/RelNotes/1.8.2.2.txt create mode 100644 Documentation/RelNotes/1.8.2.3.txt create mode 100644 Documentation/RelNotes/1.8.2.txt create mode 100644 Documentation/RelNotes/1.8.3.1.txt create mode 100644 Documentation/RelNotes/1.8.3.2.txt create mode 100644 Documentation/RelNotes/1.8.3.3.txt create mode 100644 Documentation/RelNotes/1.8.3.4.txt create mode 100644 Documentation/RelNotes/1.8.3.txt create mode 100644 Documentation/RelNotes/1.8.4.1.txt create mode 100644 Documentation/RelNotes/1.8.4.2.txt create mode 100644 Documentation/RelNotes/1.8.4.3.txt create mode 100644 Documentation/RelNotes/1.8.4.4.txt create mode 100644 Documentation/RelNotes/1.8.4.5.txt create mode 100644 Documentation/RelNotes/1.8.4.txt create mode 100644 Documentation/RelNotes/1.8.5.1.txt create mode 100644 Documentation/RelNotes/1.8.5.2.txt create mode 100644 Documentation/RelNotes/1.8.5.3.txt create mode 100644 Documentation/RelNotes/1.8.5.4.txt create mode 100644 Documentation/RelNotes/1.8.5.5.txt create mode 100644 Documentation/RelNotes/1.8.5.6.txt create mode 100644 Documentation/RelNotes/1.8.5.txt create mode 100644 Documentation/RelNotes/1.9.0.txt create mode 100644 Documentation/RelNotes/1.9.1.txt create mode 100644 Documentation/RelNotes/1.9.2.txt create mode 100644 Documentation/RelNotes/1.9.3.txt create mode 100644 Documentation/RelNotes/1.9.4.txt create mode 100644 Documentation/RelNotes/1.9.5.txt create mode 100644 Documentation/RelNotes/2.0.0.txt create mode 100644 Documentation/RelNotes/2.0.1.txt create mode 100644 Documentation/RelNotes/2.0.2.txt create mode 100644 Documentation/RelNotes/2.0.3.txt create mode 100644 Documentation/RelNotes/2.0.4.txt create mode 100644 Documentation/RelNotes/2.0.5.txt create mode 100644 Documentation/RelNotes/2.1.0.txt create mode 100644 Documentation/RelNotes/2.1.1.txt create mode 100644 Documentation/RelNotes/2.1.2.txt create mode 100644 Documentation/RelNotes/2.1.3.txt create mode 100644 Documentation/RelNotes/2.1.4.txt create mode 100644 Documentation/RelNotes/2.10.0.txt create mode 100644 Documentation/RelNotes/2.10.1.txt create mode 100644 Documentation/RelNotes/2.10.2.txt create mode 100644 Documentation/RelNotes/2.10.3.txt create mode 100644 Documentation/RelNotes/2.10.4.txt create mode 100644 Documentation/RelNotes/2.10.5.txt create mode 100644 Documentation/RelNotes/2.11.0.txt create mode 100644 Documentation/RelNotes/2.11.1.txt create mode 100644 Documentation/RelNotes/2.11.2.txt create mode 100644 Documentation/RelNotes/2.11.3.txt create mode 100644 Documentation/RelNotes/2.11.4.txt create mode 100644 Documentation/RelNotes/2.12.0.txt create mode 100644 Documentation/RelNotes/2.12.1.txt create mode 100644 Documentation/RelNotes/2.12.2.txt create mode 100644 Documentation/RelNotes/2.12.3.txt create mode 100644 Documentation/RelNotes/2.12.4.txt create mode 100644 Documentation/RelNotes/2.12.5.txt create mode 100644 Documentation/RelNotes/2.13.0.txt create mode 100644 Documentation/RelNotes/2.13.1.txt create mode 100644 Documentation/RelNotes/2.13.2.txt create mode 100644 Documentation/RelNotes/2.13.3.txt create mode 100644 Documentation/RelNotes/2.13.4.txt create mode 100644 Documentation/RelNotes/2.13.5.txt create mode 100644 Documentation/RelNotes/2.13.6.txt create mode 100644 Documentation/RelNotes/2.13.7.txt create mode 100644 Documentation/RelNotes/2.14.0.txt create mode 100644 Documentation/RelNotes/2.14.1.txt create mode 100644 Documentation/RelNotes/2.14.2.txt create mode 100644 Documentation/RelNotes/2.14.3.txt create mode 100644 Documentation/RelNotes/2.14.4.txt create mode 100644 Documentation/RelNotes/2.14.5.txt create mode 100644 Documentation/RelNotes/2.14.6.txt create mode 100644 Documentation/RelNotes/2.15.0.txt create mode 100644 Documentation/RelNotes/2.15.1.txt create mode 100644 Documentation/RelNotes/2.15.2.txt create mode 100644 Documentation/RelNotes/2.15.3.txt create mode 100644 Documentation/RelNotes/2.15.4.txt create mode 100644 Documentation/RelNotes/2.16.0.txt create mode 100644 Documentation/RelNotes/2.16.1.txt create mode 100644 Documentation/RelNotes/2.16.2.txt create mode 100644 Documentation/RelNotes/2.16.3.txt create mode 100644 Documentation/RelNotes/2.16.4.txt create mode 100644 Documentation/RelNotes/2.16.5.txt create mode 100644 Documentation/RelNotes/2.16.6.txt create mode 100644 Documentation/RelNotes/2.17.0.txt create mode 100644 Documentation/RelNotes/2.17.1.txt create mode 100644 Documentation/RelNotes/2.17.2.txt create mode 100644 Documentation/RelNotes/2.17.3.txt create mode 100644 Documentation/RelNotes/2.17.4.txt create mode 100644 Documentation/RelNotes/2.17.5.txt create mode 100644 Documentation/RelNotes/2.17.6.txt create mode 100644 Documentation/RelNotes/2.18.0.txt create mode 100644 Documentation/RelNotes/2.18.1.txt create mode 100644 Documentation/RelNotes/2.18.2.txt create mode 100644 Documentation/RelNotes/2.18.3.txt create mode 100644 Documentation/RelNotes/2.18.4.txt create mode 100644 Documentation/RelNotes/2.18.5.txt create mode 100644 Documentation/RelNotes/2.19.0.txt create mode 100644 Documentation/RelNotes/2.19.1.txt create mode 100644 Documentation/RelNotes/2.19.2.txt create mode 100644 Documentation/RelNotes/2.19.3.txt create mode 100644 Documentation/RelNotes/2.19.4.txt create mode 100644 Documentation/RelNotes/2.19.5.txt create mode 100644 Documentation/RelNotes/2.19.6.txt create mode 100644 Documentation/RelNotes/2.2.0.txt create mode 100644 Documentation/RelNotes/2.2.1.txt create mode 100644 Documentation/RelNotes/2.2.2.txt create mode 100644 Documentation/RelNotes/2.2.3.txt create mode 100644 Documentation/RelNotes/2.20.0.txt create mode 100644 Documentation/RelNotes/2.20.1.txt create mode 100644 Documentation/RelNotes/2.20.2.txt create mode 100644 Documentation/RelNotes/2.20.3.txt create mode 100644 Documentation/RelNotes/2.20.4.txt create mode 100644 Documentation/RelNotes/2.20.5.txt create mode 100644 Documentation/RelNotes/2.21.0.txt create mode 100644 Documentation/RelNotes/2.21.1.txt create mode 100644 Documentation/RelNotes/2.21.2.txt create mode 100644 Documentation/RelNotes/2.21.3.txt create mode 100644 Documentation/RelNotes/2.21.4.txt create mode 100644 Documentation/RelNotes/2.22.0.txt create mode 100644 Documentation/RelNotes/2.22.1.txt create mode 100644 Documentation/RelNotes/2.22.2.txt create mode 100644 Documentation/RelNotes/2.22.3.txt create mode 100644 Documentation/RelNotes/2.22.4.txt create mode 100644 Documentation/RelNotes/2.22.5.txt create mode 100644 Documentation/RelNotes/2.23.0.txt create mode 100644 Documentation/RelNotes/2.23.1.txt create mode 100644 Documentation/RelNotes/2.23.2.txt create mode 100644 Documentation/RelNotes/2.23.3.txt create mode 100644 Documentation/RelNotes/2.23.4.txt create mode 100644 Documentation/RelNotes/2.24.0.txt create mode 100644 Documentation/RelNotes/2.24.1.txt create mode 100644 Documentation/RelNotes/2.24.2.txt create mode 100644 Documentation/RelNotes/2.24.3.txt create mode 100644 Documentation/RelNotes/2.24.4.txt create mode 100644 Documentation/RelNotes/2.25.0.txt create mode 100644 Documentation/RelNotes/2.25.1.txt create mode 100644 Documentation/RelNotes/2.25.2.txt create mode 100644 Documentation/RelNotes/2.25.3.txt create mode 100644 Documentation/RelNotes/2.25.4.txt create mode 100644 Documentation/RelNotes/2.25.5.txt create mode 100644 Documentation/RelNotes/2.26.0.txt create mode 100644 Documentation/RelNotes/2.26.1.txt create mode 100644 Documentation/RelNotes/2.26.2.txt create mode 100644 Documentation/RelNotes/2.26.3.txt create mode 100644 Documentation/RelNotes/2.27.0.txt create mode 100644 Documentation/RelNotes/2.27.1.txt create mode 100644 Documentation/RelNotes/2.28.0.txt create mode 100644 Documentation/RelNotes/2.28.1.txt create mode 100644 Documentation/RelNotes/2.29.0.txt create mode 100644 Documentation/RelNotes/2.29.1.txt create mode 100644 Documentation/RelNotes/2.29.2.txt create mode 100644 Documentation/RelNotes/2.29.3.txt create mode 100644 Documentation/RelNotes/2.3.0.txt create mode 100644 Documentation/RelNotes/2.3.1.txt create mode 100644 Documentation/RelNotes/2.3.10.txt create mode 100644 Documentation/RelNotes/2.3.2.txt create mode 100644 Documentation/RelNotes/2.3.3.txt create mode 100644 Documentation/RelNotes/2.3.4.txt create mode 100644 Documentation/RelNotes/2.3.5.txt create mode 100644 Documentation/RelNotes/2.3.6.txt create mode 100644 Documentation/RelNotes/2.3.7.txt create mode 100644 Documentation/RelNotes/2.3.8.txt create mode 100644 Documentation/RelNotes/2.3.9.txt create mode 100644 Documentation/RelNotes/2.30.0.txt create mode 100644 Documentation/RelNotes/2.30.1.txt create mode 100644 Documentation/RelNotes/2.30.2.txt create mode 100644 Documentation/RelNotes/2.4.0.txt create mode 100644 Documentation/RelNotes/2.4.1.txt create mode 100644 Documentation/RelNotes/2.4.10.txt create mode 100644 Documentation/RelNotes/2.4.11.txt create mode 100644 Documentation/RelNotes/2.4.12.txt create mode 100644 Documentation/RelNotes/2.4.2.txt create mode 100644 Documentation/RelNotes/2.4.3.txt create mode 100644 Documentation/RelNotes/2.4.4.txt create mode 100644 Documentation/RelNotes/2.4.5.txt create mode 100644 Documentation/RelNotes/2.4.6.txt create mode 100644 Documentation/RelNotes/2.4.7.txt create mode 100644 Documentation/RelNotes/2.4.8.txt create mode 100644 Documentation/RelNotes/2.4.9.txt create mode 100644 Documentation/RelNotes/2.5.0.txt create mode 100644 Documentation/RelNotes/2.5.1.txt create mode 100644 Documentation/RelNotes/2.5.2.txt create mode 100644 Documentation/RelNotes/2.5.3.txt create mode 100644 Documentation/RelNotes/2.5.4.txt create mode 100644 Documentation/RelNotes/2.5.5.txt create mode 100644 Documentation/RelNotes/2.5.6.txt create mode 100644 Documentation/RelNotes/2.6.0.txt create mode 100644 Documentation/RelNotes/2.6.1.txt create mode 100644 Documentation/RelNotes/2.6.2.txt create mode 100644 Documentation/RelNotes/2.6.3.txt create mode 100644 Documentation/RelNotes/2.6.4.txt create mode 100644 Documentation/RelNotes/2.6.5.txt create mode 100644 Documentation/RelNotes/2.6.6.txt create mode 100644 Documentation/RelNotes/2.6.7.txt create mode 100644 Documentation/RelNotes/2.7.0.txt create mode 100644 Documentation/RelNotes/2.7.1.txt create mode 100644 Documentation/RelNotes/2.7.2.txt create mode 100644 Documentation/RelNotes/2.7.3.txt create mode 100644 Documentation/RelNotes/2.7.4.txt create mode 100644 Documentation/RelNotes/2.7.5.txt create mode 100644 Documentation/RelNotes/2.7.6.txt create mode 100644 Documentation/RelNotes/2.8.0.txt create mode 100644 Documentation/RelNotes/2.8.1.txt create mode 100644 Documentation/RelNotes/2.8.2.txt create mode 100644 Documentation/RelNotes/2.8.3.txt create mode 100644 Documentation/RelNotes/2.8.4.txt create mode 100644 Documentation/RelNotes/2.8.5.txt create mode 100644 Documentation/RelNotes/2.8.6.txt create mode 100644 Documentation/RelNotes/2.9.0.txt create mode 100644 Documentation/RelNotes/2.9.1.txt create mode 100644 Documentation/RelNotes/2.9.2.txt create mode 100644 Documentation/RelNotes/2.9.3.txt create mode 100644 Documentation/RelNotes/2.9.4.txt create mode 100644 Documentation/RelNotes/2.9.5.txt create mode 100644 Documentation/SubmittingPatches create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/asciidoctor-extensions.rb create mode 100644 Documentation/blame-options.txt create mode 100755 Documentation/build-docdep.perl create mode 100755 Documentation/cat-texi.perl create mode 100755 Documentation/cmd-list.perl create mode 100644 Documentation/config.txt create mode 100644 Documentation/config/add.txt create mode 100644 Documentation/config/advice.txt create mode 100644 Documentation/config/alias.txt create mode 100644 Documentation/config/am.txt create mode 100644 Documentation/config/apply.txt create mode 100644 Documentation/config/blame.txt create mode 100644 Documentation/config/branch.txt create mode 100644 Documentation/config/browser.txt create mode 100644 Documentation/config/checkout.txt create mode 100644 Documentation/config/clean.txt create mode 100644 Documentation/config/clone.txt create mode 100644 Documentation/config/color.txt create mode 100644 Documentation/config/column.txt create mode 100644 Documentation/config/commit.txt create mode 100644 Documentation/config/commitgraph.txt create mode 100644 Documentation/config/completion.txt create mode 100644 Documentation/config/core.txt create mode 100644 Documentation/config/credential.txt create mode 100644 Documentation/config/diff.txt create mode 100644 Documentation/config/difftool.txt create mode 100644 Documentation/config/extensions.txt create mode 100644 Documentation/config/fastimport.txt create mode 100644 Documentation/config/feature.txt create mode 100644 Documentation/config/fetch.txt create mode 100644 Documentation/config/filter.txt create mode 100644 Documentation/config/fmt-merge-msg.txt create mode 100644 Documentation/config/format.txt create mode 100644 Documentation/config/fsck.txt create mode 100644 Documentation/config/gc.txt create mode 100644 Documentation/config/gitcvs.txt create mode 100644 Documentation/config/gitweb.txt create mode 100644 Documentation/config/gpg.txt create mode 100644 Documentation/config/grep.txt create mode 100644 Documentation/config/gui.txt create mode 100644 Documentation/config/guitool.txt create mode 100644 Documentation/config/help.txt create mode 100644 Documentation/config/http.txt create mode 100644 Documentation/config/i18n.txt create mode 100644 Documentation/config/imap.txt create mode 100644 Documentation/config/index.txt create mode 100644 Documentation/config/init.txt create mode 100644 Documentation/config/instaweb.txt create mode 100644 Documentation/config/interactive.txt create mode 100644 Documentation/config/log.txt create mode 100644 Documentation/config/mailinfo.txt create mode 100644 Documentation/config/mailmap.txt create mode 100644 Documentation/config/maintenance.txt create mode 100644 Documentation/config/man.txt create mode 100644 Documentation/config/merge.txt create mode 100644 Documentation/config/mergetool.txt create mode 100644 Documentation/config/notes.txt create mode 100644 Documentation/config/pack.txt create mode 100644 Documentation/config/pager.txt create mode 100644 Documentation/config/pretty.txt create mode 100644 Documentation/config/protocol.txt create mode 100644 Documentation/config/pull.txt create mode 100644 Documentation/config/push.txt create mode 100644 Documentation/config/rebase.txt create mode 100644 Documentation/config/receive.txt create mode 100644 Documentation/config/remote.txt create mode 100644 Documentation/config/remotes.txt create mode 100644 Documentation/config/repack.txt create mode 100644 Documentation/config/rerere.txt create mode 100644 Documentation/config/reset.txt create mode 100644 Documentation/config/sendemail.txt create mode 100644 Documentation/config/sequencer.txt create mode 100644 Documentation/config/showbranch.txt create mode 100644 Documentation/config/splitindex.txt create mode 100644 Documentation/config/ssh.txt create mode 100644 Documentation/config/stash.txt create mode 100644 Documentation/config/status.txt create mode 100644 Documentation/config/submodule.txt create mode 100644 Documentation/config/tag.txt create mode 100644 Documentation/config/tar.txt create mode 100644 Documentation/config/trace2.txt create mode 100644 Documentation/config/transfer.txt create mode 100644 Documentation/config/uploadarchive.txt create mode 100644 Documentation/config/uploadpack.txt create mode 100644 Documentation/config/url.txt create mode 100644 Documentation/config/user.txt create mode 100644 Documentation/config/versionsort.txt create mode 100644 Documentation/config/web.txt create mode 100644 Documentation/config/worktree.txt create mode 100644 Documentation/date-formats.txt create mode 100644 Documentation/diff-format.txt create mode 100644 Documentation/diff-generate-patch.txt create mode 100644 Documentation/diff-options.txt create mode 100755 Documentation/doc-diff create mode 100644 Documentation/docbook-xsl.css create mode 100644 Documentation/docbook.xsl create mode 100644 Documentation/everyday.txto create mode 100644 Documentation/fetch-options.txt create mode 100755 Documentation/fix-texi.perl create mode 100644 Documentation/git-add.txt create mode 100644 Documentation/git-am.txt create mode 100644 Documentation/git-annotate.txt create mode 100644 Documentation/git-apply.txt create mode 100644 Documentation/git-archimport.txt create mode 100644 Documentation/git-archive.txt create mode 100644 Documentation/git-bisect-lk2009.txt create mode 100644 Documentation/git-bisect.txt create mode 100644 Documentation/git-blame.txt create mode 100644 Documentation/git-branch.txt create mode 100644 Documentation/git-bugreport.txt create mode 100644 Documentation/git-bundle.txt create mode 100644 Documentation/git-cat-file.txt create mode 100644 Documentation/git-check-attr.txt create mode 100644 Documentation/git-check-ignore.txt create mode 100644 Documentation/git-check-mailmap.txt create mode 100644 Documentation/git-check-ref-format.txt create mode 100644 Documentation/git-checkout-index.txt create mode 100644 Documentation/git-checkout.txt create mode 100644 Documentation/git-cherry-pick.txt create mode 100644 Documentation/git-cherry.txt create mode 100644 Documentation/git-citool.txt create mode 100644 Documentation/git-clean.txt create mode 100644 Documentation/git-clone.txt create mode 100644 Documentation/git-column.txt create mode 100644 Documentation/git-commit-graph.txt create mode 100644 Documentation/git-commit-tree.txt create mode 100644 Documentation/git-commit.txt create mode 100644 Documentation/git-config.txt create mode 100644 Documentation/git-count-objects.txt create mode 100644 Documentation/git-credential-cache--daemon.txt create mode 100644 Documentation/git-credential-cache.txt create mode 100644 Documentation/git-credential-store.txt create mode 100644 Documentation/git-credential.txt create mode 100644 Documentation/git-cvsexportcommit.txt create mode 100644 Documentation/git-cvsimport.txt create mode 100644 Documentation/git-cvsserver.txt create mode 100644 Documentation/git-daemon.txt create mode 100644 Documentation/git-describe.txt create mode 100644 Documentation/git-diff-files.txt create mode 100644 Documentation/git-diff-index.txt create mode 100644 Documentation/git-diff-tree.txt create mode 100644 Documentation/git-diff.txt create mode 100644 Documentation/git-difftool.txt create mode 100644 Documentation/git-fast-export.txt create mode 100644 Documentation/git-fast-import.txt create mode 100644 Documentation/git-fetch-pack.txt create mode 100644 Documentation/git-fetch.txt create mode 100644 Documentation/git-filter-branch.txt create mode 100644 Documentation/git-fmt-merge-msg.txt create mode 100644 Documentation/git-for-each-ref.txt create mode 100644 Documentation/git-for-each-repo.txt create mode 100644 Documentation/git-format-patch.txt create mode 100644 Documentation/git-fsck-objects.txt create mode 100644 Documentation/git-fsck.txt create mode 100644 Documentation/git-gc.txt create mode 100644 Documentation/git-get-tar-commit-id.txt create mode 100644 Documentation/git-grep.txt create mode 100644 Documentation/git-gui.txt create mode 100644 Documentation/git-hash-object.txt create mode 100644 Documentation/git-help.txt create mode 100644 Documentation/git-http-backend.txt create mode 100644 Documentation/git-http-fetch.txt create mode 100644 Documentation/git-http-push.txt create mode 100644 Documentation/git-imap-send.txt create mode 100644 Documentation/git-index-pack.txt create mode 100644 Documentation/git-init-db.txt create mode 100644 Documentation/git-init.txt create mode 100644 Documentation/git-instaweb.txt create mode 100644 Documentation/git-interpret-trailers.txt create mode 100644 Documentation/git-log.txt create mode 100644 Documentation/git-ls-files.txt create mode 100644 Documentation/git-ls-remote.txt create mode 100644 Documentation/git-ls-tree.txt create mode 100644 Documentation/git-mailinfo.txt create mode 100644 Documentation/git-mailsplit.txt create mode 100644 Documentation/git-maintenance.txt create mode 100644 Documentation/git-merge-base.txt create mode 100644 Documentation/git-merge-file.txt create mode 100644 Documentation/git-merge-index.txt create mode 100644 Documentation/git-merge-one-file.txt create mode 100644 Documentation/git-merge-tree.txt create mode 100644 Documentation/git-merge.txt create mode 100644 Documentation/git-mergetool--lib.txt create mode 100644 Documentation/git-mergetool.txt create mode 100644 Documentation/git-mktag.txt create mode 100644 Documentation/git-mktree.txt create mode 100644 Documentation/git-multi-pack-index.txt create mode 100644 Documentation/git-mv.txt create mode 100644 Documentation/git-name-rev.txt create mode 100644 Documentation/git-notes.txt create mode 100644 Documentation/git-p4.txt create mode 100644 Documentation/git-pack-objects.txt create mode 100644 Documentation/git-pack-redundant.txt create mode 100644 Documentation/git-pack-refs.txt create mode 100644 Documentation/git-patch-id.txt create mode 100644 Documentation/git-prune-packed.txt create mode 100644 Documentation/git-prune.txt create mode 100644 Documentation/git-pull.txt create mode 100644 Documentation/git-push.txt create mode 100644 Documentation/git-quiltimport.txt create mode 100644 Documentation/git-range-diff.txt create mode 100644 Documentation/git-read-tree.txt create mode 100644 Documentation/git-rebase.txt create mode 100644 Documentation/git-receive-pack.txt create mode 100644 Documentation/git-reflog.txt create mode 100644 Documentation/git-remote-ext.txt create mode 100644 Documentation/git-remote-fd.txt create mode 100644 Documentation/git-remote-helpers.txto create mode 100644 Documentation/git-remote.txt create mode 100644 Documentation/git-repack.txt create mode 100644 Documentation/git-replace.txt create mode 100644 Documentation/git-request-pull.txt create mode 100644 Documentation/git-rerere.txt create mode 100644 Documentation/git-reset.txt create mode 100644 Documentation/git-restore.txt create mode 100644 Documentation/git-rev-list.txt create mode 100644 Documentation/git-rev-parse.txt create mode 100644 Documentation/git-revert.txt create mode 100644 Documentation/git-rm.txt create mode 100644 Documentation/git-send-email.txt create mode 100644 Documentation/git-send-pack.txt create mode 100644 Documentation/git-sh-i18n--envsubst.txt create mode 100644 Documentation/git-sh-i18n.txt create mode 100644 Documentation/git-sh-setup.txt create mode 100644 Documentation/git-shell.txt create mode 100644 Documentation/git-shortlog.txt create mode 100644 Documentation/git-show-branch.txt create mode 100644 Documentation/git-show-index.txt create mode 100644 Documentation/git-show-ref.txt create mode 100644 Documentation/git-show.txt create mode 100644 Documentation/git-sparse-checkout.txt create mode 100644 Documentation/git-stage.txt create mode 100644 Documentation/git-stash.txt create mode 100644 Documentation/git-status.txt create mode 100644 Documentation/git-stripspace.txt create mode 100644 Documentation/git-submodule.txt create mode 100644 Documentation/git-svn.txt create mode 100644 Documentation/git-switch.txt create mode 100644 Documentation/git-symbolic-ref.txt create mode 100644 Documentation/git-tag.txt create mode 100644 Documentation/git-tools.txt create mode 100644 Documentation/git-unpack-file.txt create mode 100644 Documentation/git-unpack-objects.txt create mode 100644 Documentation/git-update-index.txt create mode 100644 Documentation/git-update-ref.txt create mode 100644 Documentation/git-update-server-info.txt create mode 100644 Documentation/git-upload-archive.txt create mode 100644 Documentation/git-upload-pack.txt create mode 100644 Documentation/git-var.txt create mode 100644 Documentation/git-verify-commit.txt create mode 100644 Documentation/git-verify-pack.txt create mode 100644 Documentation/git-verify-tag.txt create mode 100644 Documentation/git-web--browse.txt create mode 100644 Documentation/git-whatchanged.txt create mode 100644 Documentation/git-worktree.txt create mode 100644 Documentation/git-write-tree.txt create mode 100644 Documentation/git.txt create mode 100644 Documentation/gitattributes.txt create mode 100644 Documentation/gitcli.txt create mode 100644 Documentation/gitcore-tutorial.txt create mode 100644 Documentation/gitcredentials.txt create mode 100644 Documentation/gitcvs-migration.txt create mode 100644 Documentation/gitdiffcore.txt create mode 100644 Documentation/giteveryday.txt create mode 100644 Documentation/gitfaq.txt create mode 100644 Documentation/gitglossary.txt create mode 100644 Documentation/githooks.txt create mode 100644 Documentation/gitignore.txt create mode 100644 Documentation/gitk.txt create mode 100644 Documentation/gitmodules.txt create mode 100644 Documentation/gitnamespaces.txt create mode 100644 Documentation/gitremote-helpers.txt create mode 100644 Documentation/gitrepository-layout.txt create mode 100644 Documentation/gitrevisions.txt create mode 100644 Documentation/gitsubmodules.txt create mode 100644 Documentation/gittutorial-2.txt create mode 100644 Documentation/gittutorial.txt create mode 100644 Documentation/gitweb.conf.txt create mode 100644 Documentation/gitweb.txt create mode 100644 Documentation/gitworkflows.txt create mode 100644 Documentation/glossary-content.txt create mode 100755 Documentation/howto-index.sh create mode 100644 Documentation/howto/keep-canonical-history-correct.txt create mode 100644 Documentation/howto/maintain-git.txt create mode 100644 Documentation/howto/new-command.txt create mode 100644 Documentation/howto/rebase-from-internal-branch.txt create mode 100644 Documentation/howto/rebuild-from-update-hook.txt create mode 100644 Documentation/howto/recover-corrupted-blob-object.txt create mode 100644 Documentation/howto/recover-corrupted-object-harder.txt create mode 100644 Documentation/howto/revert-a-faulty-merge.txt create mode 100644 Documentation/howto/revert-branch-rebase.txt create mode 100644 Documentation/howto/separating-topic-branches.txt create mode 100644 Documentation/howto/setup-git-server-over-http.txt create mode 100644 Documentation/howto/update-hook-example.txt create mode 100644 Documentation/howto/use-git-daemon.txt create mode 100644 Documentation/howto/using-merge-subtree.txt create mode 100644 Documentation/howto/using-signed-tag-in-pull-request.txt create mode 100644 Documentation/i18n.txt create mode 100755 Documentation/install-doc-quick.sh create mode 100755 Documentation/install-webdoc.sh create mode 100644 Documentation/line-range-format.txt create mode 100644 Documentation/line-range-options.txt create mode 100755 Documentation/lint-gitlink.perl create mode 100644 Documentation/mailmap.txt create mode 100644 Documentation/manpage-base-url.xsl.in create mode 100644 Documentation/manpage-bold-literal.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/manpage-quote-apos.xsl create mode 100644 Documentation/manpage.xsl create mode 100644 Documentation/merge-options.txt create mode 100644 Documentation/merge-strategies.txt create mode 100644 Documentation/object-format-disclaimer.txt create mode 100644 Documentation/pretty-formats.txt create mode 100644 Documentation/pretty-options.txt create mode 100644 Documentation/pull-fetch-param.txt create mode 100644 Documentation/ref-reachability-filters.txt create mode 100644 Documentation/rev-list-description.txt create mode 100644 Documentation/rev-list-options.txt create mode 100644 Documentation/revisions.txt create mode 100644 Documentation/sequencer.txt create mode 100644 Documentation/signoff-option.txt create mode 100644 Documentation/technical/.gitignore create mode 100644 Documentation/technical/api-error-handling.txt create mode 100644 Documentation/technical/api-index-skel.txt create mode 100755 Documentation/technical/api-index.sh create mode 100644 Documentation/technical/api-merge.txt create mode 100644 Documentation/technical/api-parse-options.txt create mode 100644 Documentation/technical/api-trace2.txt create mode 100644 Documentation/technical/bitmap-format.txt create mode 100644 Documentation/technical/bundle-format.txt create mode 100644 Documentation/technical/commit-graph-format.txt create mode 100644 Documentation/technical/commit-graph.txt create mode 100644 Documentation/technical/directory-rename-detection.txt create mode 100644 Documentation/technical/hash-function-transition.txt create mode 100644 Documentation/technical/http-protocol.txt create mode 100644 Documentation/technical/index-format.txt create mode 100644 Documentation/technical/long-running-process-protocol.txt create mode 100644 Documentation/technical/multi-pack-index.txt create mode 100644 Documentation/technical/pack-format.txt create mode 100644 Documentation/technical/pack-heuristics.txt create mode 100644 Documentation/technical/pack-protocol.txt create mode 100644 Documentation/technical/packfile-uri.txt create mode 100644 Documentation/technical/partial-clone.txt create mode 100644 Documentation/technical/protocol-capabilities.txt create mode 100644 Documentation/technical/protocol-common.txt create mode 100644 Documentation/technical/protocol-v2.txt create mode 100644 Documentation/technical/racy-git.txt create mode 100644 Documentation/technical/reftable.txt create mode 100644 Documentation/technical/repository-version.txt create mode 100644 Documentation/technical/rerere.txt create mode 100644 Documentation/technical/send-pack-pipeline.txt create mode 100644 Documentation/technical/shallow.txt create mode 100644 Documentation/technical/signature-format.txt create mode 100644 Documentation/technical/trivial-merge.txt create mode 100644 Documentation/texi.xsl create mode 100644 Documentation/trace2-target-values.txt create mode 100644 Documentation/transfer-data-leaks.txt create mode 100644 Documentation/urls-remotes.txt create mode 100644 Documentation/urls.txt create mode 100644 Documentation/user-manual.conf create mode 100644 Documentation/user-manual.txt (limited to 'Documentation') diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes new file mode 100644 index 0000000..ddb0301 --- /dev/null +++ b/Documentation/.gitattributes @@ -0,0 +1 @@ +*.txt whitespace diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..9022d48 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,17 @@ +*.xml +*.html +*.[1-8] +*.made +*.texi +*.pdf +git.info +gitman.info +howto-index.txt +doc.dep +cmds-*.txt +mergetools-*.txt +manpage-base-url.xsl +SubmittingPatches.txt +tmp-doc-diff/ +GIT-ASCIIDOCFLAGS +/GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines new file mode 100644 index 0000000..45465bc --- /dev/null +++ b/Documentation/CodingGuidelines @@ -0,0 +1,640 @@ +Like other projects, we also have some guidelines to keep to the +code. For Git in general, a few rough rules are: + + - Most importantly, we never say "It's in POSIX; we'll happily + ignore your needs should your system not conform to it." + We live in the real world. + + - However, we often say "Let's stay away from that construct, + it's not even in POSIX". + + - In spite of the above two rules, we sometimes say "Although + this is not in POSIX, it (is so convenient | makes the code + much more readable | has other good characteristics) and + practically all the platforms we care about support it, so + let's use it". + + Again, we live in the real world, and it is sometimes a + judgement call, the decision based more on real world + constraints people face than what the paper standard says. + + - Fixing style violations while working on a real change as a + preparatory clean-up step is good, but otherwise avoid useless code + churn for the sake of conforming to the style. + + "Once it _is_ in the tree, it's not really worth the patch noise to + go and fix it up." + Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + +Make your code readable and sensible, and don't try to be clever. + +As for more concrete guidelines, just imitate the existing code +(this is a good guideline, no matter which project you are +contributing to). It is always preferable to match the _local_ +convention. New code added to Git suite is expected to match +the overall style of existing code. Modifications to existing +code is expected to match the style the surrounding code already +uses (even if it doesn't match the overall style of existing code). + +But if you must have a list of rules, here they are. + +For shell scripts specifically (not exhaustive): + + - We use tabs for indentation. + + - Case arms are indented at the same depth as case and esac lines, + like this: + + case "$variable" in + pattern1) + do this + ;; + pattern2) + do that + ;; + esac + + - Redirection operators should be written with space before, but no + space after them. In other words, write 'echo test >"$file"' + instead of 'echo test> $file' or 'echo test > $file'. Note that + even though it is not required by POSIX to double-quote the + redirection target in a variable (as shown above), our code does so + because some versions of bash issue a warning without the quotes. + + (incorrect) + cat hello > world < universe + echo hello >$world + + (correct) + cat hello >world "$world" + + - We prefer $( ... ) for command substitution; unlike ``, it + properly nests. It should have been the way Bourne spelled + it from day one, but unfortunately isn't. + + - If you want to find out if a command is available on the user's + $PATH, you should use 'type ', instead of 'which '. + The output of 'which' is not machine parsable and its exit code + is not reliable across platforms. + + - We use POSIX compliant parameter substitutions and avoid bashisms; + namely: + + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. + + - We use ${parameter#word} and its [#%] siblings, and their + doubled "longest matching" form. + + - No "Substring Expansion" ${parameter:offset:length}. + + - No shell arrays. + + - No pattern replacement ${parameter/pattern/string}. + + - We use Arithmetic Expansion $(( ... )). + + - We do not use Process Substitution <(list) or >(list). + + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + + (incorrect) + if test -f hello; then + do this + fi + + (correct) + if test -f hello + then + do this + fi + + - If a command sequence joined with && or || or | spans multiple + lines, put each command on a separate line and put && and || and | + operators at the end of each line, rather than the start. This + means you don't need to use \ to join lines, since the above + operators imply the sequence isn't finished. + + (incorrect) + grep blob verify_pack_result \ + | awk -f print_1.awk \ + | sort >actual && + ... + + (correct) + grep blob verify_pack_result | + awk -f print_1.awk | + sort >actual && + ... + + - We prefer "test" over "[ ... ]". + + - We do not write the noiseword "function" in front of shell + functions. + + - We prefer a space between the function name and the parentheses, + and no space inside the parentheses. The opening "{" should also + be on the same line. + + (incorrect) + my_function(){ + ... + + (correct) + my_function () { + ... + + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, + [::], [==], or [..]) for portability. + + - We do not use \{m,n\}; + + - We do not use -E; + + - We do not use ? or + (which are \{0,1\} and \{1,\} + respectively in BRE) but that goes without saying as these + are ERE elements not BRE (note that \? and \+ are not even part + of BRE -- making them accessible from BRE is a GNU extension). + + - Use Git's gettext wrappers in git-sh-i18n to make the user + interface translatable. See "Marking strings for translation" in + po/README. + + - We do not write our "test" command with "-a" and "-o" and use "&&" + or "||" to concatenate multiple "test" commands instead, because + the use of "-a/-o" is often error-prone. E.g. + + test -n "$x" -a "$a" = "$b" + + is buggy and breaks when $x is "=", but + + test -n "$x" && test "$a" = "$b" + + does not have such a problem. + + +For C programs: + + - We use tabs to indent, and interpret tabs as taking up to + 8 spaces. + + - We try to keep to at most 80 characters per line. + + - As a Git developer we assume you have a reasonably modern compiler + and we recommend you to enable the DEVELOPER makefile knob to + ensure your patch is clear of all compiler warnings we care about, + by e.g. "echo DEVELOPER=1 >>config.mak". + + - We try to support a wide range of C compilers to compile Git with, + including old ones. You should not use features from newer C + standard, even if your compiler groks them. + + There are a few exceptions to this guideline: + + . since early 2012 with e1327023ea, we have been using an enum + definition whose last element is followed by a comma. This, like + an array initializer that ends with a trailing comma, can be used + to reduce the patch noise when adding a new identifier at the end. + + . since mid 2017 with cbc0f81d, we have been using designated + initializers for struct (e.g. "struct t v = { .val = 'a' };"). + + . since mid 2017 with 512f41cf, we have been using designated + initializers for array (e.g. "int array[10] = { [5] = 2 }"). + + These used to be forbidden, but we have not heard any breakage + report, and they are assumed to be safe. + + - Variables have to be declared at the beginning of the block, before + the first statement (i.e. -Wdeclaration-after-statement). + + - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)" + is still not allowed in this codebase. + + - NULL pointers shall be written as NULL, not as 0. + + - When declaring pointers, the star sides with the variable + name, i.e. "char *string", not "char* string" or + "char * string". This makes it easier to understand code + like "char *string, c;". + + - Use whitespace around operators and keywords, but not inside + parentheses and not around functions. So: + + while (condition) + func(bar + 1); + + and not: + + while( condition ) + func (bar+1); + + - Do not explicitly compare an integral value with constant 0 or '\0', + or a pointer value with constant NULL. For instance, to validate that + counted array is initialized but has no elements, write: + + if (!ptr || cnt) + BUG("empty array expected"); + + and not: + + if (ptr == NULL || cnt != 0); + BUG("empty array expected"); + + - We avoid using braces unnecessarily. I.e. + + if (bla) { + x = 1; + } + + is frowned upon. But there are a few exceptions: + + - When the statement extends over a few lines (e.g., a while loop + with an embedded conditional, or a comment). E.g.: + + while (foo) { + if (x) + one(); + else + two(); + } + + if (foo) { + /* + * This one requires some explanation, + * so we're better off with braces to make + * it obvious that the indentation is correct. + */ + doit(); + } + + - When there are multiple arms to a conditional and some of them + require braces, enclose even a single line block in braces for + consistency. E.g.: + + if (foo) { + doit(); + } else { + one(); + two(); + three(); + } + + - We try to avoid assignments in the condition of an "if" statement. + + - Try to make your code understandable. You may put comments + in, but comments invariably tend to stale out when the code + they were describing changes. Often splitting a function + into two makes the intention of the code much clearer. + + - Multi-line comments include their delimiters on separate lines from + the text. E.g. + + /* + * A very long + * multi-line comment. + */ + + Note however that a comment that explains a translatable string to + translators uses a convention of starting with a magic token + "TRANSLATORS: ", e.g. + + /* + * TRANSLATORS: here is a comment that explains the string to + * be translated, that follows immediately after it. + */ + _("Here is a translatable string explained by the above."); + + - Double negation is often harder to understand than no negation + at all. + + - There are two schools of thought when it comes to comparison, + especially inside a loop. Some people prefer to have the less stable + value on the left hand side and the more stable value on the right hand + side, e.g. if you have a loop that counts variable i down to the + lower bound, + + while (i > lower_bound) { + do something; + i--; + } + + Other people prefer to have the textual order of values match the + actual order of values in their comparison, so that they can + mentally draw a number line from left to right and place these + values in order, i.e. + + while (lower_bound < i) { + do something; + i--; + } + + Both are valid, and we use both. However, the more "stable" the + stable side becomes, the more we tend to prefer the former + (comparison with a constant, "i > 0", is an extreme example). + Just do not mix styles in the same part of the code and mimic + existing styles in the neighbourhood. + + - There are two schools of thought when it comes to splitting a long + logical line into multiple lines. Some people push the second and + subsequent lines far enough to the right with tabs and align them: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of || + the_source_text) { + ... + + while other people prefer to align the second and the subsequent + lines with the column immediately inside the opening parenthesis, + with tabs and spaces, following our "tabstop is always a multiple + of 8" convention: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of || + the_source_text) { + ... + + Both are valid, and we use both. Again, just do not mix styles in + the same part of the code and mimic existing styles in the + neighbourhood. + + - When splitting a long logical line, some people change line before + a binary operator, so that the result looks like a parse tree when + you turn your head 90-degrees counterclockwise: + + if (the_beginning_of_a_very_long_expression_that_has_to + || span_more_than_a_single_line_of_the_source_text) { + + while other people prefer to leave the operator at the end of the + line: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of_the_source_text) { + + Both are valid, but we tend to use the latter more, unless the + expression gets fairly complex, in which case the former tends to + be easier to read. Again, just do not mix styles in the same part + of the code and mimic existing styles in the neighbourhood. + + - When splitting a long logical line, with everything else being + equal, it is preferable to split after the operator at higher + level in the parse tree. That is, this is more preferable: + + if (a_very_long_variable * that_is_used_in + + a_very_long_expression) { + ... + + than + + if (a_very_long_variable * + that_is_used_in + a_very_long_expression) { + ... + + - Some clever tricks, like using the !! operator with arithmetic + constructs, can be extremely confusing to others. Avoid them, + unless there is a compelling reason to use them. + + - Use the API. No, really. We have a strbuf (variable length + string), several arrays with the ALLOC_GROW() macro, a + string_list for sorted string lists, a hash map (mapping struct + objects) named "struct decorate", amongst other things. + + - When you come up with an API, document its functions and structures + in the header file that exposes the API to its callers. Use what is + in "strbuf.h" as a model for the appropriate tone and level of + detail. + + - The first #include in C files, except in platform specific compat/ + implementations, must be either "git-compat-util.h", "cache.h" or + "builtin.h". You do not have to include more than one of these. + + - A C file must directly include the header files that declare the + functions and the types it uses, except for the functions and types + that are made available to it by including one of the header files + it must include by the previous rule. + + - If you are planning a new command, consider writing it in shell + or perl first, so that changes in semantics can be easily + changed and discussed. Many Git commands started out like + that, and a few are still scripts. + + - Avoid introducing a new dependency into Git. This means you + usually should stay away from scripting languages not already + used in the Git core command set (unless your command is clearly + separate from it, such as an importer to convert random-scm-X + repositories to Git). + + - When we pass pair to functions, we should try to + pass them in that order. + + - Use Git's gettext wrappers to make the user interface + translatable. See "Marking strings for translation" in po/README. + + - Variables and functions local to a given source file should be marked + with "static". Variables that are visible to other source files + must be declared with "extern" in header files. However, function + declarations should not use "extern", as that is already the default. + + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=" " ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + +For Perl programs: + + - Most of the C guidelines above apply. + + - We try to support Perl 5.8 and later ("use Perl 5.008"). + + - use strict and use warnings are strongly preferred. + + - Don't overuse statement modifiers unless using them makes the + result easier to follow. + + ... do something ... + do_this() unless (condition); + ... do something else ... + + is more readable than: + + ... do something ... + unless (condition) { + do_this(); + } + ... do something else ... + + *only* when the condition is so rare that do_this() will be almost + always called. + + - We try to avoid assignments inside "if ()" conditions. + + - Learn and use Git.pm if you need that functionality. + + - For Emacs, it's useful to put the following in + GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: + + ;; note the first part is useful for C editing, too + ((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) + +For Python scripts: + + - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). + + - As a minimum, we aim to be compatible with Python 2.7. + + - Where required libraries do not restrict us to Python 2, we try to + also be compatible with Python 3.1 and later. + +Error Messages + + - Do not end error messages with a full stop. + + - Do not capitalize ("unable to open %s", not "Unable to open %s") + + - Say what the error is first ("cannot open %s", not "%s: cannot open") + + +Externally Visible Names + + - For configuration variable names, follow the existing convention: + + . The section name indicates the affected subsystem. + + . The subsection name, if any, indicates which of an unbounded set + of things to set the value for. + + . The variable name describes the effect of tweaking this knob. + + The section and variable names that consist of multiple words are + formed by concatenating the words without punctuations (e.g. `-`), + and are broken using bumpyCaps in documentation as a hint to the + reader. + + When choosing the variable namespace, do not use variable name for + specifying possibly unbounded set of things, most notably anything + an end user can freely come up with (e.g. branch names). Instead, + use subsection names or variable values, like the existing variable + branch..description does. + + +Writing Documentation: + + Most (if not all) of the documentation pages are written in the + AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and + processed into HTML and manpages (e.g. git.html and git.1 in the + same directory). + + The documentation liberally mixes US and UK English (en_US/UK) + norms for spelling and grammar, which is somewhat unfortunate. + In an ideal world, it would have been better if it consistently + used only one and not the other, and we would have picked en_US + (if you wish to correct the English of some of the existing + documentation, please see the documentation-related advice in the + Documentation/SubmittingPatches file). + + Every user-visible change should be reflected in the documentation. + The same general rule as for code applies -- imitate the existing + conventions. + + A few commented examples follow to provide reference when writing or + modifying command usage strings and synopsis sections in the manual + pages: + + Placeholders are spelled in lowercase and enclosed in angle brackets: + + --sort= + --abbrev[=] + + If a placeholder has multiple words, they are separated by dashes: + + --template= + + Possibility of multiple occurrences is indicated by three dots: + ... + (One or more of .) + + Optional parts are enclosed in square brackets: + [] + (Zero or one .) + + --exec-path[=] + (Option with an optional argument. Note that the "=" is inside the + brackets.) + + [...] + (Zero or more of . Note that the dots are inside, not + outside the brackets.) + + Multiple alternatives are indicated with vertical bars: + [-q | --quiet] + [--utf8 | --no-utf8] + + Parentheses are used for grouping: + [( | )...] + (Any number of either or . Parens are needed to make + it clear that "..." pertains to both and .) + + [(-p )...] + (Any number of option -p, each with one argument.) + + git remote set-head (-a | -d | ) + (One and only one of "-a", "-d" or "" _must_ (no square + brackets) be provided.) + + And a somewhat more contrived example: + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + Here "=" is outside the brackets, because "--diff-filter=" is a + valid usage. "*" has its own pair of brackets, because it can + (optionally) be specified only when one or more of the letters is + also provided. + + A note on notation: + Use 'git' (all lowercase) when talking about commands i.e. something + the user would type into a shell and use 'Git' (uppercase first letter) + when talking about the version control system and its properties. + + A few commented examples follow to provide reference when writing or + modifying paragraphs or option/command explanations that contain options + or commands: + + Literal examples (e.g. use of command-line options, command names, + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): + `--pretty=oneline` + `git rev-list` + `remote.pushDefault` + `http://git.example.com` + `.git/config` + `GIT_DIR` + `HEAD` + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` + + Word phrases enclosed in `backtick characters` are rendered literally + and will not be further expanded. The use of `backticks` to achieve the + previous rule means that literal examples should not use AsciiDoc + escapes. + Correct: + `--pretty=oneline` + Incorrect: + `\--pretty=oneline` + + If some place in the documentation needs to typeset a command usage + example with inline substitutions, it is fine to use +monospaced and + inline substituted text+ instead of `monospaced literal text`, and with + the former, the part that should not get substituted must be + quoted/escaped. diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..b980407 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,479 @@ +# Guard against environment variables +MAN1_TXT = +MAN5_TXT = +MAN7_TXT = +TECH_DOCS = +ARTICLES = +SP_ARTICLES = +OBSOLETE_HTML = + +-include GIT-EXCLUDED-PROGRAMS + +MAN1_TXT += $(filter-out \ + $(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \ + $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ + $(wildcard git-*.txt)) +MAN1_TXT += git.txt +MAN1_TXT += gitk.txt +MAN1_TXT += gitweb.txt + +# man5 / man7 guides (note: new guides should also be added to command-list.txt) +MAN5_TXT += gitattributes.txt +MAN5_TXT += githooks.txt +MAN5_TXT += gitignore.txt +MAN5_TXT += gitmodules.txt +MAN5_TXT += gitrepository-layout.txt +MAN5_TXT += gitweb.conf.txt + +MAN7_TXT += gitcli.txt +MAN7_TXT += gitcore-tutorial.txt +MAN7_TXT += gitcredentials.txt +MAN7_TXT += gitcvs-migration.txt +MAN7_TXT += gitdiffcore.txt +MAN7_TXT += giteveryday.txt +MAN7_TXT += gitfaq.txt +MAN7_TXT += gitglossary.txt +MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt +MAN7_TXT += gitrevisions.txt +MAN7_TXT += gitsubmodules.txt +MAN7_TXT += gittutorial-2.txt +MAN7_TXT += gittutorial.txt +MAN7_TXT += gitworkflows.txt + +ifdef MAN_FILTER +MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) +else +MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) +MAN_FILTER = $(MAN_TXT) +endif + +MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) +MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) +GIT_MAN_REF = master + +OBSOLETE_HTML += everyday.html +OBSOLETE_HTML += git-remote-helpers.html + +ARTICLES += howto-index +ARTICLES += git-tools +ARTICLES += git-bisect-lk2009 +# with their own formatting rules. +SP_ARTICLES += user-manual +SP_ARTICLES += howto/new-command +SP_ARTICLES += howto/revert-branch-rebase +SP_ARTICLES += howto/using-merge-subtree +SP_ARTICLES += howto/using-signed-tag-in-pull-request +SP_ARTICLES += howto/use-git-daemon +SP_ARTICLES += howto/update-hook-example +SP_ARTICLES += howto/setup-git-server-over-http +SP_ARTICLES += howto/separating-topic-branches +SP_ARTICLES += howto/revert-a-faulty-merge +SP_ARTICLES += howto/recover-corrupted-blob-object +SP_ARTICLES += howto/recover-corrupted-object-harder +SP_ARTICLES += howto/rebuild-from-update-hook +SP_ARTICLES += howto/rebase-from-internal-branch +SP_ARTICLES += howto/keep-canonical-history-correct +SP_ARTICLES += howto/maintain-git +API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) +SP_ARTICLES += $(API_DOCS) + +TECH_DOCS += MyFirstContribution +TECH_DOCS += MyFirstObjectWalk +TECH_DOCS += SubmittingPatches +TECH_DOCS += technical/hash-function-transition +TECH_DOCS += technical/http-protocol +TECH_DOCS += technical/index-format +TECH_DOCS += technical/long-running-process-protocol +TECH_DOCS += technical/multi-pack-index +TECH_DOCS += technical/pack-format +TECH_DOCS += technical/pack-heuristics +TECH_DOCS += technical/pack-protocol +TECH_DOCS += technical/partial-clone +TECH_DOCS += technical/protocol-capabilities +TECH_DOCS += technical/protocol-common +TECH_DOCS += technical/protocol-v2 +TECH_DOCS += technical/racy-git +TECH_DOCS += technical/reftable +TECH_DOCS += technical/send-pack-pipeline +TECH_DOCS += technical/shallow +TECH_DOCS += technical/signature-format +TECH_DOCS += technical/trivial-merge +SP_ARTICLES += $(TECH_DOCS) +SP_ARTICLES += technical/api-index + +ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML) +DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML)) + +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT))) +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT))) +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT))) + +prefix ?= $(HOME) +bindir ?= $(prefix)/bin +htmldir ?= $(prefix)/share/doc/git-doc +infodir ?= $(prefix)/share/info +pdfdir ?= $(prefix)/share/doc/git-doc +mandir ?= $(prefix)/share/man +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 +man7dir = $(mandir)/man7 +# DESTDIR = + +ASCIIDOC = asciidoc +ASCIIDOC_EXTRA = +ASCIIDOC_HTML = xhtml11 +ASCIIDOC_DOCBOOK = docbook +ASCIIDOC_CONF = -f asciidoc.conf +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ + -amanversion=$(GIT_VERSION) \ + -amanmanual='Git Manual' -amansource='Git' +TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) +TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) +MANPAGE_XSL = manpage-normal.xsl +XMLTO = xmlto +XMLTO_EXTRA = +INSTALL ?= install +RM ?= rm -f +MAN_REPO = ../../git-manpages +HTML_REPO = ../../git-htmldocs + +MAKEINFO = makeinfo +INSTALL_INFO = install-info +DOCBOOK2X_TEXI = docbook2x-texi +DBLATEX = dblatex +ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex +DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty +ifndef PERL_PATH + PERL_PATH = /usr/bin/perl +endif + +-include ../config.mak.autogen +-include ../config.mak + +ifndef NO_MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif + +# Newer DocBook stylesheet emits warning cruft in the output when +# this is not set, and if set it shows an absolute link. Older +# stylesheets simply ignore this parameter. +# +# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/ +# or similar. +ifndef MAN_BASE_URL +MAN_BASE_URL = file://$(htmldir)/ +endif +XMLTO_EXTRA += -m manpage-base-url.xsl + +# If your target system uses GNU groff, it may try to render +# apostrophes as a "pretty" apostrophe using unicode. This breaks +# cut&paste, so you should set GNU_ROFF to force them to be ASCII +# apostrophes. Unfortunately does not work with non-GNU roff. +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_CONF = +ASCIIDOC_HTML = xhtml5 +ASCIIDOC_DOCBOOK = docbook5 +ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +DBLATEX_COMMON = +XMLTO_EXTRA += --skip-validation +XMLTO_EXTRA += -x manpage.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +ifdef DEFAULT_PAGER +DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) +ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' +endif + +ifdef DEFAULT_EDITOR +DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) +ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' +endif + +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; + QUIET_XMLTO = @echo ' ' XMLTO $@; + QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; + QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; + QUIET_DBLATEX = @echo ' ' DBLATEX $@; + QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; + QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: html man + +html: $(DOC_HTML) + +man: man1 man5 man7 +man1: $(DOC_MAN1) +man5: $(DOC_MAN5) +man7: $(DOC_MAN7) + +info: git.info gitman.info + +pdf: user-manual.pdf + +install: install-man + +install-man: man + $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir) + $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) + +install-info: info + $(INSTALL) -d -m 755 $(DESTDIR)$(infodir) + $(INSTALL) -m 644 git.info gitman.info $(DESTDIR)$(infodir) + if test -r $(DESTDIR)$(infodir)/dir; then \ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) gitman.info ;\ + else \ + echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ + fi + +install-pdf: pdf + $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir) + $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir) + +install-html: html + '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) + +../GIT-VERSION-FILE: FORCE + $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE + +ifneq ($(MAKECMDGOALS),clean) +-include ../GIT-VERSION-FILE +endif + +# +# Determine "include::" file references in asciidoc files. +# +docdep_prereqs = \ + mergetools-list.made $(mergetools_txt) \ + cmd-list.made $(cmds_txt) + +doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl + $(QUIET_GEN)$(RM) $@+ $@ && \ + $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ + mv $@+ $@ + +ifneq ($(MAKECMDGOALS),clean) +-include doc.dep +endif + +cmds_txt = cmds-ancillaryinterrogators.txt \ + cmds-ancillarymanipulators.txt \ + cmds-mainporcelain.txt \ + cmds-plumbinginterrogators.txt \ + cmds-plumbingmanipulators.txt \ + cmds-synchingrepositories.txt \ + cmds-synchelpers.txt \ + cmds-guide.txt \ + cmds-purehelpers.txt \ + cmds-foreignscminterface.txt + +$(cmds_txt): cmd-list.made + +cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) + $(QUIET_GEN)$(RM) $@ && \ + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ + date >$@ + +mergetools_txt = mergetools-diff.txt mergetools-merge.txt + +$(mergetools_txt): mergetools-list.made + +mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) + $(QUIET_GEN)$(RM) $@ && \ + $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ + . ../git-mergetool--lib.sh && \ + show_tool_names can_diff "* " || :' >mergetools-diff.txt && \ + $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ + . ../git-mergetool--lib.sh && \ + show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ + date >$@ + +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) + +GIT-ASCIIDOCFLAGS: FORCE + @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ + if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \ + echo >&2 " * new asciidoc flags"; \ + echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \ + fi + +clean: + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 + $(RM) *.texi *.texi+ *.texi++ git.info gitman.info + $(RM) *.pdf + $(RM) howto-index.txt howto/*.html doc.dep + $(RM) technical/*.html technical/api-index.txt + $(RM) SubmittingPatches.txt + $(RM) $(cmds_txt) $(mergetools_txt) *.made + $(RM) manpage-base-url.xsl + $(RM) GIT-ASCIIDOCFLAGS + +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_HTML) -d manpage -o $@+ $< && \ + mv $@+ $@ + +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_HTML) -o $@+ $< && \ + mv $@+ $@ + +manpage-base-url.xsl: manpage-base-url.xsl.in + $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ + +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_XML) -d manpage -o $@+ $< && \ + mv $@+ $@ + +user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_XML) -d book -o $@+ $< && \ + mv $@+ $@ + +technical/api-index.txt: technical/api-index-skel.txt \ + technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) + $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh + +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ + asciidoc.conf GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt + +SubmittingPatches.txt: SubmittingPatches + $(QUIET_GEN) cp $< $@ + +XSLT = docbook.xsl +XSLTOPTS = +XSLTOPTS += --xinclude +XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css +XSLTOPTS += --param generate.consistent.ids 1 + +user-manual.html: user-manual.xml $(XSLT) + $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ + xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ + mv $@+ $@ + +git.info: user-manual.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi + +user-manual.texi: user-manual.xml + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \ + $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ + rm $@++ && \ + mv $@+ $@ + +user-manual.pdf: user-manual.xml + $(QUIET_DBLATEX)$(RM) $@+ $@ && \ + $(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \ + mv $@+ $@ + +gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \ + $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \ + rm $(xml)+ &&) true) > $@++ && \ + $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ + rm $@++ && \ + mv $@+ $@ + +gitman.info: gitman.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi + +$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ + mv $@+ $@ + +howto-index.txt: howto-index.sh $(wildcard howto/*.txt) + $(QUIET_GEN)$(RM) $@+ $@ && \ + '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \ + mv $@+ $@ + +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt + +WEBDOC_DEST = /pub/software/scm/git/docs + +howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ +$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + sed -e '1,/^$$/d' $< | \ + $(TXT_TO_HTML) - >$@+ && \ + mv $@+ $@ + +install-webdoc : html + '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) + +# You must have a clone of 'git-htmldocs' and 'git-manpages' repositories +# next to the 'git' repository itself for the following to work. + +quick-install: quick-install-man + +require-manrepo:: + @if test ! -d $(MAN_REPO); \ + then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi + +quick-install-man: require-manrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF) + +require-htmlrepo:: + @if test ! -d $(HTML_REPO); \ + then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi + +quick-install-html: require-htmlrepo + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF) + +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done + +lint-docs:: + $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl + +ifeq ($(wildcard po/Makefile),po/Makefile) +doc-l10n install-l10n:: + $(MAKE) -C po $@ +endif + +.PHONY: FORCE diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt new file mode 100644 index 0000000..7c9a037 --- /dev/null +++ b/Documentation/MyFirstContribution.txt @@ -0,0 +1,1232 @@ +My First Contribution to the Git Project +======================================== +:sectanchors: + +[[summary]] +== Summary + +This is a tutorial demonstrating the end-to-end workflow of creating a change to +the Git tree, sending it for review, and making changes based on comments. + +[[prerequisites]] +=== Prerequisites + +This tutorial assumes you're already fairly familiar with using Git to manage +source code. The Git workflow steps will largely remain unexplained. + +[[related-reading]] +=== Related Reading + +This tutorial aims to summarize the following documents, but the reader may find +useful additional context: + +- `Documentation/SubmittingPatches` +- `Documentation/howto/new-command.txt` + +[[getting-help]] +=== Getting Help + +If you get stuck, you can seek help in the following places. + +==== git@vger.kernel.org + +This is the main Git project mailing list where code reviews, version +announcements, design discussions, and more take place. Those interested in +contributing are welcome to post questions here. The Git list requires +plain-text-only emails and prefers inline and bottom-posting when replying to +mail; you will be CC'd in all replies to you. Optionally, you can subscribe to +the list by sending an email to majordomo@vger.kernel.org with "subscribe git" +in the body. The https://lore.kernel.org/git[archive] of this mailing list is +available to view in a browser. + +==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] + +This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required. + +==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode + +This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It's better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation. + +[[getting-started]] +== Getting Started + +[[cloning]] +=== Clone the Git Repository + +Git is mirrored in a number of locations. Clone the repository from one of them; +https://git-scm.com/downloads suggests one of the best places to clone from is +the mirror on GitHub. + +---- +$ git clone https://github.com/git/git git +$ cd git +---- + +[[dependencies]] +=== Installing Dependencies + +To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what's needed, you can take a look at +`INSTALL`, paying close attention to the section about Git's dependencies on +external programs and libraries. That document mentions a way to "test-drive" +our freshly built Git without installing; that's the method we'll be using in +this tutorial. + +Make sure that your environment has everything you need by building your brand +new clone of Git from the above step: + +---- +$ make +---- + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + +[[identify-problem]] +=== Identify Problem to Solve + +//// +Use + to indicate fixed-width here; couldn't get ` to work nicely with the +quotes around "Pony Saying 'Um, Hello'". +//// +In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying +`Um, Hello''' - a feature which has gone unimplemented despite a high frequency +of invocation during users' typical daily workflow. + +(We've seen some other effort in this space with the implementation of popular +commands such as `sl`.) + +[[setup-workspace]] +=== Set Up Your Workspace + +Let's start by making a development branch to work on our changes. Per +`Documentation/SubmittingPatches`, since a brand new command is a new feature, +it's fine to base your work on `master`. However, in the future for bugfixes, +etc., you should check that document and base it on the appropriate branch. + +For the purposes of this document, we will base all our work on the `master` +branch of the upstream project. Create the `psuh` branch you will use for +development like so: + +---- +$ git checkout -b psuh origin/master +---- + +We'll make a number of commits here in order to demonstrate how to send a topic +with multiple patches up for review simultaneously. + +[[code-it-up]] +== Code It Up! + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/psuh. + +[[add-new-command]] +=== Adding a New Command + +Lots of the subcommands are written as builtins, which means they are +implemented in C and compiled into the main `git` executable. Implementing the +very simple `psuh` command as a built-in will demonstrate the structure of the +codebase, the internal API, and the process of working together as a contributor +with the reviewers and maintainer to integrate this change into the system. + +Built-in subcommands are typically implemented in a function named "cmd_" +followed by the name of the subcommand, in a source file named after the +subcommand and contained within `builtin/`. So it makes sense to implement your +command in `builtin/psuh.c`. Create that file, and within it, write the entry +point for your command in a function matching the style and signature: + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +---- + +We'll also need to add the declaration of psuh; open up `builtin.h`, find the +declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, +in order to keep the declarations alphabetically sorted: + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix); +---- + +Be sure to `#include "builtin.h"` in your `psuh.c`. + +Go ahead and add some throwaway printf to that function. This is a decent +starting point as we can now add build rules and register the command. + +NOTE: Your throwaway text, as well as much of the text you will be adding over +the course of this tutorial, is user-facing. That means it needs to be +localizable. Take a look at `po/README` under "Marking strings for translation". +Throughout the tutorial, we will mark strings for translation as necessary; you +should also do so when writing your user-facing commands in the future. + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +{ + printf(_("Pony saying hello goes here.\n")); + return 0; +} +---- + +Let's try to build it. Open `Makefile`, find where `builtin/pull.o` is added +to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in +alphabetical order. Once you've done so, move to the top-level directory and +build simply with `make`. Also add the `DEVELOPER=1` variable to turn on +some additional warnings: + +---- +$ echo DEVELOPER=1 >config.mak +$ make +---- + +NOTE: When you are developing the Git project, it's preferred that you use the +`DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn +it off, but it's a good idea to mention the problem to the mailing list. + +Great, now your new command builds happily on its own. But nobody invokes it. +Let's change that. + +The list of commands lives in `git.c`. We can register a new command by adding +a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string +with the command name, a function pointer to the command implementation, and a +setup option flag. For now, let's keep mimicking `push`. Find the line where +`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new +line in alphabetical order (immediately before `cmd_pull`). + +The options are documented in `builtin.h` under "Adding a new built-in." Since +we hope to print some data about the user's current workspace context later, +we need a Git directory, so choose `RUN_SETUP` as your only option. + +Go ahead and build again. You should see a clean build, so let's kick the tires +and see if it works. There's a binary you can use to test with in the +`bin-wrappers` directory. + +---- +$ ./bin-wrappers/git psuh +---- + +Check it out! You've got a command! Nice work! Let's commit this. + +`git status` reveals modified `Makefile`, `builtin.h`, and `git.c` as well as +untracked `builtin/psuh.c` and `git-psuh`. First, let's take care of the binary, +which should be ignored. Open `.gitignore` in your editor, find `/git-pull`, and +add an entry for your new command in alphabetical order: + +---- +... +/git-prune-packed +/git-psuh +/git-pull +/git-push +/git-quiltimport +/git-range-diff +... +---- + +Checking `git status` again should show that `git-psuh` has been removed from +the untracked list and `.gitignore` has been added to the modified list. Now we +can stage and commit: + +---- +$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore +$ git commit -s +---- + +You will be presented with your editor in order to write a commit message. Start +the commit with a 50-column or less subject line, including the name of the +component you're working on, followed by a blank line (always required) and then +the body of your commit message, which should provide the bulk of the context. +Remember to be explicit and provide the "Why" of your change, especially if it +couldn't easily be understood from your diff. When editing your commit message, +don't remove the `Signed-off-by` trailer which was added by `-s` above. + +---- +psuh: add a built-in by popular demand + +Internal metrics indicate this is a command many users expect to be +present. So here's an implementation to help drive customer +satisfaction and engagement: a pony which doubtfully greets the user, +or, a Pony Saying "Um, Hello" (PSUH). + +This commit message is intentionally formatted to 72 columns per line, +starts with a single line as "commit message subject" that is written as +if to command the codebase to do something (add this, teach a command +that). The body of the message is designed to add information about the +commit that is not readily deduced from reading the associated diff, +such as answering the question "why?". + +Signed-off-by: A U Thor +---- + +Go ahead and inspect your new commit with `git show`. "psuh:" indicates you +have modified mainly the `psuh` command. The subject line gives readers an idea +of what you've changed. The sign-off line (`-s`) indicates that you agree to +the Developer's Certificate of Origin 1.1 (see the +`Documentation/SubmittingPatches` +++[[dco]]+++ header). + +For the remainder of the tutorial, the subject line only will be listed for the +sake of brevity. However, fully-fleshed example commit messages are available +on the reference implementation linked at the top of this document. + +[[implementation]] +=== Implementation + +It's probably useful to do at least something besides printing out a string. +Let's start by having a look at everything we get. + +Modify your `cmd_psuh` implementation to dump the args you're passed, keeping +existing `printf()` calls in place: + +---- + int i; + + ... + + printf(Q_("Your args (there is %d):\n", + "Your args (there are %d):\n", + argc), + argc); + for (i = 0; i < argc; i++) + printf("%d: %s\n", i, argv[i]); + + printf(_("Your current working directory:\n%s%s\n"), + prefix ? "/" : "", prefix ? prefix : ""); + +---- + +Build and try it. As you may expect, there's pretty much just whatever we give +on the command line, including the name of our command. (If `prefix` is empty +for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so +helpful. So what other context can we get? + +Add a line to `#include "config.h"`. Then, add the following bits to the +function body: + +---- + const char *cfg_name; + +... + + git_config(git_default_config, NULL); + if (git_config_get_string_tmp("user.name", &cfg_name) > 0) + printf(_("No name is found in config\n")); + else + printf(_("Your name: %s\n"), cfg_name); +---- + +`git_config()` will grab the configuration from config files known to Git and +apply standard precedence rules. `git_config_get_string_tmp()` will look up +a specific key ("user.name") and give you the value. There are a number of +single-key lookup functions like this one; you can see them all (and more info +about how to use `git_config()`) in `Documentation/technical/api-config.txt`. + +You should see that the name printed matches the one you see when you run: + +---- +$ git config --get user.name +---- + +Great! Now we know how to check for values in the Git config. Let's commit this +too, so we don't lose our progress. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: show parameters & config opts" +---- + +NOTE: Again, the above is for sake of brevity in this tutorial. In a real change +you should not use `-m` but instead use the editor to write a meaningful +message. + +Still, it'd be nice to know what the user's working context is like. Let's see +if we can print the name of the user's current branch. We can mimic the +`git status` implementation; the printer is located in `wt-status.c` and we can +see that the branch is held in a `struct wt_status`. + +`wt_status_print()` gets invoked by `cmd_status()` in `builtin/commit.c`. +Looking at that implementation we see the status config being populated like so: + +---- +status_init_config(&s, git_status_config); +---- + +But as we drill down, we can find that `status_init_config()` wraps a call +to `git_config()`. Let's modify the code we wrote in the previous commit. + +Be sure to include the header to allow you to use `struct wt_status`: +---- +#include "wt-status.h" +---- + +Then modify your `cmd_psuh` implementation to declare your `struct wt_status`, +prepare it, and print its contents: + +---- + struct wt_status status; + +... + + wt_status_prepare(the_repository, &status); + git_config(git_default_config, &status); + +... + + printf(_("Your current branch: %s\n"), status.branch); +---- + +Run it again. Check it out - here's the (verbose) name of your current branch! + +Let's commit this as well. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: print the current branch" +---- + +Now let's see if we can get some info about a specific commit. + +Luckily, there are some helpers for us here. `commit.h` has a function called +`lookup_commit_reference_by_name` to which we can simply provide a hardcoded +string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't +require a full format object to be passed. + +Add the following includes: + +---- +#include "commit.h" +#include "pretty.h" +---- + +Then, add the following lines within your implementation of `cmd_psuh()` near +the declarations and the logic, respectively. + +---- + struct commit *c = NULL; + struct strbuf commitline = STRBUF_INIT; + +... + + c = lookup_commit_reference_by_name("origin/master"); + + if (c != NULL) { + pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline); + printf(_("Current commit: %s\n"), commitline.buf); + } +---- + +The `struct strbuf` provides some safety belts to your basic `char*`, one of +which is a length member to prevent buffer overruns. It needs to be initialized +nicely with `STRBUF_INIT`. Keep it in mind when you need to pass around `char*`. + +`lookup_commit_reference_by_name` resolves the name you pass it, so you can play +with the value there and see what kind of things you can come up with. + +`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single +format enum shorthand, rather than an entire format struct. It then +pretty-prints the commit according to that shorthand. These are similar to the +formats available with `--pretty=FOO` in many Git commands. + +Build it and run, and if you're using the same name in the example, you should +see the subject line of the most recent commit in `origin/master` that you know +about. Neat! Let's commit that as well. + +---- +$ git add builtin/psuh.c +$ git commit -sm "psuh: display the top of origin/master" +---- + +[[add-documentation]] +=== Adding Documentation + +Awesome! You've got a fantastic new command that you're ready to share with the +community. But hang on just a minute - this isn't very user-friendly. Run the +following: + +---- +$ ./bin-wrappers/git help psuh +---- + +Your new command is undocumented! Let's fix that. + +Take a look at `Documentation/git-*.txt`. These are the manpages for the +subcommands that Git knows about. You can open these up and take a look to get +acquainted with the format, but then go ahead and make a new file +`Documentation/git-psuh.txt`. Like with most of the documentation in the Git +project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing +Documentation" section). Use the following template to fill out your own +manpage: + +// Surprisingly difficult to embed AsciiDoc source within AsciiDoc. +[listing] +.... +git-psuh(1) +=========== + +NAME +---- +git-psuh - Delight users' typo with a shy horse + + +SYNOPSIS +-------- +[verse] +'git-psuh [...]' + +DESCRIPTION +----------- +... + +OPTIONS[[OPTIONS]] +------------------ +... + +OUTPUT +------ +... + +GIT +--- +Part of the linkgit:git[1] suite +.... + +The most important pieces of this to note are the file header, underlined by =, +the NAME section, and the SYNOPSIS, which would normally contain the grammar if +your command took arguments. Try to use well-established manpage headers so your +documentation is consistent with other Git and UNIX manpages; this makes life +easier for your user, who can skip to the section they know contains the +information they need. + +NOTE: Before trying to build the docs, make sure you have the package `asciidoc` +installed. + +Now that you've written your manpage, you'll need to build it explicitly. We +convert your AsciiDoc to troff which is man-readable like so: + +---- +$ make all doc +$ man Documentation/git-psuh.1 +---- + +or + +---- +$ make -C Documentation/ git-psuh.1 +$ man Documentation/git-psuh.1 +---- + +While this isn't as satisfying as running through `git help`, you can at least +check that your help page looks right. + +You can also check that the documentation coverage is good (that is, the project +sees that your command has been implemented as well as documented) by running +`make check-docs` from the top-level. + +Go ahead and commit your new documentation change. + +[[add-usage]] +=== Adding Usage Text + +Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end. +That's because `-h` is a special case which your command should handle by +printing usage. + +Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy +tool for pulling out options you need to be able to handle, and it takes a +usage string. + +In order to use it, we'll need to prepare a NULL-terminated array of usage +strings and a `builtin_psuh_options` array. + +Add a line to `#include "parse-options.h"`. + +At global scope, add your array of usage strings: + +---- +static const char * const psuh_usage[] = { + N_("git psuh [...]"), + NULL, +}; +---- + +Then, within your `cmd_psuh()` implementation, we can declare and populate our +`option` struct. Ours is pretty boring but you can add more to it if you want to +explore `parse_options()` in more detail: + +---- + struct option options[] = { + OPT_END() + }; +---- + +Finally, before you print your args and prefix, add the call to +`parse-options()`: + +---- + argc = parse_options(argc, argv, prefix, options, psuh_usage, 0); +---- + +This call will modify your `argv` parameter. It will strip the options you +specified in `options` from `argv` and the locations pointed to from `options` +entries will be updated. Be sure to replace your `argc` with the result from +`parse_options()`, or you will be confused if you try to parse `argv` later. + +It's worth noting the special argument `--`. As you may be aware, many Unix +commands use `--` to indicate "end of named parameters" - all parameters after +the `--` are interpreted merely as positional arguments. (This can be handy if +you want to pass as a parameter something which would usually be interpreted as +a flag.) `parse_options()` will terminate parsing when it reaches `--` and give +you the rest of the options afterwards, untouched. + +Now that you have a usage hint, you can teach Git how to show it in the general +command list shown by `git help git` or `git help -a`, which is generated from +`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' +line above it in alphabetical order. Now, we can add some attributes about the +command which impacts where it shows up in the aforementioned help commands. The +top of `command-list.txt` shares some information about what each attribute +means; in those help pages, the commands are sorted according to these +attributes. `git psuh` is user-facing, or porcelain - so we will mark it as +"mainporcelain". For "mainporcelain" commands, the comments at the top of +`command-list.txt` indicate we can also optionally add an attribute from another +list; since `git psuh` shows some information about the user's workspace but +doesn't modify anything, let's mark it as "info". Make sure to keep your +attributes in the same style as the rest of `command-list.txt` using spaces to +align and delineate them: + +---- +git-prune-packed plumbingmanipulators +git-psuh mainporcelain info +git-pull mainporcelain remote +git-push mainporcelain remote +---- + +Build again. Now, when you run with `-h`, you should see your usage printed and +your command terminated before anything else interesting happens. Great! + +Go ahead and commit this one, too. + +[[testing]] +== Testing + +It's important to test your code - even for a little toy command like this one. +Moreover, your patch won't be accepted into the Git tree without tests. Your +tests should: + +* Illustrate the current behavior of the feature +* Prove the current behavior matches the expected behavior +* Ensure the externally-visible behavior isn't broken in later changes + +So let's write some tests. + +Related reading: `t/README` + +[[overview-test-structure]] +=== Overview of Testing Structure + +The tests in Git live in `t/` and are named with a 4-digit decimal number using +the schema shown in the Naming Tests section of `t/README`. + +[[write-new-test]] +=== Writing Your Test + +Since this a toy command, let's go ahead and name the test with t9999. However, +as many of the family/subcmd combinations are full, best practice seems to be +to find a command close enough to the one you've added and share its naming +space. + +Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see +"Writing Tests" and "Source 'test-lib.sh'" in `t/README`): + +---- +#!/bin/sh + +test_description='git-psuh test + +This test runs git-psuh and makes sure it does not crash.' + +. ./test-lib.sh +---- + +Tests are framed inside of a `test_expect_success` in order to output TAP +formatted results. Let's make sure that `git psuh` doesn't exit poorly and does +mention the right animal somewhere: + +---- +test_expect_success 'runs correctly with no args and good output' ' + git psuh >actual && + test_i18ngrep Pony actual +' +---- + +Indicate that you've run everything you wanted by adding the following at the +bottom of your script: + +---- +test_done +---- + +Make sure you mark your test script executable: + +---- +$ chmod +x t/t9999-psuh-tutorial.sh +---- + +You can get an idea of whether you created your new test script successfully +by running `make -C t test-lint`, which will check for things like test number +uniqueness, executable bit, and so on. + +[[local-test]] +=== Running Locally + +Let's try and run locally: + +---- +$ make +$ cd t/ && prove t9999-psuh-tutorial.sh +---- + +You can run the full test suite and ensure `git-psuh` didn't break anything: + +---- +$ cd t/ +$ prove -j$(nproc) --shuffle t[0-9]*.sh +---- + +NOTE: You can also do this with `make test` or use any testing harness which can +speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the +tests are run in, which makes them resilient against unwanted inter-test +dependencies. `prove` also makes the output nicer. + +Go ahead and commit this change, as well. + +[[ready-to-share]] +== Getting Ready to Share + +You may have noticed already that the Git project performs its code reviews via +emailed patches, which are then applied by the maintainer when they are ready +and approved by the community. The Git project does not accept patches from +pull requests, and the patches emailed for review need to be formatted a +specific way. At this point the tutorial diverges, in order to demonstrate two +different methods of formatting your patchset and getting it reviewed. + +The first method to be covered is GitGitGadget, which is useful for those +already familiar with GitHub's common pull request workflow. This method +requires a GitHub account. + +The second method to be covered is `git send-email`, which can give slightly +more fine-grained control over the emails to be sent. This method requires some +setup which can change depending on your system and will not be covered in this +tutorial. + +Regardless of which method you choose, your engagement with reviewers will be +the same; the review process will be covered after the sections on GitGitGadget +and `git send-email`. + +[[howto-ggg]] +== Sending Patches via GitGitGadget + +One option for sending patches is to follow a typical pull request workflow and +send your patches out via GitGitGadget. GitGitGadget is a tool created by +Johannes Schindelin to make life as a Git contributor easier for those used to +the GitHub PR workflow. It allows contributors to open pull requests against its +mirror of the Git project, and does some magic to turn the PR into a set of +emails and send them out for you. It also runs the Git continuous integration +suite for you. It's documented at http://gitgitgadget.github.io. + +[[create-fork]] +=== Forking `git/git` on GitHub + +Before you can send your patch off to be reviewed using GitGitGadget, you will +need to fork the Git project and upload your changes. First thing - make sure +you have a GitHub account. + +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork +button. Place your fork wherever you deem appropriate and create it. + +[[upload-to-fork]] +=== Uploading to Your Own Fork + +To upload your branch to your own fork, you'll need to add the new fork as a +remote. You can use `git remote -v` to show the remotes you have added already. +From your new fork's page on GitHub, you can press "Clone or download" to get +the URL; then you need to run the following to add, replacing your own URL and +remote name for the examples provided: + +---- +$ git remote add remotename git@github.com:remotename/git.git +---- + +or to use the HTTPS URL: + +---- +$ git remote add remotename https://github.com/remotename/git/.git +---- + +Run `git remote -v` again and you should see the new remote showing up. +`git fetch remotename` (with the real name of your remote replaced) in order to +get ready to push. + +Next, double-check that you've been doing all your development in a new branch +by running `git branch`. If you didn't, now is a good time to move your new +commits to their own branch. + +As mentioned briefly at the beginning of this document, we are basing our work +on `master`, so go ahead and update as shown below, or using your preferred +workflow. + +---- +$ git checkout master +$ git pull -r +$ git rebase master psuh +---- + +Finally, you're ready to push your new topic branch! (Due to our branch and +command name choices, be careful when you type the command below.) + +---- +$ git push remotename psuh +---- + +Now you should be able to go and check out your newly created branch on GitHub. + +[[send-pr-ggg]] +=== Sending a PR to GitGitGadget + +In order to have your code tested and formatted for review, you need to start by +opening a Pull Request against `gitgitgadget/git`. Head to +https://github.com/gitgitgadget/git and open a PR either with the "New pull +request" button or the convenient "Compare & pull request" button that may +appear with the name of your newly pushed branch. + +Review the PR's title and description, as it's used by GitGitGadget as the cover +letter for your change. When you're happy, submit your pull request. + +[[run-ci-ggg]] +=== Running CI and Getting Ready to Send + +If it's your first time using GitGitGadget (which is likely, as you're using +this tutorial) then someone will need to give you permission to use the tool. +As mentioned in the GitGitGadget documentation, you just need someone who +already uses it to comment on your PR with `/allow `. GitGitGadget +will automatically run your PRs through the CI even without the permission given +but you will not be able to `/submit` your changes until someone allows you to +use the tool. + +NOTE: You can typically find someone who can `/allow` you on GitGitGadget by +either examining recent pull requests where someone has been granted `/allow` +(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: +is:pr is:open "/allow"]), in which case both the author and the person who +granted the `/allow` can now `/allow` you, or by inquiring on the +https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode +linking your pull request and asking for someone to `/allow` you. + +If the CI fails, you can update your changes with `git rebase -i` and push your +branch again: + +---- +$ git push -f remotename psuh +---- + +In fact, you should continue to make changes this way up until the point when +your patch is accepted into `next`. + +//// +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83 +It'd be nice to be able to verify that the patch looks good before sending it +to everyone on Git mailing list. +[[check-work-ggg]] +=== Check Your Work +//// + +[[send-mail-ggg]] +=== Sending Your Patches + +Now that your CI is passing and someone has granted you permission to use +GitGitGadget with the `/allow` command, sending out for review is as simple as +commenting on your PR with `/submit`. + +[[responding-ggg]] +=== Updating With Comments + +Skip ahead to <> for information on how to +reply to review comments you will receive on the mailing list. + +Once you have your branch again in the shape you want following all review +comments, you can submit again: + +---- +$ git push -f remotename psuh +---- + +Next, go look at your pull request against GitGitGadget; you should see the CI +has been kicked off again. Now while the CI is running is a good time for you +to modify your description at the top of the pull request thread; it will be +used again as the cover letter. You should use this space to describe what +has changed since your previous version, so that your reviewers have some idea +of what they're looking at. When the CI is done running, you can comment once +more with `/submit` - GitGitGadget will automatically add a v2 mark to your +changes. + +[[howto-git-send-email]] +== Sending Patches with `git send-email` + +If you don't want to use GitGitGadget, you can also use Git itself to mail your +patches. Some benefits of using Git this way include finer grained control of +subject line (for example, being able to use the tag [RFC PATCH] in the subject) +and being able to send a ``dry run'' mail to yourself to ensure it all looks +good before going out to the list. + +[[setup-git-send-email]] +=== Prerequisite: Setting Up `git send-email` + +Configuration for `send-email` can vary based on your operating system and email +provider, and so will not be covered in this tutorial, beyond stating that in +many distributions of Linux, `git-send-email` is not packaged alongside the +typical `git` install. You may need to install this additional package; there +are a number of resources online to help you do so. You will also need to +determine the right way to configure it to use your SMTP server; again, as this +configuration can change significantly based on your system and email setup, it +is out of scope for the context of this tutorial. + +[[format-patch]] +=== Preparing Initial Patchset + +Sending emails with Git is a two-part process; before you can prepare the emails +themselves, you'll need to prepare the patches. Luckily, this is pretty simple: + +---- +$ git format-patch --cover-letter -o psuh/ master..psuh +---- + +The `--cover-letter` parameter tells `format-patch` to create a cover letter +template for you. You will need to fill in the template before you're ready +to send - but for now, the template will be next to your other patches. + +The `-o psuh/` parameter tells `format-patch` to place the patch files into a +directory. This is useful because `git send-email` can take a directory and +send out all the patches from there. + +`master..psuh` tells `format-patch` to generate patches for the difference +between `master` and `psuh`. It will make one patch file per commit. After you +run, you can go have a look at each of the patches with your favorite text +editor and make sure everything looks alright; however, it's not recommended to +make code fixups via the patch file. It's a better idea to make the change the +normal way using `git rebase -i` or by adding a new commit than by modifying a +patch. + +NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject +with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for +comments'' and indicates that while your code isn't quite ready for submission, +you'd like to begin the code review process. This can also be used when your +patch is a proposal, but you aren't sure whether the community wants to solve +the problem with that approach or not - to conduct a sort of design review. You +may also see on the list patches marked ``WIP'' - this means they are incomplete +but want reviewers to look at what they have so far. You can add this flag with +`--subject-prefix=WIP`. + +Check and make sure that your patches and cover letter template exist in the +directory you specified - you're nearly ready to send out your review! + +[[cover-letter]] +=== Preparing Email + +In addition to an email per patch, the Git community also expects your patches +to come with a cover letter, typically with a subject line [PATCH 0/x] (where +x is the number of patches you're sending). Since you invoked `format-patch` +with `--cover-letter`, you've already got a template ready. Open it up in your +favorite editor. + +You should see a number of headers present already. Check that your `From:` +header is correct. Then modify your `Subject:` to something which succinctly +covers the purpose of your entire topic branch, for example: + +---- +Subject: [PATCH 0/7] adding the 'psuh' command +---- + +Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git +community that this email is the beginning of a review, and many reviewers +filter their email for this type of flag. + +You'll need to add some extra parameters when you invoke `git send-email` to add +the cover letter. + +Next you'll have to fill out the body of your cover letter. This is an important +component of change submission as it explains to the community from a high level +what you're trying to do, and why, in a way that's more apparent than just +looking at your diff. Be sure to explain anything your diff doesn't make clear +on its own. + +Here's an example body for `psuh`: + +---- +Our internal metrics indicate widespread interest in the command +git-psuh - that is, many users are trying to use it, but finding it is +unavailable, using some unknown workaround instead. + +The following handful of patches add the psuh command and implement some +handy features on top of it. + +This patchset is part of the MyFirstContribution tutorial and should not +be merged. +---- + +The template created by `git format-patch --cover-letter` includes a diffstat. +This gives reviewers a summary of what they're in for when reviewing your topic. +The one generated for `psuh` from the sample implementation looks like this: + +---- + Documentation/git-psuh.txt | 40 +++++++++++++++++++++ + Makefile | 1 + + builtin.h | 1 + + builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++ + git.c | 1 + + t/t9999-psuh-tutorial.sh | 12 +++++++ + 6 files changed, 128 insertions(+) + create mode 100644 Documentation/git-psuh.txt + create mode 100644 builtin/psuh.c + create mode 100755 t/t9999-psuh-tutorial.sh +---- + +Finally, the letter will include the version of Git used to generate the +patches. You can leave that string alone. + +[[sending-git-send-email]] +=== Sending Email + +At this point you should have a directory `psuh/` which is filled with your +patches and a cover letter. Time to mail it out! You can send it like this: + +---- +$ git send-email --to=target@example.com psuh/*.patch +---- + +NOTE: Check `git help send-email` for some other options which you may find +valuable, such as changing the Reply-to address or adding more CC and BCC lines. + +NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but +please don't send your patchset from the tutorial to the real mailing list! For +now, you can send it to yourself, to make sure you understand how it will look. + +After you run the command above, you will be presented with an interactive +prompt for each patch that's about to go out. This gives you one last chance to +edit or quit sending something (but again, don't edit code this way). Once you +press `y` or `a` at these prompts your emails will be sent! Congratulations! + +Awesome, now the community will drop everything and review your changes. (Just +kidding - be patient!) + +[[v2-git-send-email]] +=== Sending v2 + +Skip ahead to <> for information on how to +handle comments from reviewers. Continue this section when your topic branch is +shaped the way you want it to look for your patchset v2. + +When you're ready with the next iteration of your patch, the process is fairly +similar. + +First, generate your v2 patches again: + +---- +$ git format-patch -v2 --cover-letter -o psuh/ master..psuh +---- + +This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`, +to the `psuh/` directory. You may notice that they are sitting alongside the v1 +patches; that's fine, but be careful when you are ready to send them. + +Edit your cover letter again. Now is a good time to mention what's different +between your last version and now, if it's something significant. You do not +need the exact same body in your second cover letter; focus on explaining to +reviewers the changes you've made that may not be as visible. + +You will also need to go and find the Message-Id of your previous cover letter. +You can either note it when you send the first series, from the output of `git +send-email`, or you can look it up on the +https://lore.kernel.org/git[mailing list]. Find your cover letter in the +archives, click on it, then click "permalink" or "raw" to reveal the Message-Id +header. It should match: + +---- +Message-Id: +---- + +Your Message-Id is ``. This example will be used +below as well; make sure to replace it with the correct Message-Id for your +**previous cover letter** - that is, if you're sending v2, use the Message-Id +from v1; if you're sending v3, use the Message-Id from v2. + +While you're looking at the email, you should also note who is CC'd, as it's +common practice in the mailing list to keep all CCs on a thread. You can add +these CC lines directly to your cover letter with a line like so in the header +(before the Subject line): + +---- +CC: author@example.com, Othe R +---- + +Now send the emails again, paying close attention to which messages you pass in +to the command: + +---- +$ git send-email --to=target@example.com + --in-reply-to="" + psuh/v2* +---- + +[[single-patch]] +=== Bonus Chapter: One-Patch Changes + +In some cases, your very small change may consist of only one patch. When that +happens, you only need to send one email. Your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, but if you need to supply even more context, you can do so below +the `---` in your patch. Take the example below, which was generated with `git +format-patch` on a single commit, and then edited to add the content between +the `---` and the diffstat. + +---- +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001 +From: A U Thor +Date: Thu, 18 Apr 2019 15:11:02 -0700 +Subject: [PATCH] README: change the grammar + +I think it looks better this way. This part of the commit message will +end up in the commit-log. + +Signed-off-by: A U Thor +--- +Let's have a wild discussion about grammar on the mailing list. This +part of my email will never end up in the commit log. Here is where I +can add additional context to the mailing list about my intent, outside +of the context of the commit log. This section was added after `git +format-patch` was run, by editing the patch file in a text editor. + + README.md | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) + +diff --git a/README.md b/README.md +index 88f126184c..38da593a60 100644 +--- a/README.md ++++ b/README.md +@@ -3,7 +3,7 @@ + Git - fast, scalable, distributed revision control system + ========================================================= + +-Git is a fast, scalable, distributed revision control system with an ++Git is a fast, scalable, and distributed revision control system with an + unusually rich command set that provides both high-level operations + and full access to internals. + +-- +2.21.0.392.gf8f6787159e-goog +---- + +[[now-what]] +== My Patch Got Emailed - Now What? + +[[reviewing]] +=== Responding to Reviews + +After a few days, you will hopefully receive a reply to your patchset with some +comments. Woohoo! Now you can get back to work. + +It's good manners to reply to each comment, notifying the reviewer that you have +made the change suggested, feel the original is better, or that the comment +inspired you to do something a new way which is superior to both the original +and the suggested change. This way reviewers don't need to inspect your v2 to +figure out whether you implemented their comment or not. + +Reviewers may ask you about what you wrote in the patchset, either in +the proposed commit log message or in the changes themselves. You +should answer these questions in your response messages, but often the +reason why reviewers asked these questions to understand what you meant +to write is because your patchset needed clarification to be understood. + +Do not be satisfied by just answering their questions in your response +and hear them say that they now understand what you wanted to say. +Update your patches to clarify the points reviewers had trouble with, +and prepare your v2; the words you used to explain your v1 to answer +reviewers' questions may be useful thing to use. Your goal is to make +your v2 clear enough so that it becomes unnecessary for you to give the +same explanation to the next person who reads it. + +If you are going to push back on a comment, be polite and explain why you feel +your original is better; be prepared that the reviewer may still disagree with +you, and the rest of the community may weigh in on one side or the other. As +with all code reviews, it's important to keep an open mind to doing something a +different way than you originally planned; other reviewers have a different +perspective on the project than you do, and may be thinking of a valid side +effect which had not occurred to you. It is always okay to ask for clarification +if you aren't sure why a change was suggested, or what the reviewer is asking +you to do. + +Make sure your email client has a plaintext email mode and it is turned on; the +Git list rejects HTML email. Please also follow the mailing list etiquette +outlined in the +https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's +Note], which are similar to etiquette rules in most open source communities +surrounding bottom-posting and inline replies. + +When you're making changes to your code, it is cleanest - that is, the resulting +commits are easiest to look at - if you use `git rebase -i` (interactive +rebase). Take a look at this +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview] +from O'Reilly. The general idea is to modify each commit which requires changes; +this way, instead of having a patch A with a mistake, a patch B which was fine +and required no upstream reviews in v1, and a patch C which fixes patch A for +v2, you can just ship a v2 with a correct patch A and correct patch B. This is +changing history, but since it's local history which you haven't shared with +anyone, that is okay for now! (Later, it may not make sense to do this; take a +look at the section below this one for some context.) + +[[after-approval]] +=== After Review Approval + +The Git project has four integration branches: `seen`, `next`, `master`, and +`maint`. Your change will be placed into `seen` fairly early on by the maintainer +while it is still in the review process; from there, when it is ready for wider +testing, it will be merged into `next`. Plenty of early testers use `next` and +may report issues. Eventually, changes in `next` will make it to `master`, +which is typically considered stable. Finally, when a new release is cut, +`maint` is used to base bugfixes onto. As mentioned at the beginning of this +document, you can read `Documents/SubmittingPatches` for some more info about +the use of the various integration branches. + +Back to now: your code has been lauded by the upstream reviewers. It is perfect. +It is ready to be accepted. You don't need to do anything else; the maintainer +will merge your topic branch to `next` and life is good. + +However, if you discover it isn't so perfect after this point, you may need to +take some special steps depending on where you are in the process. + +If the maintainer has announced in the "What's cooking in git.git" email that +your topic is marked for `next` - that is, that they plan to merge it to `next` +but have not yet done so - you should send an email asking the maintainer to +wait a little longer: "I've sent v4 of my series and you marked it for `next`, +but I need to change this and that - please wait for v5 before you merge it." + +If the topic has already been merged to `next`, rather than modifying your +patches with `git rebase -i`, you should make further changes incrementally - +that is, with another commit, based on top of the maintainer's topic branch as +detailed in https://github.com/gitster/git. Your work is still in the same topic +but is now incremental, rather than a wholesale rewrite of the topic branch. + +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so +if you're sending your reviews out that way, you should be sure to open your PR +against the appropriate GitGitGadget/Git branch. + +If you're using `git send-email`, you can use it the same way as before, but you +should generate your diffs from `..` and base your work on +`` instead of `master`. diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt new file mode 100644 index 0000000..2d10eea --- /dev/null +++ b/Documentation/MyFirstObjectWalk.txt @@ -0,0 +1,870 @@ += My First Object Walk + +== What's an Object Walk? + +The object walk is a key concept in Git - this is the process that underpins +operations like object transfer and fsck. Beginning from a given commit, the +list of objects is found by walking parent relationships between commits (commit +X based on commit W) and containment relationships between objects (tree Y is +contained within commit X, and blob Z is located within tree Y, giving our +working tree for commit X something like `y/z.txt`). + +A related concept is the revision walk, which is focused on commit objects and +their parent relationships and does not delve into other object types. The +revision walk is used for operations like `git log`. + +=== Related Reading + +- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of + the revision walker in its various incarnations. +- `revision.h` +- https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists] + gives a good overview of the types of objects in Git and what your object + walk is really describing. + +== Setting Up + +Create a new branch from `master`. + +---- +git checkout -b revwalk origin/master +---- + +We'll put our fiddling into a new command. For fun, let's name it `git walken`. +Open up a new file `builtin/walken.c` and set up the command handler: + +---- +/* + * "git walken" + * + * Part of the "My First Object Walk" tutorial. + */ + +#include "builtin.h" + +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + trace_printf(_("cmd_walken incoming...\n")); + return 0; +} +---- + +NOTE: `trace_printf()` differs from `printf()` in that it can be turned on or +off at runtime. For the purposes of this tutorial, we will write `walken` as +though it is intended for use as a "plumbing" command: that is, a command which +is used primarily in scripts, rather than interactively by humans (a "porcelain" +command). So we will send our debug output to `trace_printf()` instead. When +running, enable trace output by setting the environment variable `GIT_TRACE`. + +Add usage text and `-h` handling, like all subcommands should consistently do +(our test suite will notice and complain if you fail to do so). + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + const char * const walken_usage[] = { + N_("git walken"), + NULL, + } + struct option options[] = { + OPT_END() + }; + + argc = parse_options(argc, argv, prefix, options, walken_usage, 0); + + ... +} +---- + +Also add the relevant line in `builtin.h` near `cmd_whatchanged()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix); +---- + +Include the command in `git.c` in `commands[]` near the entry for `whatchanged`, +maintaining alphabetical ordering: + +---- +{ "walken", cmd_walken, RUN_SETUP }, +---- + +Add it to the `Makefile` near the line for `builtin/worktree.o`: + +---- +BUILTIN_OBJS += builtin/walken.o +---- + +Build and test out your command, without forgetting to ensure the `DEVELOPER` +flag is set, and with `GIT_TRACE` enabled so the debug output can be seen: + +---- +$ echo DEVELOPER=1 >>config.mak +$ make +$ GIT_TRACE=1 ./bin-wrappers/git walken +---- + +NOTE: For a more exhaustive overview of the new command process, take a look at +`Documentation/MyFirstContribution.txt`. + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/revwalk. + +=== `struct rev_cmdline_info` + +The definition of `struct rev_cmdline_info` can be found in `revision.h`. + +This struct is contained within the `rev_info` struct and is used to reflect +parameters provided by the user over the CLI. + +`nr` represents the number of `rev_cmdline_entry` present in the array. + +`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is +used to track the allocated size of the list. + +Per entry, we find: + +`item` is the object provided upon which to base the object walk. Items in Git +can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.txt`.) + +`name` is the object ID (OID) of the object - a hex string you may be familiar +with from using Git to organize your source in the past. Check the tutorial +mentioned above towards the top for a discussion of where the OID can come +from. + +`whence` indicates some information about what to do with the parents of the +specified object. We'll explore this flag more later on; take a look at +`Documentation/revisions.txt` to get an idea of what could set the `whence` +value. + +`flags` are used to hint the beginning of the revision walk and are the first +block under the `#include`s in `revision.h`. The most likely ones to be set in +the `rev_cmdline_info` are `UNINTERESTING` and `BOTTOM`, but these same flags +can be used during the walk, as well. + +=== `struct rev_info` + +This one is quite a bit longer, and many fields are only used during the walk +by `revision.c` - not configuration options. Most of the configurable flags in +`struct rev_info` have a mirror in `Documentation/rev-list-options.txt`. It's a +good idea to take some time and read through that document. + +== Basic Commit Walk + +First, let's see if we can replicate the output of `git log --oneline`. We'll +refer back to the implementation frequently to discover norms when performing +an object walk of our own. + +To do so, we'll first find all the commits, in order, which preceded the current +commit. We'll extract the name and subject of the commit from each. + +Ideally, we will also be able to find out which ones are currently at the tip of +various branches. + +=== Setting Up + +Preparing for your object walk has some distinct stages. + +1. Perform default setup for this mode, and others which may be invoked. +2. Check configuration files for relevant settings. +3. Set up the `rev_info` struct. +4. Tweak the initialized `rev_info` to suit the current walk. +5. Prepare the `rev_info` for the walk. +6. Iterate over the objects, processing each one. + +==== Default Setups + +Before examining configuration files which may modify command behavior, set up +default state for switches or options your command may have. If your command +utilizes other Git components, ask them to set up their default states as well. +For instance, `git log` takes advantage of `grep` and `diff` functionality, so +its `init_log_defaults()` sets its own state (`decoration_style`) and asks +`grep` and `diff` to initialize themselves by calling each of their +initialization functions. + +==== Configuring From `.gitconfig` + +Next, we should have a look at any relevant configuration settings (i.e., +settings readable and settable from `git config`). This is done by providing a +callback to `git_config()`; within that callback, you can also invoke methods +from other components you may need that need to intercept these options. Your +callback will be invoked once per each configuration value which Git knows about +(global, local, worktree, etc.). + +Similarly to the default values, we don't have anything to do here yet +ourselves; however, we should call `git_default_config()` if we aren't calling +any other existing config callbacks. + +Add a new function to `builtin/walken.c`: + +---- +static int git_walken_config(const char *var, const char *value, void *cb) +{ + /* + * For now, we don't have any custom configuration, so fall back to + * the default config. + */ + return git_default_config(var, value, cb); +} +---- + +Make sure to invoke `git_config()` with it in your `cmd_walken()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + git_config(git_walken_config, NULL); + + ... +} +---- + +==== Setting Up `rev_info` + +Now that we've gathered external configuration and options, it's time to +initialize the `rev_info` object which we will use to perform the walk. This is +typically done by calling `repo_init_revisions()` with the repository you intend +to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info` +struct. + +Add the `struct rev_info` and the `repo_init_revisions()` call: +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + /* This can go wherever you like in your declarations.*/ + struct rev_info rev; + ... + + /* This should go after the git_config() call. */ + repo_init_revisions(the_repository, &rev, prefix); + + ... +} +---- + +==== Tweaking `rev_info` For the Walk + +We're getting close, but we're still not quite ready to go. Now that `rev` is +initialized, we can modify it to fit our needs. This is usually done within a +helper for clarity, so let's add one: + +---- +static void final_rev_info_setup(struct rev_info *rev) +{ + /* + * We want to mimic the appearance of `git log --oneline`, so let's + * force oneline format. + */ + get_commit_format("oneline", rev); + + /* Start our object walk at HEAD. */ + add_head_to_pending(rev); +} +---- + +[NOTE] +==== +Instead of using the shorthand `add_head_to_pending()`, you could do +something like this: +---- + struct setup_revision_opt opt; + + memset(&opt, 0, sizeof(opt)); + opt.def = "HEAD"; + opt.revarg_opt = REVARG_COMMITTISH; + setup_revisions(argc, argv, rev, &opt); +---- +Using a `setup_revision_opt` gives you finer control over your walk's starting +point. +==== + +Then let's invoke `final_rev_info_setup()` after the call to +`repo_init_revisions()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + final_rev_info_setup(&rev); + + ... +} +---- + +Later, we may wish to add more arguments to `final_rev_info_setup()`. But for +now, this is all we need. + +==== Preparing `rev_info` For the Walk + +Now that `rev` is all initialized and configured, we've got one more setup step +before we get rolling. We can do this in a helper, which will both prepare the +`rev_info` for the walk, and perform the walk itself. Let's start the helper +with the call to `prepare_revision_walk()`, which can return an error without +dying on its own: + +---- +static void walken_commit_walk(struct rev_info *rev) +{ + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); +} +---- + +NOTE: `die()` prints to `stderr` and exits the program. Since it will print to +`stderr` it's likely to be seen by a human, so we will localize it. + +==== Performing the Walk! + +Finally! We are ready to begin the walk itself. Now we can see that `rev_info` +can also be used as an iterator; we move to the next item in the walk by using +`get_revision()` repeatedly. Add the listed variable declarations at the top and +the walk loop below the `prepare_revision_walk()` call within your +`walken_commit_walk()`: + +---- +static void walken_commit_walk(struct rev_info *rev) +{ + struct commit *commit; + struct strbuf prettybuf = STRBUF_INIT; + + ... + + while ((commit = get_revision(rev))) { + strbuf_reset(&prettybuf); + pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf); + puts(prettybuf.buf); + } + strbuf_release(&prettybuf); +} +---- + +NOTE: `puts()` prints a `char*` to `stdout`. Since this is the part of the +command we expect to be machine-parsed, we're sending it directly to stdout. + +Give it a shot. + +---- +$ make +$ ./bin-wrappers/git walken +---- + +You should see all of the subject lines of all the commits in +your tree's history, in order, ending with the initial commit, "Initial revision +of "git", the information manager from hell". Congratulations! You've written +your first revision walk. You can play with printing some additional fields +from each commit if you're curious; have a look at the functions available in +`commit.h`. + +=== Adding a Filter + +Next, let's try to filter the commits we see based on their author. This is +equivalent to running `git log --author=`. We can add a filter by +modifying `rev_info.grep_filter`, which is a `struct grep_opt`. + +First some setup. Add `grep_config()` to `git_walken_config()`: + +---- +static int git_walken_config(const char *var, const char *value, void *cb) +{ + grep_config(var, value, cb); + return git_default_config(var, value, cb); +} +---- + +Next, we can modify the `grep_filter`. This is done with convenience functions +found in `grep.h`. For fun, we're filtering to only commits from folks using a +`gmail.com` email address - a not-very-precise guess at who may be working on +Git as a hobby. Since we're checking the author, which is a specific line in the +header, we'll use the `append_header_grep_pattern()` helper. We can use +the `enum grep_header_field` to indicate which part of the commit header we want +to search. + +In `final_rev_info_setup()`, add your filter line: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + append_header_grep_pattern(&rev->grep_filter, GREP_HEADER_AUTHOR, + "gmail"); + compile_grep_patterns(&rev->grep_filter); + + ... +} +---- + +`append_header_grep_pattern()` adds your new "gmail" pattern to `rev_info`, but +it won't work unless we compile it with `compile_grep_patterns()`. + +NOTE: If you are using `setup_revisions()` (for example, if you are passing a +`setup_revision_opt` instead of using `add_head_to_pending()`), you don't need +to call `compile_grep_patterns()` because `setup_revisions()` calls it for you. + +NOTE: We could add the same filter via the `append_grep_pattern()` helper if we +wanted to, but `append_header_grep_pattern()` adds the `enum grep_context` and +`enum grep_pat_token` for us. + +=== Changing the Order + +There are a few ways that we can change the order of the commits during a +revision walk. Firstly, we can use the `enum rev_sort_order` to choose from some +typical orderings. + +`topo_order` is the same as `git log --topo-order`: we avoid showing a parent +before all of its children have been shown, and we avoid mixing commits which +are in different lines of history. (`git help log`'s section on `--topo-order` +has a very nice diagram to illustrate this.) + +Let's see what happens when we run with `REV_SORT_BY_COMMIT_DATE` as opposed to +`REV_SORT_BY_AUTHOR_DATE`. Add the following: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_COMMIT_DATE; + + ... +} +---- + +Let's output this into a file so we can easily diff it with the walk sorted by +author date. + +---- +$ make +$ ./bin-wrappers/git walken > commit-date.txt +---- + +Then, let's sort by author date and run it again. + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_AUTHOR_DATE; + + ... +} +---- + +---- +$ make +$ ./bin-wrappers/git walken > author-date.txt +---- + +Finally, compare the two. This is a little less helpful without object names or +dates, but hopefully we get the idea. + +---- +$ diff -u commit-date.txt author-date.txt +---- + +This display indicates that commits can be reordered after they're written, for +example with `git rebase`. + +Let's try one more reordering of commits. `rev_info` exposes a `reverse` flag. +Set that flag somewhere inside of `final_rev_info_setup()`: + +---- +static void final_rev_info_setup(int argc, const char **argv, const char *prefix, + struct rev_info *rev) +{ + ... + + rev->reverse = 1; + + ... +} +---- + +Run your walk again and note the difference in order. (If you remove the grep +pattern, you should see the last commit this call gives you as your current +HEAD.) + +== Basic Object Walk + +So far we've been walking only commits. But Git has more types of objects than +that! Let's see if we can walk _all_ objects, and find out some information +about each one. + +We can base our work on an example. `git pack-objects` prepares all kinds of +objects for packing into a bitmap or packfile. The work we are interested in +resides in `builtins/pack-objects.c:get_object_list()`; examination of that +function shows that the all-object walk is being performed by +`traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two +functions reside in `list-objects.c`; examining the source shows that, despite +the name, these functions traverse all kinds of objects. Let's have a look at +the arguments to `traverse_commit_list_filtered()`, which are a superset of the +arguments to the unfiltered version. + +- `struct list_objects_filter_options *filter_options`: This is a struct which + stores a filter-spec as outlined in `Documentation/rev-list-options.txt`. +- `struct rev_info *revs`: This is the `rev_info` used for the walk. +- `show_commit_fn show_commit`: A callback which will be used to handle each + individual commit object. +- `show_object_fn show_object`: A callback which will be used to handle each + non-commit object (so each blob, tree, or tag). +- `void *show_data`: A context buffer which is passed in turn to `show_commit` + and `show_object`. +- `struct oidset *omitted`: A linked-list of object IDs which the provided + filter caused to be omitted. + +It looks like this `traverse_commit_list_filtered()` uses callbacks we provide +instead of needing us to call it repeatedly ourselves. Cool! Let's add the +callbacks first. + +For the sake of this tutorial, we'll simply keep track of how many of each kind +of object we find. At file scope in `builtin/walken.c` add the following +tracking variables: + +---- +static int commit_count; +static int tag_count; +static int blob_count; +static int tree_count; +---- + +Commits are handled by a different callback than other objects; let's do that +one first: + +---- +static void walken_show_commit(struct commit *cmt, void *buf) +{ + commit_count++; +} +---- + +The `cmt` argument is fairly self-explanatory. But it's worth mentioning that +the `buf` argument is actually the context buffer that we can provide to the +traversal calls - `show_data`, which we mentioned a moment ago. + +Since we have the `struct commit` object, we can look at all the same parts that +we looked at in our earlier commit-only walk. For the sake of this tutorial, +though, we'll just increment the commit counter and move on. + +The callback for non-commits is a little different, as we'll need to check +which kind of object we're dealing with: + +---- +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + switch (obj->type) { + case OBJ_TREE: + tree_count++; + break; + case OBJ_BLOB: + blob_count++; + break; + case OBJ_TAG: + tag_count++; + break; + case OBJ_COMMIT: + BUG("unexpected commit object in walken_show_object\n"); + default: + BUG("unexpected object type %s in walken_show_object\n", + type_name(obj->type)); + } +} +---- + +Again, `obj` is fairly self-explanatory, and we can guess that `buf` is the same +context pointer that `walken_show_commit()` receives: the `show_data` argument +to `traverse_commit_list()` and `traverse_commit_list_filtered()`. Finally, +`str` contains the name of the object, which ends up being something like +`foo.txt` (blob), `bar/baz` (tree), or `v1.2.3` (tag). + +To help assure us that we aren't double-counting commits, we'll include some +complaining if a commit object is routed through our non-commit callback; we'll +also complain if we see an invalid object type. Since those two cases should be +unreachable, and would only change in the event of a semantic change to the Git +codebase, we complain by using `BUG()` - which is a signal to a developer that +the change they made caused unintended consequences, and the rest of the +codebase needs to be updated to understand that change. `BUG()` is not intended +to be seen by the public, so it is not localized. + +Our main object walk implementation is substantially different from our commit +walk implementation, so let's make a new function to perform the object walk. We +can perform setup which is applicable to all objects here, too, to keep separate +from setup which is applicable to commit-only walks. + +We'll start by enabling all types of objects in the `struct rev_info`. We'll +also turn on `tree_blobs_in_commit_order`, which means that we will walk a +commit's tree and everything it points to immediately after we find each commit, +as opposed to waiting for the end and walking through all trees after the commit +history has been discovered. With the appropriate settings configured, we are +ready to call `prepare_revision_walk()`. + +---- +static void walken_object_walk(struct rev_info *rev) +{ + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); + + commit_count = 0; + tag_count = 0; + blob_count = 0; + tree_count = 0; +---- + +Let's start by calling just the unfiltered walk and reporting our counts. +Complete your implementation of `walken_object_walk()`: + +---- + traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); + + printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count, + blob_count, tag_count, tree_count); +} +---- + +NOTE: This output is intended to be machine-parsed. Therefore, we are not +sending it to `trace_printf()`, and we are not localizing it - we need scripts +to be able to count on the formatting to be exactly the way it is shown here. +If we were intending this output to be read by humans, we would need to localize +it with `_()`. + +Finally, we'll ask `cmd_walken()` to use the object walk instead. Discussing +command line options is out of scope for this tutorial, so we'll just hardcode +a branch we can change at compile time. Where you call `final_rev_info_setup()` +and `walken_commit_walk()`, instead branch like so: + +---- + if (1) { + add_head_to_pending(&rev); + walken_object_walk(&rev); + } else { + final_rev_info_setup(argc, argv, prefix, &rev); + walken_commit_walk(&rev); + } +---- + +NOTE: For simplicity, we've avoided all the filters and sorts we applied in +`final_rev_info_setup()` and simply added `HEAD` to our pending queue. If you +want, you can certainly use the filters we added before by moving +`final_rev_info_setup()` out of the conditional and removing the call to +`add_head_to_pending()`. + +Now we can try to run our command! It should take noticeably longer than the +commit walk, but an examination of the output will give you an idea why. Your +output should look similar to this example, but with different counts: + +---- +Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees. +---- + +This makes sense. We have more trees than commits because the Git project has +lots of subdirectories which can change, plus at least one tree per commit. We +have no tags because we started on a commit (`HEAD`) and while tags can point to +commits, commits can't point to tags. + +NOTE: You will have different counts when you run this yourself! The number of +objects grows along with the Git project. + +=== Adding a Filter + +There are a handful of filters that we can apply to the object walk laid out in +`Documentation/rev-list-options.txt`. These filters are typically useful for +operations such as creating packfiles or performing a partial clone. They are +defined in `list-objects-filter-options.h`. For the purposes of this tutorial we +will use the "tree:1" filter, which causes the walk to omit all trees and blobs +which are not directly referenced by commits reachable from the commit in +`pending` when the walk begins. (`pending` is the list of objects which need to +be traversed during a walk; you can imagine a breadth-first tree traversal to +help understand. In our case, that means we omit trees and blobs not directly +referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only +`HEAD` in the `pending` list.) + +First, we'll need to `#include "list-objects-filter-options.h`" and set up the +`struct list_objects_filter_options` at the top of the function. + +---- +static void walken_object_walk(struct rev_info *rev) +{ + struct list_objects_filter_options filter_options = {}; + + ... +---- + +For now, we are not going to track the omitted objects, so we'll replace those +parameters with `NULL`. For the sake of simplicity, we'll add a simple +build-time branch to use our filter or not. Replace the line calling +`traverse_commit_list()` with the following, which will remind us which kind of +walk we've just performed: + +---- + if (0) { + /* Unfiltered: */ + trace_printf(_("Unfiltered object walk.\n")); + traverse_commit_list(rev, walken_show_commit, + walken_show_object, NULL); + } else { + trace_printf( + _("Filtered object walk with filterspec 'tree:1'.\n")); + parse_list_objects_filter(&filter_options, "tree:1"); + + traverse_commit_list_filtered(&filter_options, rev, + walken_show_commit, walken_show_object, NULL, NULL); + } +---- + +`struct list_objects_filter_options` is usually built directly from a command +line argument, so the module provides an easy way to build one from a string. +Even though we aren't taking user input right now, we can still build one with +a hardcoded string using `parse_list_objects_filter()`. + +With the filter spec "tree:1", we are expecting to see _only_ the root tree for +each commit; therefore, the tree object count should be less than or equal to +the number of commits. (For an example of why that's true: `git commit --revert` +points to the same tree object as its grandparent.) + +=== Counting Omitted Objects + +We also have the capability to enumerate all objects which were omitted by a +filter, like with `git log --filter= --filter-print-omitted`. Asking +`traverse_commit_list_filtered()` to populate the `omitted` list means that our +object walk does not perform any better than an unfiltered object walk; all +reachable objects are walked in order to populate the list. + +First, add the `struct oidset` and related items we will use to iterate it: + +---- +static void walken_object_walk( + ... + + struct oidset omitted; + struct oidset_iter oit; + struct object_id *oid = NULL; + int omitted_count = 0; + oidset_init(&omitted, 0); + + ... +---- + +Modify the call to `traverse_commit_list_filtered()` to include your `omitted` +object: + +---- + ... + + traverse_commit_list_filtered(&filter_options, rev, + walken_show_commit, walken_show_object, NULL, &omitted); + + ... +---- + +Then, after your traversal, the `oidset` traversal is pretty straightforward. +Count all the objects within and modify the print statement: + +---- + /* Count the omitted objects. */ + oidset_iter_init(&omitted, &oit); + + while ((oid = oidset_iter_next(&oit))) + omitted_count++; + + printf("commits %d\nblobs %d\ntags %d\ntrees%d\nomitted %d\n", + commit_count, blob_count, tag_count, tree_count, omitted_count); +---- + +By running your walk with and without the filter, you should find that the total +object count in each case is identical. You can also time each invocation of +the `walken` subcommand, with and without `omitted` being passed in, to confirm +to yourself the runtime impact of tracking all omitted objects. + +=== Changing the Order + +Finally, let's demonstrate that you can also reorder walks of all objects, not +just walks of commits. First, we'll make our handlers chattier - modify +`walken_show_commit()` and `walken_show_object()` to print the object as they +go: + +---- +static void walken_show_commit(struct commit *cmt, void *buf) +{ + trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); + commit_count++; +} + +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + trace_printf("%s: %s\n", type_name(obj->type), oid_to_hex(&obj->oid)); + + ... +} +---- + +NOTE: Since we will be examining this output directly as humans, we'll use +`trace_printf()` here. Additionally, since this change introduces a significant +number of printed lines, using `trace_printf()` will allow us to easily silence +those lines without having to recompile. + +(Leave the counter increment logic in place.) + +With only that change, run again (but save yourself some scrollback): + +---- +$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10 +---- + +Take a look at the top commit with `git show` and the object ID you printed; it +should be the same as the output of `git show HEAD`. + +Next, let's change a setting on our `struct rev_info` within +`walken_object_walk()`. Find where you're changing the other settings on `rev`, +such as `rev->tree_objects` and `rev->tree_blobs_in_commit_order`, and add the +`reverse` setting at the bottom: + +---- + ... + + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + rev->reverse = 1; + + ... +---- + +Now, run again, but this time, let's grab the last handful of objects instead +of the first handful: + +---- +$ make +$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10 +---- + +The last commit object given should have the same OID as the one we saw at the +top before, and running `git show ` with that OID should give you again +the same results as `git show HEAD`. Furthermore, if you run and examine the +first ten lines again (with `head` instead of `tail` like we did before applying +the `reverse` setting), you should see that now the first commit printed is the +initial commit, `e83c5163`. + +== Wrapping Up + +Let's review. In this tutorial, we: + +- Built a commit walk from the ground up +- Enabled a grep filter for that commit walk +- Changed the sort order of that filtered commit walk +- Built an object walk (tags, commits, trees, and blobs) from the ground up +- Learned how to add a filter-spec to an object walk +- Changed the display order of the filtered object walk diff --git a/Documentation/RelNotes/1.5.0.1.txt b/Documentation/RelNotes/1.5.0.1.txt new file mode 100644 index 0000000..fea3f99 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.1.txt @@ -0,0 +1,42 @@ +GIT v1.5.0.1 Release Notes +========================== + +Fixes since v1.5.0 +------------------ + +* Documentation updates + + - Clarifications and corrections to 1.5.0 release notes. + + - The main documentation did not link to git-remote documentation. + + - Clarified introductory text of git-rebase documentation. + + - Converted remaining mentions of update-index on Porcelain + documents to git-add/git-rm. + + - Some i18n.* configuration variables were incorrectly + described as core.*; fixed. + +* Bugfixes + + - git-add and git-update-index on a filesystem on which + executable bits are unreliable incorrectly reused st_mode + bits even when the path changed between symlink and regular + file. + + - git-daemon marks the listening sockets with FD_CLOEXEC so + that it won't be leaked into the children. + + - segfault from git-blame when the mandatory pathname + parameter was missing was fixed; usage() message is given + instead. + + - git-rev-list did not read $GIT_DIR/config file, which means + that did not honor i18n.logoutputencoding correctly. + +* Tweaks + + - sliding mmap() inefficiently mmaped the same region of a + packfile with an access pattern that used objects in the + reverse order. This has been made more efficient. diff --git a/Documentation/RelNotes/1.5.0.2.txt b/Documentation/RelNotes/1.5.0.2.txt new file mode 100644 index 0000000..b061e50 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.2.txt @@ -0,0 +1,65 @@ +GIT v1.5.0.2 Release Notes +========================== + +Fixes since v1.5.0.1 +-------------------- + +* Bugfixes + + - Automated merge conflict handling when changes to symbolic + links conflicted were completely broken. The merge-resolve + strategy created a regular file with conflict markers in it + in place of the symbolic link. The default strategy, + merge-recursive was even more broken. It removed the path + that was pointed at by the symbolic link. Both of these + problems have been fixed. + + - 'git diff maint master next' did not correctly give combined + diff across three trees. + + - 'git fast-import' portability fix for Solaris. + + - 'git show-ref --verify' without arguments did not error out + but segfaulted. + + - 'git diff :tracked-file `pwd`/an-untracked-file' gave an extra + slashes after a/ and b/. + + - 'git format-patch' produced too long filenames if the commit + message had too long line at the beginning. + + - Running 'make all' and then without changing anything + running 'make install' still rebuilt some files. This + was inconvenient when building as yourself and then + installing as root (especially problematic when the source + directory is on NFS and root is mapped to nobody). + + - 'git-rerere' failed to deal with two unconflicted paths that + sorted next to each other. + + - 'git-rerere' attempted to open(2) a symlink and failed if + there was a conflict. Since a conflicting change to a + symlink would not benefit from rerere anyway, the command + now ignores conflicting changes to symlinks. + + - 'git-repack' did not like to pass more than 64 arguments + internally to underlying 'rev-list' logic, which made it + impossible to repack after accumulating many (small) packs + in the repository. + + - 'git-diff' to review the combined diff during a conflicted + merge were not reading the working tree version correctly + when changes to a symbolic link conflicted. It should have + read the data using readlink(2) but read from the regular + file the symbolic link pointed at. + + - 'git-remote' did not like period in a remote's name. + +* Documentation updates + + - added and clarified core.bare, core.legacyheaders configurations. + + - updated "git-clone --depth" documentation. + + +* Assorted git-gui fixes. diff --git a/Documentation/RelNotes/1.5.0.3.txt b/Documentation/RelNotes/1.5.0.3.txt new file mode 100644 index 0000000..cd500f9 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.3.txt @@ -0,0 +1,58 @@ +GIT v1.5.0.3 Release Notes +========================== + +Fixes since v1.5.0.2 +-------------------- + +* Bugfixes + + - 'git.el' honors the commit coding system from the configuration. + + - 'blameview' in contrib/ correctly digs deeper when a line is + clicked. + + - 'http-push' correctly makes sure the remote side has leading + path. Earlier it started in the middle of the path, and + incorrectly. + + - 'git-merge' did not exit with non-zero status when the + working tree was dirty and cannot fast forward. It does + now. + + - 'cvsexportcommit' does not lose yet-to-be-used message file. + + - int-vs-size_t typefix when running combined diff on files + over 2GB long. + + - 'git apply --whitespace=strip' should not touch unmodified + lines. + + - 'git-mailinfo' choke when a logical header line was too long. + + - 'git show A..B' did not error out. Negative ref ("not A" in + this example) does not make sense for the purpose of the + command, so now it errors out. + + - 'git fmt-merge-msg --file' without file parameter did not + correctly error out. + + - 'git archimport' barfed upon encountering a commit without + summary. + + - 'git index-pack' did not protect itself from getting a short + read out of pread(2). + + - 'git http-push' had a few buffer overruns. + + - Build dependency fixes to rebuild fetch.o when other headers + change. + +* Documentation updates + + - user-manual updates. + + - Options to 'git remote add' were described insufficiently. + + - Configuration format.suffix was not documented. + + - Other formatting and spelling fixes. diff --git a/Documentation/RelNotes/1.5.0.4.txt b/Documentation/RelNotes/1.5.0.4.txt new file mode 100644 index 0000000..feefa5d --- /dev/null +++ b/Documentation/RelNotes/1.5.0.4.txt @@ -0,0 +1,22 @@ +GIT v1.5.0.4 Release Notes +========================== + +Fixes since v1.5.0.3 +-------------------- + +* Bugfixes + + - git.el does not add duplicate sign-off lines. + + - git-commit shows the full stat of the resulting commit, not + just about the files in the current directory, when run from + a subdirectory. + + - "git-checkout -m '@{8 hours ago}'" had a funny failure from + eval; fixed. + + - git-gui updates. + +* Documentation updates + +* User manual updates diff --git a/Documentation/RelNotes/1.5.0.5.txt b/Documentation/RelNotes/1.5.0.5.txt new file mode 100644 index 0000000..eeec3d7 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.5.txt @@ -0,0 +1,26 @@ +GIT v1.5.0.5 Release Notes +========================== + +Fixes since v1.5.0.3 +-------------------- + +* Bugfixes + + - git-merge (hence git-pull) did not refuse fast-forwarding + when the working tree had local changes that would have + conflicted with it. + + - git.el does not add duplicate sign-off lines. + + - git-commit shows the full stat of the resulting commit, not + just about the files in the current directory, when run from + a subdirectory. + + - "git-checkout -m '@{8 hours ago}'" had a funny failure from + eval; fixed. + + - git-gui updates. + +* Documentation updates + +* User manual updates diff --git a/Documentation/RelNotes/1.5.0.6.txt b/Documentation/RelNotes/1.5.0.6.txt new file mode 100644 index 0000000..c02015a --- /dev/null +++ b/Documentation/RelNotes/1.5.0.6.txt @@ -0,0 +1,21 @@ +GIT v1.5.0.6 Release Notes +========================== + +Fixes since v1.5.0.5 +-------------------- + +* Bugfixes + + - a handful small fixes to gitweb. + + - build procedure for user-manual is fixed not to require locally + installed stylesheets. + + - "git commit $paths" on paths whose earlier contents were + already updated in the index were failing out. + +* Documentation + + - user-manual has better cross references. + + - gitweb installation/deployment procedure is now documented. diff --git a/Documentation/RelNotes/1.5.0.7.txt b/Documentation/RelNotes/1.5.0.7.txt new file mode 100644 index 0000000..670ad32 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.7.txt @@ -0,0 +1,18 @@ +GIT v1.5.0.7 Release Notes +========================== + +Fixes since v1.5.0.6 +-------------------- + +* Bugfixes + + - git-upload-pack failed to close unused pipe ends, resulting + in many zombies to hang around. + + - git-rerere was recording the contents of earlier hunks + duplicated in later hunks. This prevented resolving the same + conflict when performing the same merge the other way around. + +* Documentation + + - a few documentation fixes from Debian package maintainer. diff --git a/Documentation/RelNotes/1.5.0.txt b/Documentation/RelNotes/1.5.0.txt new file mode 100644 index 0000000..d6d42f3 --- /dev/null +++ b/Documentation/RelNotes/1.5.0.txt @@ -0,0 +1,469 @@ +GIT v1.5.0 Release Notes +======================== + +Old news +-------- + +This section is for people who are upgrading from ancient +versions of git. Although all of the changes in this section +happened before the current v1.4.4 release, they are summarized +here in the v1.5.0 release notes for people who skipped earlier +versions. + +As of git v1.5.0 there are some optional features that changes +the repository to allow data to be stored and transferred more +efficiently. These features are not enabled by default, as they +will make the repository unusable with older versions of git. +Specifically, the available options are: + + - There is a configuration variable core.legacyheaders that + changes the format of loose objects so that they are more + efficient to pack and to send out of the repository over git + native protocol, since v1.4.2. However, loose objects + written in the new format cannot be read by git older than + that version; people fetching from your repository using + older clients over dumb transports (e.g. http) using older + versions of git will also be affected. + + To let git use the new loose object format, you have to + set core.legacyheaders to false. + + - Since v1.4.3, configuration repack.usedeltabaseoffset allows + packfile to be created in more space efficient format, which + cannot be read by git older than that version. + + To let git use the new format for packfiles, you have to + set repack.usedeltabaseoffset to true. + +The above two new features are not enabled by default and you +have to explicitly ask for them, because they make repositories +unreadable by older versions of git, and in v1.5.0 we still do +not enable them by default for the same reason. We will change +this default probably 1 year after 1.4.2's release, when it is +reasonable to expect everybody to have new enough version of +git. + + - 'git pack-refs' appeared in v1.4.4; this command allows tags + to be accessed much more efficiently than the traditional + 'one-file-per-tag' format. Older git-native clients can + still fetch from a repository that packed and pruned refs + (the server side needs to run the up-to-date version of git), + but older dumb transports cannot. Packing of refs is done by + an explicit user action, either by use of "git pack-refs + --prune" command or by use of "git gc" command. + + - 'git -p' to paginate anything -- many commands do pagination + by default on a tty. Introduced between v1.4.1 and v1.4.2; + this may surprise old timers. + + - 'git archive' superseded 'git tar-tree' in v1.4.3; + + - 'git cvsserver' was new invention in v1.3.0; + + - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were + seriously enhanced during v1.4.0 timeperiod. + + - 'gitweb' became part of git.git during v1.4.0 timeperiod and + seriously modified since then. + + - reflog is an v1.4.0 invention. This allows you to name a + revision that a branch used to be at (e.g. "git diff + master@{yesterday} master" allows you to see changes since + yesterday's tip of the branch). + + +Updates in v1.5.0 since v1.4.4 series +------------------------------------- + +* Index manipulation + + - git-add is to add contents to the index (aka "staging area" + for the next commit), whether the file the contents happen to + be is an existing one or a newly created one. + + - git-add without any argument does not add everything + anymore. Use 'git-add .' instead. Also you can add + otherwise ignored files with an -f option. + + - git-add tries to be more friendly to users by offering an + interactive mode ("git-add -i"). + + - git-commit used to refuse to commit if was + different between HEAD and the index (i.e. update-index was + used on it earlier). This check was removed. + + - git-rm is much saner and safer. It is used to remove paths + from both the index file and the working tree, and makes sure + you are not losing any local modification before doing so. + + - git-reset ... can be used to revert index + entries for selected paths. + + - git-update-index is much less visible. Many suggestions to + use the command in git output and documentation have now been + replaced by simpler commands such as "git add" or "git rm". + + +* Repository layout and objects transfer + + - The data for origin repository is stored in the configuration + file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly + created clones. The latter is still supported and there is + no need to convert your existing repository if you are + already comfortable with your workflow with the layout. + + - git-clone always uses what is known as "separate remote" + layout for a newly created repository with a working tree. + + A repository with the separate remote layout starts with only + one default branch, 'master', to be used for your own + development. Unlike the traditional layout that copied all + the upstream branches into your branch namespace (while + renaming their 'master' to your 'origin'), the new layout + puts upstream branches into local "remote-tracking branches" + with their own namespace. These can be referenced with names + such as "origin/$upstream_branch_name" and are stored in + .git/refs/remotes rather than .git/refs/heads where normal + branches are stored. + + This layout keeps your own branch namespace less cluttered, + avoids name collision with your upstream, makes it possible + to automatically track new branches created at the remote + after you clone from it, and makes it easier to interact with + more than one remote repository (you can use "git remote" to + add other repositories to track). There might be some + surprises: + + * 'git branch' does not show the remote tracking branches. + It only lists your own branches. Use '-r' option to view + the tracking branches. + + * If you are forking off of a branch obtained from the + upstream, you would have done something like 'git branch + my-next next', because traditional layout dropped the + tracking branch 'next' into your own branch namespace. + With the separate remote layout, you say 'git branch next + origin/next', which allows you to use the matching name + 'next' for your own branch. It also allows you to track a + remote other than 'origin' (i.e. where you initially cloned + from) and fork off of a branch from there the same way + (e.g. "git branch mingw j6t/master"). + + Repositories initialized with the traditional layout continue + to work. + + - New branches that appear on the origin side after a clone is + made are also tracked automatically. This is done with an + wildcard refspec "refs/heads/*:refs/remotes/origin/*", which + older git does not understand, so if you clone with 1.5.0, + you would need to downgrade remote.*.fetch in the + configuration file to specify each branch you are interested + in individually if you plan to fetch into the repository with + older versions of git (but why would you?). + + - Similarly, wildcard refspec "refs/heads/*:refs/remotes/me/*" + can be given to "git-push" command to update the tracking + branches that is used to track the repository you are pushing + from on the remote side. + + - git-branch and git-show-branch know remote tracking branches + (use the command line switch "-r" to list only tracked branches). + + - git-push can now be used to delete a remote branch or a tag. + This requires the updated git on the remote side (use "git + push :refs/heads/" to delete "branch"). + + - git-push more aggressively keeps the transferred objects + packed. Earlier we recommended to monitor amount of loose + objects and repack regularly, but you should repack when you + accumulated too many small packs this way as well. Updated + git-count-objects helps you with this. + + - git-fetch also more aggressively keeps the transferred objects + packed. This behavior of git-push and git-fetch can be + tweaked with a single configuration transfer.unpacklimit (but + usually there should not be any need for a user to tweak it). + + - A new command, git-remote, can help you manage your remote + tracking branch definitions. + + - You may need to specify explicit paths for upload-pack and/or + receive-pack due to your ssh daemon configuration on the + other end. This can now be done via remote.*.uploadpack and + remote.*.receivepack configuration. + + +* Bare repositories + + - Certain commands change their behavior in a bare repository + (i.e. a repository without associated working tree). We use + a fairly conservative heuristic (if $GIT_DIR is ".git", or + ends with "/.git", the repository is not bare) to decide if a + repository is bare, but "core.bare" configuration variable + can be used to override the heuristic when it misidentifies + your repository. + + - git-fetch used to complain updating the current branch but + this is now allowed for a bare repository. So is the use of + 'git-branch -f' to update the current branch. + + - Porcelain-ish commands that require a working tree refuses to + work in a bare repository. + + +* Reflog + + - Reflog records the history from the view point of the local + repository. In other words, regardless of the real history, + the reflog shows the history as seen by one particular + repository (this enables you to ask "what was the current + revision in _this_ repository, yesterday at 1pm?"). This + facility is enabled by default for repositories with working + trees, and can be accessed with the "branch@{time}" and + "branch@{Nth}" notation. + + - "git show-branch" learned showing the reflog data with the + new -g option. "git log" has -g option to view reflog + entries in a more verbose manner. + + - git-branch knows how to rename branches and moves existing + reflog data from the old branch to the new one. + + - In addition to the reflog support in v1.4.4 series, HEAD + reference maintains its own log. "HEAD@{5.minutes.ago}" + means the commit you were at 5 minutes ago, which takes + branch switching into account. If you want to know where the + tip of your current branch was at 5 minutes ago, you need to + explicitly say its name (e.g. "master@{5.minutes.ago}") or + omit the refname altogether i.e. "@{5.minutes.ago}". + + - The commits referred to by reflog entries are now protected + against pruning. The new command "git reflog expire" can be + used to truncate older reflog entries and entries that refer + to commits that have been pruned away previously with older + versions of git. + + Existing repositories that have been using reflog may get + complaints from fsck-objects and may not be able to run + git-repack, if you had run git-prune from older git; please + run "git reflog expire --stale-fix --all" first to remove + reflog entries that refer to commits that are no longer in + the repository when that happens. + + +* Cruft removal + + - We used to say "old commits are retrievable using reflog and + 'master@{yesterday}' syntax as long as you haven't run + git-prune". We no longer have to say the latter half of the + above sentence, as git-prune does not remove things reachable + from reflog entries. + + - There is a toplevel garbage collector script, 'git-gc', that + runs periodic cleanup functions, including 'git-repack -a -d', + 'git-reflog expire', 'git-pack-refs --prune', and 'git-rerere + gc'. + + - The output from fsck ("fsck-objects" is called just "fsck" + now, but the old name continues to work) was needlessly + alarming in that it warned missing objects that are reachable + only from dangling objects. This has been corrected and the + output is much more useful. + + +* Detached HEAD + + - You can use 'git-checkout' to check out an arbitrary revision + or a tag as well, instead of named branches. This will + dissociate your HEAD from the branch you are currently on. + + A typical use of this feature is to "look around". E.g. + + $ git checkout v2.6.16 + ... compile, test, etc. + $ git checkout v2.6.17 + ... compile, test, etc. + + - After detaching your HEAD, you can go back to an existing + branch with usual "git checkout $branch". Also you can + start a new branch using "git checkout -b $newbranch" to + start a new branch at that commit. + + - You can even pull from other repositories, make merges and + commits while your HEAD is detached. Also you can use "git + reset" to jump to arbitrary commit, while still keeping your + HEAD detached. + + Remember that a detached state is volatile, i.e. it will be forgotten + as soon as you move away from it with the checkout or reset command, + unless a branch is created from it as mentioned above. It is also + possible to rescue a lost detached state from the HEAD reflog. + + +* Packed refs + + - Repositories with hundreds of tags have been paying large + overhead, both in storage and in runtime, due to the + traditional one-ref-per-file format. A new command, + git-pack-refs, can be used to "pack" them in more efficient + representation (you can let git-gc do this for you). + + - Clones and fetches over dumb transports are now aware of + packed refs and can download from repositories that use + them. + + +* Configuration + + - configuration related to color setting are consolidated under + color.* namespace (older diff.color.*, status.color.* are + still supported). + + - 'git-repo-config' command is accessible as 'git-config' now. + + +* Updated features + + - git-describe uses better criteria to pick a base ref. It + used to pick the one with the newest timestamp, but now it + picks the one that is topologically the closest (that is, + among ancestors of commit C, the ref T that has the shortest + output from "git-rev-list T..C" is chosen). + + - git-describe gives the number of commits since the base ref + between the refname and the hash suffix. E.g. the commit one + before v2.6.20-rc6 in the kernel repository is: + + v2.6.20-rc5-306-ga21b069 + + which tells you that its object name begins with a21b069, + v2.6.20-rc5 is an ancestor of it (meaning, the commit + contains everything -rc5 has), and there are 306 commits + since v2.6.20-rc5. + + - git-describe with --abbrev=0 can be used to show only the + name of the base ref. + + - git-blame learned a new option, --incremental, that tells it + to output the blames as they are assigned. A sample script + to use it is also included as contrib/blameview. + + - git-blame starts annotating from the working tree by default. + + +* Less external dependency + + - We no longer require the "merge" program from the RCS suite. + All 3-way file-level merges are now done internally. + + - The original implementation of git-merge-recursive which was + in Python has been removed; we have a C implementation of it + now. + + - git-shortlog is no longer a Perl script. It no longer + requires output piped from git-log; it can accept revision + parameters directly on the command line. + + +* I18n + + - We have always encouraged the commit message to be encoded in + UTF-8, but the users are allowed to use legacy encoding as + appropriate for their projects. This will continue to be the + case. However, a non UTF-8 commit encoding _must_ be + explicitly set with i18n.commitencoding in the repository + where a commit is made; otherwise git-commit-tree will + complain if the log message does not look like a valid UTF-8 + string. + + - The value of i18n.commitencoding in the originating + repository is recorded in the commit object on the "encoding" + header, if it is not UTF-8. git-log and friends notice this, + and re-encodes the message to the log output encoding when + displaying, if they are different. The log output encoding + is determined by "git log --encoding=", + i18n.logoutputencoding configuration, or i18n.commitencoding + configuration, in the decreasing order of preference, and + defaults to UTF-8. + + - Tools for e-mailed patch application now default to -u + behavior; i.e. it always re-codes from the e-mailed encoding + to the encoding specified with i18n.commitencoding. This + unfortunately forces projects that have happily been using a + legacy encoding without setting i18n.commitencoding to set + the configuration, but taken with other improvement, please + excuse us for this very minor one-time inconvenience. + + +* e-mailed patches + + - See the above I18n section. + + - git-format-patch now enables --binary without being asked. + git-am does _not_ default to it, as sending binary patch via + e-mail is unusual and is harder to review than textual + patches and it is prudent to require the person who is + applying the patch to explicitly ask for it. + + - The default suffix for git-format-patch output is now ".patch", + not ".txt". This can be changed with --suffix=.txt option, + or setting the config variable "format.suffix" to ".txt". + + +* Foreign SCM interfaces + + - git-svn now requires the Perl SVN:: libraries, the + command-line backend was too slow and limited. + + - the 'commit' subcommand of git-svn has been renamed to + 'set-tree', and 'dcommit' is the recommended replacement for + day-to-day work. + + - git fast-import backend. + + +* User support + + - Quite a lot of documentation updates. + + - Bash completion scripts have been updated heavily. + + - Better error messages for often used Porcelainish commands. + + - Git GUI. This is a simple Tk based graphical interface for + common Git operations. + + +* Sliding mmap + + - We used to assume that we can mmap the whole packfile while + in use, but with a large project this consumes huge virtual + memory space and truly huge ones would not fit in the + userland address space on 32-bit platforms. We now mmap huge + packfile in pieces to avoid this problem. + + +* Shallow clones + + - There is a partial support for 'shallow' repositories that + keeps only recent history. A 'shallow clone' is created by + specifying how deep that truncated history should be + (e.g. "git clone --depth 5 git://some.where/repo.git"). + + Currently a shallow repository has number of limitations: + + - Cloning and fetching _from_ a shallow clone are not + supported (nor tested -- so they might work by accident but + they are not expected to). + + - Pushing from nor into a shallow clone are not expected to + work. + + - Merging inside a shallow repository would work as long as a + merge base is found in the recent history, but otherwise it + will be like merging unrelated histories and may result in + huge conflicts. + + but this would be more than adequate for people who want to + look at near the tip of a big project with a deep history and + send patches in e-mail format. diff --git a/Documentation/RelNotes/1.5.1.1.txt b/Documentation/RelNotes/1.5.1.1.txt new file mode 100644 index 0000000..9147121 --- /dev/null +++ b/Documentation/RelNotes/1.5.1.1.txt @@ -0,0 +1,65 @@ +GIT v1.5.1.1 Release Notes +========================== + +Fixes since v1.5.1 +------------------ + +* Documentation updates + + - The --left-right option of rev-list and friends is documented. + + - The documentation for cvsimport has been majorly improved. + + - "git-show-ref --exclude-existing" was documented. + +* Bugfixes + + - The implementation of -p option in "git cvsexportcommit" had + the meaning of -C (context reduction) option wrong, and + loosened the context requirements when it was told to be + strict. + + - "git cvsserver" did not behave like the real cvsserver when + client side removed a file from the working tree without + doing anything else on the path. In such a case, it should + restore it from the checked out revision. + + - "git fsck" issued an alarming error message on detached + HEAD. It is not an error since at least 1.5.0. + + - "git send-email" produced of References header of unbounded length; + fixed this with line-folding. + + - "git archive" to download from remote site should not + require you to be in a git repository, but it incorrectly + did. + + - "git apply" ignored -p for "diff --git" formatted + patches. + + - "git rerere" recorded a conflict that had one side empty + (the other side adds) incorrectly; this made merging in the + other direction fail to use previously recorded resolution. + + - t4200 test was broken where "wc -l" pads its output with + spaces. + + - "git branch -m old new" to rename branch did not work + without a configuration file in ".git/config". + + - The sample hook for notification e-mail was misnamed. + + - gitweb did not show type-changing patch correctly in the + blobdiff view. + + - git-svn did not error out with incorrect command line options. + + - git-svn fell into an infinite loop when insanely long commit + message was found. + + - git-svn dcommit and rebase was confused by patches that were + merged from another branch that is managed by git-svn. + + - git-svn used to get confused when globbing remote branch/tag + spec (e.g. "branches = proj/branches/*:refs/remotes/origin/*") + is used and there was a plain file that matched the glob. diff --git a/Documentation/RelNotes/1.5.1.2.txt b/Documentation/RelNotes/1.5.1.2.txt new file mode 100644 index 0000000..d884563 --- /dev/null +++ b/Documentation/RelNotes/1.5.1.2.txt @@ -0,0 +1,50 @@ +GIT v1.5.1.2 Release Notes +========================== + +Fixes since v1.5.1.1 +-------------------- + +* Bugfixes + + - "git clone" over http from a repository that has lost the + loose refs by running "git pack-refs" were broken (a code to + deal with this was added to "git fetch" in v1.5.0, but it + was missing from "git clone"). + + - "git diff a/ b/" incorrectly fell in "diff between two + filesystem objects" codepath, when the user most likely + wanted to limit the extent of output to two tracked + directories. + + - git-quiltimport had the same bug as we fixed for + git-applymbox in v1.5.1.1 -- it gave an alarming "did not + have any patch" message (but did not actually fail and was + harmless). + + - various git-svn fixes. + + - Sample update hook incorrectly always refused requests to + delete branches through push. + + - git-blame on a very long working tree path had buffer + overrun problem. + + - git-apply did not like to be fed two patches in a row that created + and then modified the same file. + + - git-svn was confused when a non-project was stored directly under + trunk/, branches/ and tags/. + + - git-svn wants the Error.pm module that was at least as new + as what we ship as part of git; install ours in our private + installation location if the one on the system is older. + + - An earlier update to command line integer parameter parser was + botched and made 'update-index --cacheinfo' completely useless. + + +* Documentation updates + + - Various documentation updates from J. Bruce Fields, Frank + Lichtenheld, Alex Riesen and others. Andrew Ruder started a + war on undocumented options. diff --git a/Documentation/RelNotes/1.5.1.3.txt b/Documentation/RelNotes/1.5.1.3.txt new file mode 100644 index 0000000..876408b --- /dev/null +++ b/Documentation/RelNotes/1.5.1.3.txt @@ -0,0 +1,45 @@ +GIT v1.5.1.3 Release Notes +========================== + +Fixes since v1.5.1.2 +-------------------- + +* Bugfixes + + - git-add tried to optimize by finding common leading + directories across its arguments but botched, causing very + confused behaviour. + + - unofficial rpm.spec file shipped with git was letting + ETC_GITCONFIG set to /usr/etc/gitconfig. Tweak the official + Makefile to make it harder for distro people to make the + same mistake, by setting the variable to /etc/gitconfig if + prefix is set to /usr. + + - git-svn inconsistently stripped away username from the URL + only when svnsync_props was in use. + + - git-svn got confused when handling symlinks on Mac OS. + + - git-send-email was not quoting recipient names that have + period '.' in them. Also it did not allow overriding + envelope sender, which made it impossible to send patches to + certain subscriber-only lists. + + - built-in write_tree() routine had a sequence that renamed a + file that is still open, which some systems did not like. + + - when memory is very tight, sliding mmap code to read + packfiles incorrectly closed the fd that was still being + used to read the pack. + + - import-tars contributed front-end for fastimport was passing + wrong directory modes without checking. + + - git-fastimport trusted its input too much and allowed to + create corrupt tree objects with entries without a name. + + - git-fetch needlessly barfed when too long reflog action + description was given by the caller. + +Also contains various documentation updates. diff --git a/Documentation/RelNotes/1.5.1.4.txt b/Documentation/RelNotes/1.5.1.4.txt new file mode 100644 index 0000000..df2f66c --- /dev/null +++ b/Documentation/RelNotes/1.5.1.4.txt @@ -0,0 +1,30 @@ +GIT v1.5.1.4 Release Notes +========================== + +Fixes since v1.5.1.3 +-------------------- + +* Bugfixes + + - "git-http-fetch" did not work around a bug in libcurl + earlier than 7.16 (curl_multi_remove_handle() was broken). + + - "git cvsserver" handles a file that was once removed and + then added again correctly. + + - import-tars script (in contrib/) handles GNU tar archives + that contain pathnames longer than 100 bytes (long-link + extension) correctly. + + - xdelta test program did not build correctly. + + - gitweb sometimes tried incorrectly to apply function to + decode utf8 twice, resulting in corrupt output. + + - "git blame -C" mishandled text at the end of a group of + lines. + + - "git log/rev-list --boundary" did not produce output + correctly without --left-right option. + + - Many documentation updates. diff --git a/Documentation/RelNotes/1.5.1.5.txt b/Documentation/RelNotes/1.5.1.5.txt new file mode 100644 index 0000000..b0ab8eb --- /dev/null +++ b/Documentation/RelNotes/1.5.1.5.txt @@ -0,0 +1,42 @@ +GIT v1.5.1.5 Release Notes +========================== + +Fixes since v1.5.1.4 +-------------------- + +* Bugfixes + + - git-send-email did not understand aliases file for mutt, which + allows leading whitespaces. + + - git-format-patch emitted Content-Type and Content-Transfer-Encoding + headers for non ASCII contents, but failed to add MIME-Version. + + - git-name-rev had a buffer overrun with a deep history. + + - contributed script import-tars did not get the directory in + tar archives interpreted correctly. + + - git-svn was reported to segfault for many people on list and + #git; hopefully this has been fixed. + + - "git-svn clone" does not try to minimize the URL + (i.e. connect to higher level hierarchy) by default, as this + can prevent clone to fail if only part of the repository + (e.g. 'trunk') is open to public. + + - "git checkout branch^0" did not detach the head when you are + already on 'branch'; backported the fix from the 'master'. + + - "git-config section.var" did not correctly work when + existing configuration file had both [section] and [section "name"] + next to each other. + + - "git clone ../other-directory" was fooled if the current + directory $PWD points at is a symbolic link. + + - (build) tree_entry_extract() function was both static inline + and extern, which caused trouble compiling with Forte12 + compilers on Sun. + + - Many many documentation fixes and updates. diff --git a/Documentation/RelNotes/1.5.1.6.txt b/Documentation/RelNotes/1.5.1.6.txt new file mode 100644 index 0000000..55f3ac1 --- /dev/null +++ b/Documentation/RelNotes/1.5.1.6.txt @@ -0,0 +1,45 @@ +GIT v1.5.1.6 Release Notes +========================== + +Fixes since v1.5.1.4 +-------------------- + +* Bugfixes + + - git-send-email did not understand aliases file for mutt, which + allows leading whitespaces. + + - git-format-patch emitted Content-Type and Content-Transfer-Encoding + headers for non ASCII contents, but failed to add MIME-Version. + + - git-name-rev had a buffer overrun with a deep history. + + - contributed script import-tars did not get the directory in + tar archives interpreted correctly. + + - git-svn was reported to segfault for many people on list and + #git; hopefully this has been fixed. + + - git-svn also had a bug to crash svnserve by sending a bad + sequence of requests. + + - "git-svn clone" does not try to minimize the URL + (i.e. connect to higher level hierarchy) by default, as this + can prevent clone to fail if only part of the repository + (e.g. 'trunk') is open to public. + + - "git checkout branch^0" did not detach the head when you are + already on 'branch'; backported the fix from the 'master'. + + - "git-config section.var" did not correctly work when + existing configuration file had both [section] and [section "name"] + next to each other. + + - "git clone ../other-directory" was fooled if the current + directory $PWD points at is a symbolic link. + + - (build) tree_entry_extract() function was both static inline + and extern, which caused trouble compiling with Forte12 + compilers on Sun. + + - Many many documentation fixes and updates. diff --git a/Documentation/RelNotes/1.5.1.txt b/Documentation/RelNotes/1.5.1.txt new file mode 100644 index 0000000..daed367 --- /dev/null +++ b/Documentation/RelNotes/1.5.1.txt @@ -0,0 +1,371 @@ +GIT v1.5.1 Release Notes +======================== + +Updates since v1.5.0 +-------------------- + +* Deprecated commands and options. + + - git-diff-stages and git-resolve have been removed. + +* New commands and options. + + - "git log" and friends take --reverse, which instructs them + to give their output in the order opposite from their usual. + They typically output from new to old, but with this option + their output would read from old to new. "git shortlog" + usually lists older commits first, but with this option, + they are shown from new to old. + + - "git log --pretty=format:" to allow more flexible + custom log output. + + - "git diff" learned --ignore-space-at-eol. This is a weaker + form of --ignore-space-change. + + - "git diff --no-index pathA pathB" can be used as diff + replacement with git specific enhancements. + + - "git diff --no-index" can read from '-' (standard input). + + - "git diff" also learned --exit-code to exit with non-zero + status when it found differences. In the future we might + want to make this the default but that would be a rather big + backward incompatible change; it will stay as an option for + now. + + - "git diff --quiet" is --exit-code with output turned off, + meant for scripted use to quickly determine if there is any + tree-level difference. + + - Textual patch generation with "git diff" without -w/-b + option has been significantly optimized. "git blame" got + faster because of the same change. + + - "git log" and "git rev-list" has been optimized + significantly when they are used with pathspecs. + + - "git branch --track" can be used to set up configuration + variables to help it easier to base your work on branches + you track from a remote site. + + - "git format-patch --attach" now emits attachments. Use + --inline to get an inlined multipart/mixed. + + - "git name-rev" learned --refs=, to limit the tags + used for naming the given revisions only to the ones + matching the given pattern. + + - "git remote update" is to run "git fetch" for defined remotes + to update tracking branches. + + - "git cvsimport" can now take '-d' to talk with a CVS + repository different from what are recorded in CVS/Root + (overriding it with environment CVSROOT does not work). + + - "git bundle" can help sneaker-netting your changes between + repositories. + + - "git mergetool" can help 3-way file-level conflict + resolution with your favorite graphical merge tools. + + - A new configuration "core.symlinks" can be used to disable + symlinks on filesystems that do not support them; they are + checked out as regular files instead. + + - You can name a commit object with its first line of the + message. The syntax to use is ':/message text'. E.g. + + $ git show ":/object name: introduce ':/' notation" + + means the same thing as: + + $ git show 28a4d940443806412effa246ecc7768a21553ec7 + + - "git bisect" learned a new command "run" that takes a script + to run after each revision is checked out to determine if it + is good or bad, to automate the bisection process. + + - "git log" family learned a new traversal option --first-parent, + which does what the name suggests. + + +* Updated behavior of existing commands. + + - "git-merge-recursive" used to barf when there are more than + one common ancestors for the merge, and merging them had a + rename/rename conflict. This has been fixed. + + - "git fsck" does not barf on corrupt loose objects. + + - "git rm" does not remove newly added files without -f. + + - "git archimport" allows remapping when coming up with git + branch names from arch names. + + - git-svn got almost a rewrite. + + - core.autocrlf configuration, when set to 'true', makes git + to convert CRLF at the end of lines in text files to LF when + reading from the filesystem, and convert in reverse when + writing to the filesystem. The variable can be set to + 'input', in which case the conversion happens only while + reading from the filesystem but files are written out with + LF at the end of lines. Currently, which paths to consider + 'text' (i.e. be subjected to the autocrlf mechanism) is + decided purely based on the contents, but the plan is to + allow users to explicitly override this heuristic based on + paths. + + - The behavior of 'git-apply', when run in a subdirectory, + without --index nor --cached were inconsistent with that of + the command with these options. This was fixed to match the + behavior with --index. A patch that is meant to be applied + with -p1 from the toplevel of the project tree can be + applied with any custom -p option. A patch that is not + relative to the toplevel needs to be applied with -p + option with or without --index (or --cached). + + - "git diff" outputs a trailing HT when pathnames have embedded + SP on +++/--- header lines, in order to help "GNU patch" to + parse its output. "git apply" was already updated to accept + this modified output format since ce74618d (Sep 22, 2006). + + - "git cvsserver" runs hooks/update and honors its exit status. + + - "git cvsserver" can be told to send everything with -kb. + + - "git diff --check" also honors the --color output option. + + - "git name-rev" used to stress the fact that a ref is a tag too + much, by saying something like "v1.2.3^0~22". It now says + "v1.2.3~22" in such a case (it still says "v1.2.3^0" if it does + not talk about an ancestor of the commit that is tagged, which + makes sense). + + - "git rev-list --boundary" now shows boundary markers for the + commits omitted by --max-age and --max-count condition. + + - The configuration mechanism now reads $(prefix)/etc/gitconfig. + + - "git apply --verbose" shows what preimage lines were wanted + when it couldn't find them. + + - "git status" in a read-only repository got a bit saner. + + - "git fetch" (hence "git clone" and "git pull") are less + noisy when the output does not go to tty. + + - "git fetch" between repositories with many refs were slow + even when there are not many changes that needed + transferring. This has been sped up by partially rewriting + the heaviest parts in C. + + - "git mailinfo" which splits an e-mail into a patch and the + meta-information was rewritten, thanks to Don Zickus. It + handles nested multipart better. The command was broken for + a brief period on 'master' branch since 1.5.0 but the + breakage is fixed now. + + - send-email learned configurable bcc and chain-reply-to. + + - "git remote show $remote" also talks about branches that + would be pushed if you run "git push remote". + + - Using objects from packs is now seriously optimized by clever + use of a cache. This should be most noticeable in git-log + family of commands that involve reading many tree objects. + In addition, traversing revisions while filtering changes + with pathspecs is made faster by terminating the comparison + between the trees as early as possible. + + +* Hooks + + - The part to send out notification e-mails was removed from + the sample update hook, as it was not an appropriate place + to do so. The proper place to do this is the new post-receive + hook. An example hook has been added to contrib/hooks/. + + +* Others + + - git-revert, git-gc and git-cherry-pick are now built-ins. + +Fixes since v1.5.0 +------------------ + +These are all in v1.5.0.x series. + +* Documentation updates + + - Clarifications and corrections to 1.5.0 release notes. + + - The main documentation did not link to git-remote documentation. + + - Clarified introductory text of git-rebase documentation. + + - Converted remaining mentions of update-index on Porcelain + documents to git-add/git-rm. + + - Some i18n.* configuration variables were incorrectly + described as core.*; fixed. + + - added and clarified core.bare, core.legacyheaders configurations. + + - updated "git-clone --depth" documentation. + + - user-manual updates. + + - Options to 'git remote add' were described insufficiently. + + - Configuration format.suffix was not documented. + + - Other formatting and spelling fixes. + + - user-manual has better cross references. + + - gitweb installation/deployment procedure is now documented. + + +* Bugfixes + + - git-upload-pack closes unused pipe ends; earlier this caused + many zombies to hang around. + + - git-rerere was recording the contents of earlier hunks + duplicated in later hunks. This prevented resolving the same + conflict when performing the same merge the other way around. + + - git-add and git-update-index on a filesystem on which + executable bits are unreliable incorrectly reused st_mode + bits even when the path changed between symlink and regular + file. + + - git-daemon marks the listening sockets with FD_CLOEXEC so + that it won't be leaked into the children. + + - segfault from git-blame when the mandatory pathname + parameter was missing was fixed; usage() message is given + instead. + + - git-rev-list did not read $GIT_DIR/config file, which means + that did not honor i18n.logoutputencoding correctly. + + - Automated merge conflict handling when changes to symbolic + links conflicted were completely broken. The merge-resolve + strategy created a regular file with conflict markers in it + in place of the symbolic link. The default strategy, + merge-recursive was even more broken. It removed the path + that was pointed at by the symbolic link. Both of these + problems have been fixed. + + - 'git diff maint master next' did not correctly give combined + diff across three trees. + + - 'git fast-import' portability fix for Solaris. + + - 'git show-ref --verify' without arguments did not error out + but segfaulted. + + - 'git diff :tracked-file `pwd`/an-untracked-file' gave an extra + slashes after a/ and b/. + + - 'git format-patch' produced too long filenames if the commit + message had too long line at the beginning. + + - Running 'make all' and then without changing anything + running 'make install' still rebuilt some files. This + was inconvenient when building as yourself and then + installing as root (especially problematic when the source + directory is on NFS and root is mapped to nobody). + + - 'git-rerere' failed to deal with two unconflicted paths that + sorted next to each other. + + - 'git-rerere' attempted to open(2) a symlink and failed if + there was a conflict. Since a conflicting change to a + symlink would not benefit from rerere anyway, the command + now ignores conflicting changes to symlinks. + + - 'git-repack' did not like to pass more than 64 arguments + internally to underlying 'rev-list' logic, which made it + impossible to repack after accumulating many (small) packs + in the repository. + + - 'git-diff' to review the combined diff during a conflicted + merge were not reading the working tree version correctly + when changes to a symbolic link conflicted. It should have + read the data using readlink(2) but read from the regular + file the symbolic link pointed at. + + - 'git-remote' did not like period in a remote's name. + + - 'git.el' honors the commit coding system from the configuration. + + - 'blameview' in contrib/ correctly digs deeper when a line is + clicked. + + - 'http-push' correctly makes sure the remote side has leading + path. Earlier it started in the middle of the path, and + incorrectly. + + - 'git-merge' did not exit with non-zero status when the + working tree was dirty and cannot fast forward. It does + now. + + - 'cvsexportcommit' does not lose yet-to-be-used message file. + + - int-vs-size_t typefix when running combined diff on files + over 2GB long. + + - 'git apply --whitespace=strip' should not touch unmodified + lines. + + - 'git-mailinfo' choke when a logical header line was too long. + + - 'git show A..B' did not error out. Negative ref ("not A" in + this example) does not make sense for the purpose of the + command, so now it errors out. + + - 'git fmt-merge-msg --file' without file parameter did not + correctly error out. + + - 'git archimport' barfed upon encountering a commit without + summary. + + - 'git index-pack' did not protect itself from getting a short + read out of pread(2). + + - 'git http-push' had a few buffer overruns. + + - Build dependency fixes to rebuild fetch.o when other headers + change. + + - git.el does not add duplicate sign-off lines. + + - git-commit shows the full stat of the resulting commit, not + just about the files in the current directory, when run from + a subdirectory. + + - "git-checkout -m '@{8 hours ago}'" had a funny failure from + eval; fixed. + + - git-merge (hence git-pull) did not refuse fast-forwarding + when the working tree had local changes that would have + conflicted with it. + + - a handful small fixes to gitweb. + + - build procedure for user-manual is fixed not to require locally + installed stylesheets. + + - "git commit $paths" on paths whose earlier contents were + already updated in the index were failing out. + + +* Tweaks + + - sliding mmap() inefficiently mmaped the same region of a + packfile with an access pattern that used objects in the + reverse order. This has been made more efficient. diff --git a/Documentation/RelNotes/1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.txt new file mode 100644 index 0000000..d41984d --- /dev/null +++ b/Documentation/RelNotes/1.5.2.1.txt @@ -0,0 +1,47 @@ +GIT v1.5.2.1 Release Notes +========================== + +Fixes since v1.5.2 +------------------ + +* Bugfixes + + - Temporary files that are used when invoking external diff + programs did not tolerate a long TMPDIR. + + - git-daemon did not notice when it could not write into its + pid file. + + - git-status did not honor core.excludesFile configuration like + git-add did. + + - git-annotate did not work from a subdirectory while + git-blame did. + + - git-cvsserver should have disabled access to a repository + with "gitcvs.pserver.enabled = false" set even when + "gitcvs.enabled = true" was set at the same time. It + didn't. + + - git-cvsimport did not work correctly in a repository with + its branch heads were packed with pack-refs. + + - ident unexpansion to squash "$Id: xxx $" that is in the + repository copy removed incorrect number of bytes. + + - git-svn misbehaved when the subversion repository did not + provide MD5 checksums for files. + + - git rebase (and git am) misbehaved on commits that have '\n' + (literally backslash and en, not a linefeed) in the title. + + - code to decode base85 used in binary patches had one error + return codepath wrong. + + - RFC2047 Q encoding output by git-format-patch used '_' for a + space, which is not understood by some programs. It uses =20 + which is safer. + + - git-fastimport --import-marks was broken; fixed. + + - A lot of documentation updates, clarifications and fixes. diff --git a/Documentation/RelNotes/1.5.2.2.txt b/Documentation/RelNotes/1.5.2.2.txt new file mode 100644 index 0000000..7bfa341 --- /dev/null +++ b/Documentation/RelNotes/1.5.2.2.txt @@ -0,0 +1,61 @@ +GIT v1.5.2.2 Release Notes +========================== + +Fixes since v1.5.2.1 +-------------------- + +* Usability fix + + - git-gui is shipped with its updated blame interface. It is + rumored that the older one was not just unusable but was + active health hazard, but this one is actually pretty. + Please see for yourself. + +* Bugfixes + + - "git checkout fubar" was utterly confused when there is a + branch fubar and a tag fubar at the same time. It correctly + checks out the branch fubar now. + + - "git clone /path/foo" to clone a local /path/foo.git + repository left an incorrect configuration. + + - "git send-email" correctly unquotes RFC 2047 quoted names in + the patch-email before using their values. + + - We did not accept number of seconds since epoch older than + year 2000 as a valid timestamp. We now interpret positive + integers more than 8 digits as such, which allows us to + express timestamps more recent than March 1973. + + - git-cvsimport did not work when you have GIT_DIR to point + your repository at a nonstandard location. + + - Some systems (notably, Solaris) lack hstrerror() to make + h_errno human readable; prepare a replacement + implementation. + + - .gitignore file listed git-core.spec but what we generate is + git.spec, and nobody noticed for a long time. + + - "git-merge-recursive" does not try to run file level merge + on binary files. + + - "git-branch --track" did not create tracking configuration + correctly when the branch name had slash in it. + + - The email address of the user specified with user.email + configuration was overridden by EMAIL environment variable. + + - The tree parser did not warn about tree entries with + nonsense file modes, and assumed they must be blobs. + + - "git log -z" without any other request to generate diff still + invoked the diff machinery, wasting cycles. + +* Documentation + + - Many updates to fix stale or missing documentation. + + - Although our documentation was primarily meant to be formatted + with AsciiDoc7, formatting with AsciiDoc8 is supported better. diff --git a/Documentation/RelNotes/1.5.2.3.txt b/Documentation/RelNotes/1.5.2.3.txt new file mode 100644 index 0000000..addb229 --- /dev/null +++ b/Documentation/RelNotes/1.5.2.3.txt @@ -0,0 +1,27 @@ +GIT v1.5.2.3 Release Notes +========================== + +Fixes since v1.5.2.2 +-------------------- + + * Bugfixes + + - Version 2 pack index format was introduced in version 1.5.2 + to support pack files that has offset that cannot be + represented in 32-bit. The runtime code to validate such + an index mishandled such an index for an empty pack. + + - Commit walkers (most notably, fetch over http protocol) + tried to traverse commit objects contained in trees (aka + subproject); they shouldn't. + + - A build option NO_R_TO_GCC_LINKER was not explained in Makefile + comment correctly. + + * Documentation Fixes and Updates + + - git-config --regexp was not documented properly. + + - git-repack -a was not documented properly. + + - git-remote -n was not documented properly. diff --git a/Documentation/RelNotes/1.5.2.4.txt b/Documentation/RelNotes/1.5.2.4.txt new file mode 100644 index 0000000..75cff47 --- /dev/null +++ b/Documentation/RelNotes/1.5.2.4.txt @@ -0,0 +1,28 @@ +GIT v1.5.2.4 Release Notes +========================== + +Fixes since v1.5.2.3 +-------------------- + + * Bugfixes + + - "git-gui" bugfixes, including a handful fixes to run it + better on Cygwin/MSYS. + + - "git checkout" failed to switch back and forth between + branches, one of which has "frotz -> xyzzy" symlink and + file "xyzzy/filfre", while the other one has a file + "frotz/filfre". + + - "git prune" used to segfault upon seeing a commit that is + referred to by a tree object (aka "subproject"). + + - "git diff --name-status --no-index" mishandled an added file. + + - "git apply --reverse --whitespace=warn" still complained + about whitespaces that a forward application would have + introduced. + + * Documentation Fixes and Updates + + - A handful documentation updates. diff --git a/Documentation/RelNotes/1.5.2.5.txt b/Documentation/RelNotes/1.5.2.5.txt new file mode 100644 index 0000000..e8281c7 --- /dev/null +++ b/Documentation/RelNotes/1.5.2.5.txt @@ -0,0 +1,30 @@ +GIT v1.5.2.5 Release Notes +========================== + +Fixes since v1.5.2.4 +-------------------- + + * Bugfixes + + - "git add -u" had a serious data corruption problem in one + special case (when the changes to a subdirectory's files + consist only deletion of files). + + - "git add -u " did not work from a subdirectory. + + - "git apply" left an empty directory after all its files are + renamed away. + + - "git $anycmd foo/bar", when there is a file 'foo' in the + working tree, complained that "git $anycmd foo/bar --" form + should be used to disambiguate between revs and files, + which was completely bogus. + + - "git checkout-index" and other commands that checks out + files to the work tree tried unlink(2) on directories, + which is a sane thing to do on sane systems, but not on + Solaris when you are root. + + * Documentation Fixes and Updates + + - A handful documentation fixes. diff --git a/Documentation/RelNotes/1.5.2.txt b/Documentation/RelNotes/1.5.2.txt new file mode 100644 index 0000000..e8328d0 --- /dev/null +++ b/Documentation/RelNotes/1.5.2.txt @@ -0,0 +1,197 @@ +GIT v1.5.2 Release Notes +======================== + +Updates since v1.5.1 +-------------------- + +* Plumbing level superproject support. + + You can include a subdirectory that has an independent git + repository in your index and tree objects of your project + ("superproject"). This plumbing (i.e. "core") level + superproject support explicitly excludes recursive behaviour. + + The "subproject" entries in the index and trees of a superproject + are incompatible with older versions of git. Experimenting with + the plumbing level support is encouraged, but be warned that + unless everybody in your project updates to this release or + later, using this feature would make your project + inaccessible by people with older versions of git. + +* Plumbing level gitattributes support. + + The gitattributes mechanism allows you to add 'attributes' to + paths in your project, and affect the way certain git + operations work. Currently you can influence if a path is + considered a binary or text (the former would be treated by + 'git diff' not to produce textual output; the latter can go + through the line endings conversion process in repositories + with core.autocrlf set), expand and unexpand '$Id$' keyword + with blob object name, specify a custom 3-way merge driver, + and specify a custom diff driver. You can also apply + arbitrary filter to contents on check-in/check-out codepath + but this feature is an extremely sharp-edged razor and needs + to be handled with caution (do not use it unless you + understand the earlier mailing list discussion on keyword + expansion). These conversions apply when checking files in + or out, and exporting via git-archive. + +* The packfile format now optionally supports 64-bit index. + + This release supports the "version 2" format of the .idx + file. This is automatically enabled when a huge packfile + needs more than 32-bit to express offsets of objects in the + pack. + +* Comes with an updated git-gui 0.7.1 + +* Updated gitweb: + + - can show combined diff for merges; + - uses font size of user's preference, not hardcoded in pixels; + - can now 'grep'; + +* New commands and options. + + - "git bisect start" can optionally take a single bad commit and + zero or more good commits on the command line. + + - "git shortlog" can optionally be told to wrap its output. + + - "subtree" merge strategy allows another project to be merged in as + your subdirectory. + + - "git format-patch" learned a new --subject-prefix= + option, to override the built-in "[PATCH]". + + - "git add -u" is a quick way to do the first stage of "git + commit -a" (i.e. update the index to match the working + tree); it obviously does not make a commit. + + - "git clean" honors a new configuration, "clean.requireforce". When + set to true, this makes "git clean" a no-op, preventing you + from losing files by typing "git clean" when you meant to + say "make clean". You can still say "git clean -f" to + override this. + + - "git log" family of commands learned --date={local,relative,default} + option. --date=relative is synonym to the --relative-date. + --date=local gives the timestamp in local timezone. + +* Updated behavior of existing commands. + + - When $GIT_COMMITTER_EMAIL or $GIT_AUTHOR_EMAIL is not set + but $EMAIL is set, the latter is used as a substitute. + + - "git diff --stat" shows size of preimage and postimage blobs + for binary contents. Earlier it only said "Bin". + + - "git lost-found" shows stuff that are unreachable except + from reflogs. + + - "git checkout branch^0" now detaches HEAD at the tip commit + on the named branch, instead of just switching to the + branch (use "git checkout branch" to switch to the branch, + as before). + + - "git bisect next" can be used after giving only a bad commit + without giving a good one (this starts bisection half-way to + the root commit). We used to refuse to operate without a + good and a bad commit. + + - "git push", when pushing into more than one repository, does + not stop at the first error. + + - "git archive" does not insist you to give --format parameter + anymore; it defaults to "tar". + + - "git cvsserver" can use backends other than sqlite. + + - "gitview" (in contrib/ section) learned to better support + "git-annotate". + + - "git diff $commit1:$path2 $commit2:$path2" can now report + mode changes between the two blobs. + + - Local "git fetch" from a repository whose object store is + one of the alternates (e.g. fetching from the origin in a + repository created with "git clone -l -s") avoids + downloading objects unnecessarily. + + - "git blame" uses .mailmap to canonicalize the author name + just like "git shortlog" does. + + - "git pack-objects" pays attention to pack.depth + configuration variable. + + - "git cherry-pick" and "git revert" does not use .msg file in + the working tree to prepare commit message; instead it uses + $GIT_DIR/MERGE_MSG as other commands do. + +* Builds + + - git-p4import has never been installed; now there is an + installation option to do so. + + - gitk and git-gui can be configured out. + + - Generated documentation pages automatically get version + information from GIT_VERSION. + + - Parallel build with "make -j" descending into subdirectory + was fixed. + +* Performance Tweaks + + - Optimized "git-rev-list --bisect" (hence "git-bisect"). + + - Optimized "git-add $path" in a large directory, most of + whose contents are ignored. + + - Optimized "git-diff-tree" for reduced memory footprint. + + - The recursive merge strategy updated a worktree file that + was changed identically in two branches, when one of them + renamed it. We do not do that when there is no rename, so + match that behaviour. This avoids excessive rebuilds. + + - The default pack depth has been increased to 50, as the + recent addition of delta_base_cache makes deeper delta chains + much less expensive to access. Depending on the project, it was + reported that this reduces the resulting pack file by 10% + or so. + + +Fixes since v1.5.1 +------------------ + +All of the fixes in v1.5.1 maintenance series are included in +this release, unless otherwise noted. + +* Bugfixes + + - Switching branches with "git checkout" refused to work when + a path changes from a file to a directory between the + current branch and the new branch, in order not to lose + possible local changes in the directory that is being turned + into a file with the switch. We now allow such a branch + switch after making sure that there is no locally modified + file nor un-ignored file in the directory. This has not + been backported to 1.5.1.x series, as it is rather an + intrusive change. + + - Merging branches that have a file in one and a directory in + another at the same path used to get quite confused. We + handle such a case a bit more carefully, even though that is + still left as a conflict for the user to sort out. This + will not be backported to 1.5.1.x series, as it is rather an + intrusive change. + + - git-fetch had trouble with a remote with insanely large number + of refs. + + - "git clean -d -X" now does not remove non-excluded directories. + + - rebasing (without -m) a series that changes a symlink to a directory + in the middle of a path confused git-apply greatly and refused to + operate. diff --git a/Documentation/RelNotes/1.5.3.1.txt b/Documentation/RelNotes/1.5.3.1.txt new file mode 100644 index 0000000..7ff546c --- /dev/null +++ b/Documentation/RelNotes/1.5.3.1.txt @@ -0,0 +1,10 @@ +GIT v1.5.3.1 Release Notes +========================== + +Fixes since v1.5.3 +------------------ + +This is solely to fix the generated RPM's dependencies. We used +to have git-p4 package but we do not anymore. As suggested on +the mailing list, this release makes git-core "Obsolete" git-p4, +so that yum update would not complain. diff --git a/Documentation/RelNotes/1.5.3.2.txt b/Documentation/RelNotes/1.5.3.2.txt new file mode 100644 index 0000000..4bbde3c --- /dev/null +++ b/Documentation/RelNotes/1.5.3.2.txt @@ -0,0 +1,58 @@ +GIT v1.5.3.2 Release Notes +========================== + +Fixes since v1.5.3.1 +-------------------- + + * git-push sent thin packs by default, which was not good for + the public distribution server (no point in saving transfer + while pushing; no point in making the resulting pack less + optimum). + + * git-svn sometimes terminated with "Malformed network data" when + talking over svn:// protocol. + + * git-send-email re-issued the same message-id about 10% of the + time if you fired off 30 messages within a single second. + + * git-stash was not terminating the log message of commits it + internally creates with LF. + + * git-apply failed to check the size of the patch hunk when its + beginning part matched the remainder of the preimage exactly, + even though the preimage recorded in the hunk was much larger + (therefore the patch should not have applied), leading to a + segfault. + + * "git rm foo && git commit foo" complained that 'foo' needs to + be added first, instead of committing the removal, which was a + nonsense. + + * git grep -c said "/dev/null: 0". + + * git-add -u failed to recognize a blob whose type changed + between the index and the work tree. + + * The limit to rename detection has been tightened a lot to + reduce performance problems with a huge change. + + * cvsimport and svnimport barfed when the input tried to move + a tag. + + * "git apply -pN" did not chop the right number of directories. + + * "git svnimport" did not like SVN tags with funny characters in them. + + * git-gui 0.8.3, with assorted fixes, including: + + - font-chooser on X11 was unusable with large number of fonts; + - a diff that contained a deleted symlink made it barf; + - an untracked symbolic link to a directory made it fart; + - a file with % in its name made it vomit; + + +Documentation updates +--------------------- + +User manual has been somewhat restructured. I think the new +organization is much easier to read. diff --git a/Documentation/RelNotes/1.5.3.3.txt b/Documentation/RelNotes/1.5.3.3.txt new file mode 100644 index 0000000..d213846 --- /dev/null +++ b/Documentation/RelNotes/1.5.3.3.txt @@ -0,0 +1,31 @@ +GIT v1.5.3.3 Release Notes +========================== + +Fixes since v1.5.3.2 +-------------------- + + * git-quiltimport did not like it when a patch described in the + series file does not exist. + + * p4 importer missed executable bit in some cases. + + * The default shell on some FreeBSD did not execute the + argument parsing code correctly and made git unusable. + + * git-svn incorrectly spawned pager even when the user + explicitly asked not to. + + * sample post-receive hook overquoted the envelope sender + value. + + * git-am got confused when the patch contained a change that is + only about type and not contents. + + * git-mergetool did not show our and their version of the + conflicted file when started from a subdirectory of the + project. + + * git-mergetool did not pass correct options when invoking diff3. + + * git-log sometimes invoked underlying "diff" machinery + unnecessarily. diff --git a/Documentation/RelNotes/1.5.3.4.txt b/Documentation/RelNotes/1.5.3.4.txt new file mode 100644 index 0000000..b04b3a4 --- /dev/null +++ b/Documentation/RelNotes/1.5.3.4.txt @@ -0,0 +1,35 @@ +GIT v1.5.3.4 Release Notes +========================== + +Fixes since v1.5.3.3 +-------------------- + + * Change to "git-ls-files" in v1.5.3.3 that was introduced to support + partial commit of removal better had a segfaulting bug, which was + diagnosed and fixed by Keith and Carl. + + * Performance improvements for rename detection has been backported + from the 'master' branch. + + * "git-for-each-ref --format='%(numparent)'" was not working + correctly at all, and --format='%(parent)' was not working for + merge commits. + + * Sample "post-receive-hook" incorrectly sent out push + notification e-mails marked as "From: " the committer of the + commit that happened to be at the tip of the branch that was + pushed, not from the person who pushed. + + * "git-remote" did not exit non-zero status upon error. + + * "git-add -i" did not respond very well to EOF from tty nor + bogus input. + + * "git-rebase -i" squash subcommand incorrectly made the + author of later commit the author of resulting commit, + instead of taking from the first one in the squashed series. + + * "git-stash apply --index" was not documented. + + * autoconfiguration learned that "ar" command is found as "gas" on + some systems. diff --git a/Documentation/RelNotes/1.5.3.5.txt b/Documentation/RelNotes/1.5.3.5.txt new file mode 100644 index 0000000..7ff1d5d --- /dev/null +++ b/Documentation/RelNotes/1.5.3.5.txt @@ -0,0 +1,94 @@ +GIT v1.5.3.5 Release Notes +========================== + +Fixes since v1.5.3.4 +-------------------- + + * Comes with git-gui 0.8.4. + + * "git-config" silently ignored options after --list; now it will + error out with a usage message. + + * "git-config --file" failed if the argument used a relative path + as it changed directories before opening the file. + + * "git-config --file" now displays a proper error message if it + cannot read the file specified on the command line. + + * "git-config", "git-diff", "git-apply" failed if run from a + subdirectory with relative GIT_DIR and GIT_WORK_TREE set. + + * "git-blame" crashed if run during a merge conflict. + + * "git-add -i" did not handle single line hunks correctly. + + * "git-rebase -i" and "git-stash apply" failed if external diff + drivers were used for one or more files in a commit. They now + avoid calling the external diff drivers. + + * "git-log --follow" did not work unless diff generation (e.g. -p) + was also requested. + + * "git-log --follow -B" did not work at all. Fixed. + + * "git-log -M -B" did not correctly handle cases of very large files + being renamed and replaced by very small files in the same commit. + + * "git-log" printed extra newlines between commits when a diff + was generated internally (e.g. -S or --follow) but not displayed. + + * "git-push" error message is more helpful when pushing to a + repository with no matching refs and none specified. + + * "git-push" now respects + (force push) on wildcard refspecs, + matching the behavior of git-fetch. + + * "git-filter-branch" now updates the working directory when it + has finished filtering the current branch. + + * "git-instaweb" no longer fails on Mac OS X. + + * "git-cvsexportcommit" didn't always create new parent directories + before trying to create new child directories. Fixed. + + * "git-fetch" printed a scary (but bogus) error message while + fetching a tag that pointed to a tree or blob. The error did + not impact correctness, only user perception. The bogus error + is no longer printed. + + * "git-ls-files --ignored" did not properly descend into non-ignored + directories that themselves contained ignored files if d_type + was not supported by the filesystem. This bug impacted systems + such as AFS. Fixed. + + * Git segfaulted when reading an invalid .gitattributes file. Fixed. + + * post-receive-email example hook was fixed for non-fast-forward + updates. + + * Documentation updates for supported (but previously undocumented) + options of "git-archive" and "git-reflog". + + * "make clean" no longer deletes the configure script that ships + with the git tarball, making multiple architecture builds easier. + + * "git-remote show origin" spewed a warning message from Perl + when no remote is defined for the current branch via + branch..remote configuration settings. + + * Building with NO_PERL_MAKEMAKER excessively rebuilt contents + of perl/ subdirectory by rewriting perl.mak. + + * http.sslVerify configuration settings were not used in scripted + Porcelains. + + * "git-add" leaked a bit of memory while scanning for files to add. + + * A few workarounds to squelch false warnings from recent gcc have + been added. + + * "git-send-pack $remote frotz" segfaulted when there is nothing + named 'frotz' on the local end. + + * "git-rebase --interactive" did not handle its "--strategy" option + properly. diff --git a/Documentation/RelNotes/1.5.3.6.txt b/Documentation/RelNotes/1.5.3.6.txt new file mode 100644 index 0000000..069a2b2 --- /dev/null +++ b/Documentation/RelNotes/1.5.3.6.txt @@ -0,0 +1,48 @@ +GIT v1.5.3.6 Release Notes +========================== + +Fixes since v1.5.3.5 +-------------------- + + * git-cvsexportcommit handles root commits better. + + * git-svn dcommit used to clobber when sending a series of + patches. + + * git-svn dcommit failed after attempting to rebase when + started with a dirty index; now it stops upfront. + + * git-grep sometimes refused to work when your index was + unmerged. + + * "git-grep -A1 -B2" acted as if it was told to run "git -A1 -B21". + + * git-hash-object did not honor configuration variables, such as + core.compression. + + * git-index-pack choked on a huge pack on 32-bit machines, even when + large file offsets are supported. + + * atom feeds from git-web said "10" for the month of November. + + * a memory leak in commit walker was plugged. + + * When git-send-email inserted the original author's From: + address in body, it did not mark the message with + Content-type: as needed. + + * git-revert and git-cherry-pick incorrectly refused to start + when the work tree was dirty. + + * git-clean did not honor core.excludesfile configuration. + + * git-add mishandled ".gitignore" files when applying them to + subdirectories. + + * While importing a too branchy history, git-fastimport did not + honor delta depth limit properly. + + * Support for zlib implementations that lack ZLIB_VERNUM and definition + of deflateBound() has been added. + + * Quite a lot of documentation clarifications. diff --git a/Documentation/RelNotes/1.5.3.7.txt b/Documentation/RelNotes/1.5.3.7.txt new file mode 100644 index 0000000..2f69061 --- /dev/null +++ b/Documentation/RelNotes/1.5.3.7.txt @@ -0,0 +1,45 @@ +GIT v1.5.3.7 Release Notes +========================== + +Fixes since v1.5.3.6 +-------------------- + + * git-send-email added 8-bit contents to the payload without + marking it as 8-bit in a CTE header. + + * "git-bundle create a.bndl HEAD" dereferenced the symref and + did not record the ref as 'HEAD'; this prevented a bundle + from being used as a normal source of git-clone. + + * The code to reject nonsense command line of the form + "git-commit -a paths..." and "git-commit --interactive + paths..." were broken. + + * Adding a signature that is not ASCII-only to an original + commit that is ASCII-only would make the result non-ASCII. + "git-format-patch -s" did not mark such a message correctly + with MIME encoding header. + + * git-add sometimes did not mark the resulting index entry + stat-clean. This affected only cases when adding the + contents with the same length as the previously staged + contents, and the previous staging made the index entry + "racily clean". + + * git-commit did not honor GIT_INDEX_FILE the user had in the + environment. + + * When checking out a revision, git-checkout did not report where the + updated HEAD is if you happened to have a file called HEAD in the + work tree. + + * "git-rev-list --objects" mishandled a tree that points at a + submodule. + + * "git cvsimport" was not ready for packed refs that "git gc" can + produce and gave incorrect results. + + * Many scripted Porcelains were confused when you happened to have a + file called "HEAD" in your work tree. + +Also it contains updates to the user manual and documentation. diff --git a/Documentation/RelNotes/1.5.3.8.txt b/Documentation/RelNotes/1.5.3.8.txt new file mode 100644 index 0000000..0e3ff58 --- /dev/null +++ b/Documentation/RelNotes/1.5.3.8.txt @@ -0,0 +1,25 @@ +GIT v1.5.3.8 Release Notes +========================== + +Fixes since v1.5.3.7 +-------------------- + + * Some documentation used "email.com" as an example domain. + + * git-svn fix to handle funky branch and project names going over + http/https correctly. + + * git-svn fix to tone down a needlessly alarming warning message. + + * git-clone did not correctly report errors while fetching over http. + + * git-send-email added redundant Message-Id: header to the outgoing + e-mail when the patch text already had one. + + * a read-beyond-end-of-buffer bug in configuration file updater was fixed. + + * git-grep used to show the same hit repeatedly for unmerged paths. + + * After amending the patch title in "git-am -i", the command did not + report the patch it applied with the updated title. + diff --git a/Documentation/RelNotes/1.5.3.txt b/Documentation/RelNotes/1.5.3.txt new file mode 100644 index 0000000..0668d3c --- /dev/null +++ b/Documentation/RelNotes/1.5.3.txt @@ -0,0 +1,366 @@ +GIT v1.5.3 Release Notes +======================== + +Updates since v1.5.2 +-------------------- + +* The commit walkers other than http are officially deprecated, + but still supported for now. + +* The submodule support has Porcelain layer. + + Note that the current submodule support is minimal and this is + deliberately so. A design decision we made is that operations + at the supermodule level do not recurse into submodules by + default. The expectation is that later we would add a + mechanism to tell git which submodules the user is interested + in, and this information might be used to determine the + recursive behaviour of certain commands (e.g. "git checkout" + and "git diff"), but currently we haven't agreed on what that + mechanism should look like. Therefore, if you use submodules, + you would probably need "git submodule update" on the + submodules you care about after running a "git checkout" at + the supermodule level. + +* There are a handful pack-objects changes to help you cope better + with repositories with pathologically large blobs in them. + +* For people who need to import from Perforce, a front-end for + fast-import is in contrib/fast-import/. + +* Comes with git-gui 0.8.2. + +* Comes with updated gitk. + +* New commands and options. + + - "git log --date=" can use more formats: iso8601, rfc2822. + + - The hunk header output from "git diff" family can be customized + with the attributes mechanism. See gitattributes(5) for details. + + - "git stash" allows you to quickly save away your work in + progress and replay it later on an updated state. + + - "git rebase" learned an "interactive" mode that let you + pick and reorder which commits to rebuild. + + - "git fsck" can save its findings in $GIT_DIR/lost-found, without a + separate invocation of "git lost-found" command. The blobs stored by + lost-found are stored in plain format to allow you to grep in them. + + - $GIT_WORK_TREE environment variable can be used together with + $GIT_DIR to work in a subdirectory of a working tree that is + not located at "$GIT_DIR/..". + + - Giving "--file=" option to "git config" is the same as + running the command with GIT_CONFIG= environment. + + - "git log" learned a new option "--follow", to follow + renaming history of a single file. + + - "git filter-branch" lets you rewrite the revision history of + specified branches. You can specify a number of filters to + modify the commits, files and trees. + + - "git cvsserver" learned new options (--base-path, --export-all, + --strict-paths) inspired by "git daemon". + + - "git daemon --base-path-relaxed" can help migrating a repository URL + that did not use to use --base-path to use --base-path. + + - "git commit" can use "-t templatefile" option and commit.template + configuration variable to prime the commit message given to you in the + editor. + + - "git submodule" command helps you manage the projects from + the superproject that contain them. + + - In addition to core.compression configuration option, + core.loosecompression and pack.compression options can + independently tweak zlib compression levels used for loose + and packed objects. + + - "git ls-tree -l" shows size of blobs pointed at by the + tree entries, similar to "/bin/ls -l". + + - "git rev-list" learned --regexp-ignore-case and + --extended-regexp options to tweak its matching logic used + for --grep filtering. + + - "git describe --contains" is a handier way to call more + obscure command "git name-rev --tags". + + - "git gc --aggressive" tells the command to spend more cycles + to optimize the repository harder. + + - "git repack" learned a "window-memory" limit which + dynamically reduces the window size to stay within the + specified memory usage. + + - "git repack" can be told to split resulting packs to avoid + exceeding limit specified with "--max-pack-size". + + - "git fsck" gained --verbose option. This is really really + verbose but it might help you identify exact commit that is + corrupt in your repository. + + - "git format-patch" learned --numbered-files option. This + may be useful for MH users. + + - "git format-patch" learned format.subjectprefix configuration + variable, which serves the same purpose as "--subject-prefix" + option. + + - "git tag -n -l" shows tag annotations while listing tags. + + - "git cvsimport" can optionally use the separate-remote layout. + + - "git blame" can be told to see through commits that change + whitespaces and indentation levels with "-w" option. + + - "git send-email" can be told not to thread the messages when + sending out more than one patches. + + - "git send-email" can also be told how to find whom to cc the + message to for each message via --cc-cmd. + + - "git config" learned NUL terminated output format via -z to + help scripts. + + - "git add" learned "--refresh ..." option to selectively refresh + the cached stat information. + + - "git init -q" makes the command quieter. + + - "git -p command" now has a cousin of opposite sex, "git --no-pager + command". + +* Updated behavior of existing commands. + + - "gitweb" can offer multiple snapshot formats. + + ***NOTE*** Unfortunately, this changes the format of the + $feature{snapshot}{default} entry in the per-site + configuration file 'gitweb_config.perl'. It used to be a + three-element tuple that describe a single format; with the + new configuration item format, you only have to say the name + of the format ('tgz', 'tbz2' or 'zip'). Please update the + your configuration file accordingly. + + - "git clone" uses -l (hardlink files under .git) by default when + cloning locally. + + - URL used for "git clone" and friends can specify nonstandard SSH port + by using ssh://host:port/path/to/repo syntax. + + - "git bundle create" can now create a bundle without negative refs, + i.e. "everything since the beginning up to certain points". + + - "git diff" (but not the plumbing level "git diff-tree") now + recursively descends into trees by default. + + - "git diff" does not show differences that come only from + stat-dirtiness in the form of "diff --git" header anymore. + It runs "update-index --refresh" silently as needed. + + - "git tag -l" used to match tags by globbing its parameter as if it + has wildcard '*' on both ends, which made "git tag -l gui" to match + tag 'gitgui-0.7.0'; this was very annoying. You now have to add + asterisk on the sides you want to wildcard yourself. + + - The editor to use with many interactive commands can be + overridden with GIT_EDITOR environment variable, or if it + does not exist, with core.editor configuration variable. As + before, if you have neither, environment variables VISUAL + and EDITOR are consulted in this order, and then finally we + fall back on "vi". + + - "git rm --cached" does not complain when removing a newly + added file from the index anymore. + + - Options to "git log" to affect how --grep/--author options look for + given strings now have shorter abbreviations. -i is for ignore case, + and -E is for extended regexp. + + - "git log" learned --log-size to show the number of bytes in + the log message part of the output to help qgit. + + - "git log --name-status" does not require you to give "-r" anymore. + As a general rule, Porcelain commands should recurse when showing + diff. + + - "git format-patch --root A" can be used to format everything + since the beginning up to A. This was supported with + "git format-patch --root A A" for a long time, but was not + properly documented. + + - "git svn dcommit" retains local merge information. + + - "git svnimport" allows an empty string to be specified as the + trunk/ directory. This is necessary to suck data from a SVN + repository that doe not have trunk/ branches/ and tags/ organization + at all. + + - "git config" to set values also honors type flags like --bool + and --int. + + - core.quotepath configuration can be used to make textual git + output to emit most of the characters in the path literally. + + - "git mergetool" chooses its backend more wisely, taking + notice of its environment such as use of X, Gnome/KDE, etc. + + - "gitweb" shows merge commits a lot nicer than before. The + default view uses more compact --cc format, while the UI + allows to choose normal diff with any parent. + + - snapshot files "gitweb" creates from a repository at + $path/$project/.git are more useful. We use $project part + in the filename, which we used to discard. + + - "git cvsimport" creates lightweight tags; there is no + interesting information we can record in an annotated tag, + and the handcrafted ones the old code created was not + properly formed anyway. + + - "git push" pretends that you immediately fetched back from + the remote by updating corresponding remote tracking + branches if you have any. + + - The diffstat given after a merge (or a pull) honors the + color.diff configuration. + + - "git commit --amend" is now compatible with various message source + options such as -m/-C/-c/-F. + + - "git apply --whitespace=strip" removes blank lines added at + the end of the file. + + - "git fetch" over git native protocols with "-v" option shows + connection status, and the IP address of the other end, to + help diagnosing problems. + + - We used to have core.legacyheaders configuration, when + set to false, allowed git to write loose objects in a format + that mimics the format used by objects stored in packs. It + turns out that this was not so useful. Although we will + continue to read objects written in that format, we do not + honor that configuration anymore and create loose objects in + the legacy/traditional format. + + - "--find-copies-harder" option to diff family can now be + spelled as "-C -C" for brevity. + + - "git mailsplit" (hence "git am") can read from Maildir + formatted mailboxes. + + - "git cvsserver" does not barf upon seeing "cvs login" + request. + + - "pack-objects" honors "delta" attribute set in + .gitattributes. It does not attempt to deltify blobs that + come from paths with delta attribute set to false. + + - "new-workdir" script (in contrib) can now be used with a + bare repository. + + - "git mergetool" learned to use gvimdiff. + + - "gitview" (in contrib) has a better blame interface. + + - "git log" and friends did not handle a commit log message + that is larger than 16kB; they do now. + + - "--pretty=oneline" output format for "git log" and friends + deals with "malformed" commit log messages that have more + than one lines in the first paragraph better. We used to + show the first line, cutting the title at mid-sentence; we + concatenate them into a single line and treat the result as + "oneline". + + - "git p4import" has been demoted to contrib status. For + a superior option, checkout the "git p4" front end to + "git fast-import" (also in contrib). The man page and p4 + rpm have been removed as well. + + - "git mailinfo" (hence "am") now tries to see if the message + is in utf-8 first, instead of assuming iso-8859-1, if + incoming e-mail does not say what encoding it is in. + +* Builds + + - old-style function definitions (most notably, a function + without parameter defined with "func()", not "func(void)") + have been eradicated. + + - "git tag" and "git verify-tag" have been rewritten in C. + +* Performance Tweaks + + - "git pack-objects" avoids re-deltification cost by caching + small enough delta results it creates while looking for the + best delta candidates. + + - "git pack-objects" learned a new heuristic to prefer delta + that is shallower in depth over the smallest delta + possible. This improves both overall packfile access + performance and packfile density. + + - diff-delta code that is used for packing has been improved + to work better on big files. + + - when there are more than one pack files in the repository, + the runtime used to try finding an object always from the + newest packfile; it now tries the same packfile as we found + the object requested the last time, which exploits the + locality of references. + + - verifying pack contents done by "git fsck --full" got boost + by carefully choosing the order to verify objects in them. + + - "git read-tree -m" to read into an already populated index + has been optimized vastly. The effect of this can be seen + when switching branches that have differences in only a + handful paths. + + - "git add paths..." and "git commit paths..." has also been + heavily optimized. + +Fixes since v1.5.2 +------------------ + +All of the fixes in v1.5.2 maintenance series are included in +this release, unless otherwise noted. + +* Bugfixes + + - "gitweb" had trouble handling non UTF-8 text with older + Encode.pm Perl module. + + - "git svn" misparsed the data from the commits in the repository when + the user had "color.diff = true" in the configuration. This has been + fixed. + + - There was a case where "git svn dcommit" clobbered changes made on the + SVN side while committing multiple changes. + + - "git-write-tree" had a bad interaction with racy-git avoidance and + gitattributes mechanisms. + + - "git --bare command" overrode existing GIT_DIR setting and always + made it treat the current working directory as GIT_DIR. + + - "git ls-files --error-unmatch" does not complain if you give the + same path pattern twice by mistake. + + - "git init" autodetected core.filemode but not core.symlinks, which + made a new directory created automatically by "git clone" cumbersome + to use on filesystems that require these configurations to be set. + + - "git log" family of commands behaved differently when run as "git + log" (no pathspec) and as "git log --" (again, no pathspec). This + inconsistency was introduced somewhere in v1.3.0 series but now has + been corrected. + + - "git rebase -m" incorrectly displayed commits that were skipped. diff --git a/Documentation/RelNotes/1.5.4.1.txt b/Documentation/RelNotes/1.5.4.1.txt new file mode 100644 index 0000000..d4e44b8 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.1.txt @@ -0,0 +1,17 @@ +GIT v1.5.4.1 Release Notes +========================== + +Fixes since v1.5.4 +------------------ + + * "git-commit -C $tag" used to work but rewrite in C done in + 1.5.4 broke it. + + * An entry in the .gitattributes file that names a pattern in a + subdirectory of the directory it is in did not match + correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should + match "a/b/foo.c" but it didn't). + + * Customized color specification was parsed incorrectly when + numeric color values are used. This was fixed in 1.5.4.1. + diff --git a/Documentation/RelNotes/1.5.4.2.txt b/Documentation/RelNotes/1.5.4.2.txt new file mode 100644 index 0000000..21d0df5 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.2.txt @@ -0,0 +1,43 @@ +GIT v1.5.4.2 Release Notes +========================== + +Fixes since v1.5.4 +------------------ + + * The configuration parser was not prepared to see string + valued variables misspelled as boolean and segfaulted. + + * Temporary files left behind due to interrupted object + transfers were not cleaned up with "git prune". + + * "git config --unset" was confused when the unset variables + were spelled with continuation lines in the config file. + + * The merge message detection in "git cvsimport" did not catch + a message that began with "Merge...". + + * "git status" suggests "git rm --cached" for unstaging the + earlier "git add" before the initial commit. + + * "git status" output was incorrect during a partial commit. + + * "git bisect" refused to start when the HEAD was detached. + + * "git bisect" allowed a wildcard character in the commit + message expanded while writing its log file. + + * Manual pages were not formatted correctly with docbook xsl + 1.72; added a workaround. + + * "git-commit -C $tag" used to work but rewrite in C done in + 1.5.4 broke it. This was fixed in 1.5.4.1. + + * An entry in the .gitattributes file that names a pattern in a + subdirectory of the directory it is in did not match + correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should + match "a/b/foo.c" but it didn't). This was fixed in 1.5.4.1. + + * Customized color specification was parsed incorrectly when + numeric color values are used. This was fixed in 1.5.4.1. + + * http transport misbehaved when linked with curl-gnutls. diff --git a/Documentation/RelNotes/1.5.4.3.txt b/Documentation/RelNotes/1.5.4.3.txt new file mode 100644 index 0000000..b0fc67f --- /dev/null +++ b/Documentation/RelNotes/1.5.4.3.txt @@ -0,0 +1,27 @@ +GIT v1.5.4.3 Release Notes +========================== + +Fixes since v1.5.4.2 +-------------------- + + * RPM spec used to pull in everything with 'git'. This has been + changed so that 'git' package contains just the core parts, + and we now supply 'git-all' metapackage to slurp in everything. + This should match end user's expectation better. + + * When some refs failed to update, git-push reported "failure" + which was unclear if some other refs were updated or all of + them failed atomically (the answer is the former). Reworded + the message to clarify this. + + * "git clone" from a repository whose HEAD was misconfigured + did not set up the remote properly. Now it tries to do + better. + + * Updated git-push documentation to clarify what "matching" + means, in order to reduce user confusion. + + * Updated git-add documentation to clarify "add -u" operates in + the current subdirectory you are in, just like other commands. + + * git-gui updates to work on OSX and Windows better. diff --git a/Documentation/RelNotes/1.5.4.4.txt b/Documentation/RelNotes/1.5.4.4.txt new file mode 100644 index 0000000..323c1a8 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.4.txt @@ -0,0 +1,66 @@ +GIT v1.5.4.4 Release Notes +========================== + +Fixes since v1.5.4.3 +-------------------- + + * Building and installing with an overtight umask such as 077 made + installed templates unreadable by others, while the rest of the install + are done in a way that is friendly to umask 022. + + * "git cvsexportcommit -w $cvsdir" misbehaved when GIT_DIR is set to a + relative directory. + + * "git http-push" had an invalid memory access that could lead it to + segfault. + + * When "git rebase -i" gave control back to the user for a commit that is + marked to be edited, it just said "modify it with commit --amend", + without saying what to do to continue after modifying it. Give an + explicit instruction to run "rebase --continue" to be more helpful. + + * "git send-email" in 1.5.4.3 issued a bogus empty In-Reply-To: header. + + * "git bisect" showed mysterious "won't bisect on seeked tree" error message. + This was leftover from Cogito days to prevent "bisect" starting from a + cg-seeked state. We still keep the Cogito safety, but running "git bisect + start" when another bisect was in effect will clean up and start over. + + * "git push" with an explicit PATH to receive-pack did not quite work if + receive-pack was not on usual PATH. We earlier fixed the same issue + with "git fetch" and upload-pack, but somehow forgot to do so in the + other direction. + + * git-gui's info dialog was not displayed correctly when the user tries + to commit nothing (i.e. without staging anything). + + * "git revert" did not properly fail when attempting to run with a + dirty index. + + * "git merge --no-commit --no-ff " incorrectly made commits. + + * "git merge --squash --no-ff ", which is a nonsense combination + of options, was not rejected. + + * "git ls-remote" and "git remote show" against an empty repository + failed, instead of just giving an empty result (regression). + + * "git fast-import" did not handle a renamed path whose name needs to be + quoted, due to a bug in unquote_c_style() function. + + * "git cvsexportcommit" was confused when multiple files with the same + basename needed to be pushed out in the same commit. + + * "git daemon" did not send early errors to syslog. + + * "git log --merge" did not work well with --left-right option. + + * "git svn" prompted for client cert password every time it accessed the + server. + + * The reset command in "git fast-import" data stream was documented to + end with an optional LF, but it actually required one. + + * "git svn dcommit/rebase" did not honor --rewrite-root option. + +Also included are a handful documentation updates. diff --git a/Documentation/RelNotes/1.5.4.5.txt b/Documentation/RelNotes/1.5.4.5.txt new file mode 100644 index 0000000..bbd130e --- /dev/null +++ b/Documentation/RelNotes/1.5.4.5.txt @@ -0,0 +1,56 @@ +GIT v1.5.4.5 Release Notes +========================== + +Fixes since v1.5.4.4 +-------------------- + + * "git fetch there" when the URL information came from the Cogito style + branches/there file did not update refs/heads/there (regression in + 1.5.4). + + * Bogus refspec configuration such as "remote.there.fetch = =" were not + detected as errors (regression in 1.5.4). + + * You couldn't specify a custom editor whose path contains a whitespace + via GIT_EDITOR (and core.editor). + + * The subdirectory filter to "git filter-branch" mishandled a history + where the subdirectory becomes empty and then later becomes non-empty. + + * "git shortlog" gave an empty line if the original commit message was + malformed (e.g. a botched import from foreign SCM). Now it finds the + first non-empty line and uses it for better information. + + * When the user fails to give a revision parameter to "git svn", an error + from the Perl interpreter was issued because the script lacked proper + error checking. + + * After "git rebase" stopped due to conflicts, if the user played with + "git reset" and friends, "git rebase --abort" failed to go back to the + correct commit. + + * Additional work trees prepared with git-new-workdir (in contrib/) did + not share git-svn metadata directory .git/svn with the original. + + * "git-merge-recursive" did not mark addition of the same path with + different filemodes correctly as a conflict. + + * "gitweb" gave malformed URL when pathinfo stype paths are in use. + + * "-n" stands for "--no-tags" again for "git fetch". + + * "git format-patch" did not detect the need to add 8-bit MIME header + when the user used format.header configuration. + + * "rev~" revision specifier used to mean "rev", which was inconsistent + with how "rev^" worked. Now "rev~" is the same as "rev~1" (hence it + also is the same as "rev^1"), and "rev~0" is the same as "rev^0" + (i.e. it has to be a commit). + + * "git quiltimport" did not grok empty lines, lines in "file -pNNN" + format to specify the prefix levels and lines with trailing comments. + + * "git rebase -m" triggered pre-commit verification, which made + "rebase --continue" impossible. + +As usual, it also comes with many documentation fixes and clarifications. diff --git a/Documentation/RelNotes/1.5.4.6.txt b/Documentation/RelNotes/1.5.4.6.txt new file mode 100644 index 0000000..3e3c3e5 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.6.txt @@ -0,0 +1,43 @@ +GIT v1.5.4.6 Release Notes +========================== + +I personally do not think there is any reason anybody should want to +run v1.5.4.X series these days, because 'master' version is always +more stable than any tagged released version of git. + +This is primarily to futureproof "git-shell" to accept requests +without a dash between "git" and subcommand name (e.g. "git +upload-pack") which the newer client will start to make sometime in +the future. + +Fixes since v1.5.4.5 +-------------------- + + * Command line option "-n" to "git-repack" was not correctly parsed. + + * Error messages from "git-apply" when the patchfile cannot be opened + have been improved. + + * Error messages from "git-bisect" when given nonsense revisions have + been improved. + + * reflog syntax that uses time e.g. "HEAD@{10 seconds ago}:path" did not + stop parsing at the closing "}". + + * "git rev-parse --symbolic-full-name ^master^2" printed solitary "^", + but it should print nothing. + + * "git apply" did not enforce "match at the beginning" correctly. + + * a path specification "a/b" in .gitattributes file should not match + "sub/a/b", but it did. + + * "git log --date-order --topo-order" did not override the earlier + date-order with topo-order as expected. + + * "git fast-export" did not export octopus merges correctly. + + * "git archive --prefix=$path/" mishandled gitattributes. + +As usual, it also comes with many documentation fixes and clarifications. + diff --git a/Documentation/RelNotes/1.5.4.7.txt b/Documentation/RelNotes/1.5.4.7.txt new file mode 100644 index 0000000..9065a0e --- /dev/null +++ b/Documentation/RelNotes/1.5.4.7.txt @@ -0,0 +1,10 @@ +GIT v1.5.4.7 Release Notes +========================== + +Fixes since 1.5.4.7 +------------------- + + * Removed support for an obsolete gitweb request URI, whose + implementation ran "git diff" Porcelain, instead of using plumbing, + which would have run an external diff command specified in the + repository configuration as the gitweb user. diff --git a/Documentation/RelNotes/1.5.4.txt b/Documentation/RelNotes/1.5.4.txt new file mode 100644 index 0000000..f1323b6 --- /dev/null +++ b/Documentation/RelNotes/1.5.4.txt @@ -0,0 +1,377 @@ +GIT v1.5.4 Release Notes +======================== + +Removal +------- + + * "git svnimport" was removed in favor of "git svn". It is still there + in the source tree (contrib/examples) but unsupported. + + * As git-commit and git-status have been rewritten, "git runstatus" + helper script lost all its users and has been removed. + + +Temporarily disabled +-------------------- + + * "git http-push" is known not to work well with cURL library older + than 7.16, and we had reports of repository corruption. It is + disabled on such platforms for now. Unfortunately, 1.5.3.8 shares + the same issue. In other words, this does not mean you will be + fine if you stick to an older git release. For now, please do not + use http-push from older git with cURL older than 7.16 if you + value your data. A proper fix will hopefully materialize in + later versions. + + +Deprecation notices +------------------- + + * From v1.6.0, git will by default install dashed form of commands + (e.g. "git-commit") outside of users' normal $PATH, and will install + only selected commands ("git" itself, and "gitk") in $PATH. This + implies: + + - Using dashed forms of git commands (e.g. "git-commit") from the + command line has been informally deprecated since early 2006, but + now it officially is, and will be removed in the future. Use + dash-less forms (e.g. "git commit") instead. + + - Using dashed forms from your scripts, without first prepending the + return value from "git --exec-path" to the scripts' PATH, has been + informally deprecated since early 2006, but now it officially is. + + - Use of dashed forms with "PATH=$(git --exec-path):$PATH; export + PATH" early in your script is not deprecated with this change. + + Users are strongly encouraged to adjust their habits and scripts now + to prepare for this change. + + * The post-receive hook was introduced in March 2007 to supersede + the post-update hook, primarily to overcome the command line length + limitation of the latter. Use of post-update hook will be deprecated + in future versions of git, starting from v1.6.0. + + * "git lost-found" was deprecated in favor of "git fsck"'s --lost-found + option, and will be removed in the future. + + * "git peek-remote" is deprecated, as "git ls-remote" was written in C + and works for all transports; "git peek-remote" will be removed in + the future. + + * "git repo-config" which was an old name for "git config" command + has been supported without being advertised for a long time. The + next feature release will remove it. + + * From v1.6.0, the repack.usedeltabaseoffset config option will default + to true, which will give denser packfiles (i.e. more efficient storage). + The downside is that git older than version 1.4.4 will not be able + to directly use a repository packed using this setting. + + * From v1.6.0, the pack.indexversion config option will default to 2, + which is slightly more efficient, and makes repacking more immune to + data corruptions. Git older than version 1.5.2 may revert to version 1 + of the pack index with a manual "git index-pack" to be able to directly + access corresponding pack files. + + +Updates since v1.5.3 +-------------------- + + * Comes with much improved gitk, with i18n. + + * Comes with git-gui 0.9.2 with i18n. + + * gitk is now merged as a subdirectory of git.git project, in + preparation for its i18n. + + * progress displays from many commands are a lot nicer to the eye. + Transfer commands show throughput data. + + * many commands that pay attention to per-directory .gitignore now do + so lazily, which makes the usual case go much faster. + + * Output processing for '--pretty=format:' has been + optimized. + + * Rename detection of diff family while detecting exact matches has + been greatly optimized. + + * Rename detection of diff family tries to make more natural looking + pairing. Earlier, if multiple identical rename sources were + found in the preimage, the source used was picked pretty much at random. + + * Value "true" for color.diff and color.status configuration used to + mean "always" (even when the output is not going to a terminal). + This has been corrected to mean the same thing as "auto". + + * "git diff" Porcelain now respects diff.external configuration, which + is another way to specify GIT_EXTERNAL_DIFF. + + * "git diff" can be told to use different prefixes other than + "a/" and "b/" e.g. "git diff --src-prefix=l/ --dst-prefix=k/". + + * "git diff" sometimes did not quote paths with funny + characters properly. + + * "git log" (and any revision traversal commands) misbehaved + when --diff-filter is given but was not asked to actually + produce diff. + + * HTTP proxy can be specified per remote repository using + remote.*.httpproxy configuration, or global http.proxy configuration + variable. + + * Various Perforce importer updates. + + * Example update and post-receive hooks have been improved. + + * Any command that wants to take a commit object name can now use + ":/string" syntax to name a commit. + + * "git reset" is now built-in and its output can be squelched with -q. + + * "git reset --hard" does not make any sense in a bare + repository, but did not error out; fixed. + + * "git send-email" can optionally talk over ssmtp and use SMTP-AUTH. + + * "git rebase" learned --whitespace option. + + * In "git rebase", when you decide not to replay a particular change + after the command stopped with a conflict, you can say "git rebase + --skip" without first running "git reset --hard", as the command now + runs it for you. + + * "git rebase --interactive" mode can now work on detached HEAD. + + * Other minor to serious bugs in "git rebase -i" have been fixed. + + * "git rebase" now detaches head during its operation, so after a + successful "git rebase" operation, the reflog entry branch@{1} for + the current branch points at the commit before the rebase was + started. + + * "git rebase -i" also triggers rerere to help your repeated merges. + + * "git merge" can call the "post-merge" hook. + + * "git pack-objects" can optionally run deltification with multiple + threads. + + * "git archive" can optionally substitute keywords in files marked with + export-subst attribute. + + * "git cherry-pick" made a misguided attempt to repeat the original + command line in the generated log message, when told to cherry-pick a + commit by naming a tag that points at it. It does not anymore. + + * "git for-each-ref" learned %(xxxdate:) syntax to show the + various date fields in different formats. + + * "git gc --auto" is a low-impact way to automatically run a variant of + "git repack" that does not lose unreferenced objects (read: safer + than the usual one) after the user accumulates too many loose + objects. + + * "git clean" has been rewritten in C. + + * You need to explicitly set clean.requireForce to "false" to allow + "git clean" without -f to do any damage (lack of the configuration + variable used to mean "do not require -f option to lose untracked + files", but we now use the safer default). + + * The kinds of whitespace errors "git diff" and "git apply" notice (and + fix) can be controlled via 'core.whitespace' configuration variable + and 'whitespace' attribute in .gitattributes file. + + * "git push" learned --dry-run option to show what would happen if a + push is run. + + * "git push" does not update a tracking ref on the local side when the + remote refused to update the corresponding ref. + + * "git push" learned --mirror option. This is to push the local refs + one-to-one to the remote, and deletes refs from the remote that do + not exist anymore in the repository on the pushing side. + + * "git push" can remove a corrupt ref at the remote site with the usual + ":ref" refspec. + + * "git remote" knows --mirror mode. This is to set up configuration to + push into a remote repository to store local branch heads to the same + branch on the remote side, and remove branch heads locally removed + from local repository at the same time. Suitable for pushing into a + back-up repository. + + * "git remote" learned "rm" subcommand. + + * "git cvsserver" can be run via "git shell". Also, "cvs" is + recognized as a synonym for "git cvsserver", so that CVS users + can be switched to git just by changing their login shell. + + * "git cvsserver" acts more like receive-pack by running post-receive + and post-update hooks. + + * "git am" and "git rebase" are far less verbose. + + * "git pull" learned to pass --[no-]ff option to underlying "git + merge". + + * "git pull --rebase" is a different way to integrate what you fetched + into your current branch. + + * "git fast-export" produces data-stream that can be fed to fast-import + to reproduce the history recorded in a git repository. + + * "git add -i" takes pathspecs to limit the set of files to work on. + + * "git add -p" is a short-hand to go directly to the selective patch + subcommand in the interactive command loop and to exit when done. + + * "git add -i" UI has been colorized. The interactive prompt + and menu can be colored by setting color.interactive + configuration. The diff output (including the hunk picker) + are colored with color.diff configuration. + + * "git commit --allow-empty" allows you to create a single-parent + commit that records the same tree as its parent, overriding the usual + safety valve. + + * "git commit --amend" can amend a merge that does not change the tree + from its first parent. + + * "git commit" used to unconditionally strip comment lines that + began with '#' and removed excess blank lines. This behavior has + been made configurable. + + * "git commit" has been rewritten in C. + + * "git stash random-text" does not create a new stash anymore. It was + a UI mistake. Use "git stash save random-text", or "git stash" + (without extra args) for that. + + * "git stash clear extra-text" does not clear the whole stash + anymore. It is tempting to expect "git stash clear stash@{2}" + to drop only a single named stash entry, and it is rude to + discard everything when that is asked (but not provided). + + * "git prune --expire