From 021a64743248577707cc9ed142e41f4a1227980b Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Sat, 15 Mar 2025 14:00:02 +0100 Subject: [PATCH 1/4] README: stop using rarely-used `ShellSession` markup The `ShellSession` markup seems to be relatively uncommon, only supported on GitHub. A more common markup -- also understood by GitHub, but supported much more widely, e.g. in Hugo's very own default Markdown processor -- is the `console` one. So let's use that instead. Signed-off-by: Johannes Schindelin --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 65322fbfba..f8eff9d735 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ This site is built with [Hugo](https://gohugo.io/) and served via GitHub Pages. > [!NOTE] > It is highly recommended to clone this repository using [`scalar`](https://git-scm.com/docs/scalar); This allows to work only on the parts of the repository relevant to your interests. You can select which directories are checked out using the [`git sparse-checkout add ...`](https://git-scm.com/docs/git-sparse-checkout) command. Typically, you will want to start like this: -```ShellSession +```console $ scalar clone https://github.com/git/git-scm.com $ cd git-scm.com/src $ git sparse-checkout set layouts content static assets hugo.yml data script @@ -19,7 +19,7 @@ $ git sparse-checkout set layouts content static assets hugo.yml data script If your Git installation comes without `scalar`, you can create a sparse, partial clone manually, like this: -```ShellSession +```console $ git clone --filter=blob:none --no-checkout https://github.com/git/git-scm.com $ cd git-scm.com $ git sparse-checkout set layouts content static assets hugo.yml data script From 775de014a0ca13819122d1cb3abbffa6f3296d9a Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Sat, 15 Mar 2025 14:05:36 +0100 Subject: [PATCH 2/4] README: use `console` markup consistently As early as 5d721a7ac (readme is markdown, 2012-03-08), the `README` was written in Markdown, but its Unix shell command snippets were not marked up as such (most likely because way back when, syntax highlighting in `
` blocks had not yet been dreamt up).

However, we are approaching the end of the first quarter of the 21st
century and it is time to go with the times.

Signed-off-by: Johannes Schindelin 
---
 README.md | 84 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 58 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index f8eff9d735..8ae5afbe57 100644
--- a/README.md
+++ b/README.md
@@ -55,18 +55,24 @@ To render the site locally, you'll need [Hugo](https://gohugo.io/)'s **extended*
 
 You can verify the Hugo version like this:
 
-    $ hugo version
-    hugo v0.128.0+extended linux/amd64 BuildDate=unknown
+```console
+$ hugo version
+hugo v0.128.0+extended linux/amd64 BuildDate=unknown
+```
 
 You can serve the site locally via:
 
-    $ node script/serve-public.js
+```console
+$ node script/serve-public.js
+```
 
 The site should be running on http://127.0.0.1:5000.
 
 If you want to serve the site via Hugo's built-in mechanism, you will need to turn off ["ugly URLs"](https://gohugo.io/content-management/urls/#appearance), by running this command, which will serve the site via http://127.0.0.1:1313:
 
-    $ HUGO_UGLYURLS=false hugo serve -w
+```console
+$ HUGO_UGLYURLS=false hugo serve -w
+```
 
 Side note: What _are_ "ugly URLs"? Hugo, by default, generates "pretty" URLs like https://git-scm.com/about/ (note the trailing slash) instead of what it calls "ugly" URLs like https://git-scm.com/about.html. However, since GitHub Pages auto-resolves "even prettier" URLs like https://git-scm.com/about by appending `.html` first, we _want_ the "ugly" URLs to be used here. The `serve-public.js` script emulates GitHub Pages' behavior, while `hugo serve` does not.
 
@@ -74,14 +80,18 @@ Pro-Tip: Do this in a sparse checkout that excludes large parts of `content/`, t
 
 To test the site locally _with_ the search enabled, run this instead:
 
-    $ hugo
-    $ npx -y pagefind --site public
-    $ node script/serve-public.js
+```console
+$ hugo
+$ npx -y pagefind --site public
+$ node script/serve-public.js
+```
 
 You can also use Pagefind's built-in server (which will be running on http://127.0.0.1:1414), but again, you have to turn off "ugly URLs":
 
-    $ HUGO_UGLYURLS=false hugo
-    $ npx -y pagefind --site public --serve
+```console
+$ HUGO_UGLYURLS=false hugo
+$ npx -y pagefind --site public --serve
+```
 
 Note that running Pagefind will make the process about 7 times slower, and the site will not be re-rendered and live-reloaded in the browser when you change files in `content/` (unlike with `hugo serve -w`).
 
@@ -89,63 +99,85 @@ Note that running Pagefind will make the process about 7 times slower, and the s
 
 First, install the Ruby prerequisites:
 
-	$ bundler install
+```console
+$ bundler install
+```
 
 Then, you can build the manual pages using a local Git source clone like this:
 
-    $ ruby ./script/update-docs.rb /path/to/git/.git en
+```console
+$ ruby ./script/update-docs.rb /path/to/git/.git en
+```
 
 This will populate the manual pages for all Git versions. You can also populate them only for a specific Git version (faster):
 
-    $ version=v2.23.0
-    $ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
+```console
+$ version=v2.23.0
+$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
+```
 
 Or you can populate the man pages from GitHub (much slower) like this:
 
-    $ export GITHUB_API_TOKEN=github_personal_auth_token
-    $ REBUILD_DOC=$version ruby ./script/update-docs.rb remote en  # specific version
+```console
+$ export GITHUB_API_TOKEN=github_personal_auth_token
+$ REBUILD_DOC=$version ruby ./script/update-docs.rb remote en  # specific version
+```
 
 Similarly, you can also populate the localized man pages. From a local clone of https://github.com/jnavila/git-html-l10n :
 
-    $ ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n  # all versions
-    $ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n  # specific version
+```console
+$ ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n  # all versions
+$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n  # specific version
+```
 
 Or you can do it from GitHub (much slower) like this:
 
-    $ export GITHUB_API_TOKEN=github_personal_auth_token
-    $ REBUILD_DOC=$version ruby ./script/update-docs.rb remote l10n  # specific version
+```console
+$ export GITHUB_API_TOKEN=github_personal_auth_token
+$ REBUILD_DOC=$version ruby ./script/update-docs.rb remote l10n  # specific version
+```
 
 ## Update the `Downloads` pages
 
 Now you need to get the latest downloads for the downloads pages:
 
-    $ ruby ./script/update-download-data.rb
+```console
+$ ruby ./script/update-download-data.rb
+```
 
 ## Update the ProGit book
 
 First, you will have to get the necessary prerequisites:
 
-    $ bundler install
+```console
+$ bundler install
+```
 
 Now you'll probably want some book data.
 
 You'll have to get the book content from a repository on your computer by specifying the path:
 
-    $ git clone https://github.com/progit/progit2-fr ../progit2-fr
-    $ ruby ./script/update-book2.rb fr ../progit2-fr
+```console
+$ git clone https://github.com/progit/progit2-fr ../progit2-fr
+$ ruby ./script/update-book2.rb fr ../progit2-fr
+```
 
 That will generate the book content from the Asciidoc files and write the files to the local tree, ready to be committed and served via Hugo.
 
 Alternatively, you need to have access to the [Pro Git project on GitHub](https://github.com/progit/progit2) through the API.
 
-    $ export GITHUB_API_TOKEN=github_personal_auth_token
-    $ ruby ./script/update-book2.rb en
+```console
+$ export GITHUB_API_TOKEN=github_personal_auth_token
+$ ruby ./script/update-book2.rb en
+```
 
 If you have 2FA enabled, you'll need to create a [Personal Access Token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
 
 If you want to build the book for all available languages, just omit the language code parameter:
 
-    $ ruby ./script/update-book2.rb
+```console
+$ ruby ./script/update-book2.rb
+```
 
 ## Contributing
 

From ec0fe0ba12af9139e464ac4fd9113630bf772167 Mon Sep 17 00:00:00 2001
From: Johannes Schindelin 
Date: Sat, 15 Mar 2025 14:18:58 +0100
Subject: [PATCH 3/4] README: describe how to run the tests

I had already provided links, a long time ago, but failed to jot down
notes that were so far stuck in my brain but would most likely benefit
new contributors a lot.

Signed-off-by: Johannes Schindelin 
---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 8ae5afbe57..68b2165d0e 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,32 @@ $ npx -y pagefind --site public --serve
 
 Note that running Pagefind will make the process about 7 times slower, and the site will not be re-rendered and live-reloaded in the browser when you change files in `content/` (unlike with `hugo serve -w`).
 
+## Running the test suite
+
+Believe it or not, https://git-scm.com/ has its own test suite. It uses [Playwright](https://playwright.dev/) to perform a couple of tests that verify that the site "looks right". These tests live in `tests/` and are configured via `playwright.config.js`.
+
+To run these tests in your local setup, you need a working node.js installation. After that, you need to install Playwright:
+
+```console
+$ npm install @playwright/test
+```
+
+Since Playwright uses headless versions of popular web browsers, you most likely need to install at least one of them, e.g. via:
+
+```console
+$ npx playwright install firefox
+```
+
+Supported browsers include `firefox`, `chromium`, `webkit`, `chrome`. You can also simply download all of 'em using `npx playwright install` but please first note that they all weigh >100MB, so you might want to refrain from doing that. Side note: In GitHub Actions' hosted runners, Chrome comes pre-installed, and you might be able to use your own Chrome installation, too, if you have one.
+
+By default, the Playwright tests target https://git-scm.com/, which is unlikely what you want: You probably want to run the tests to validate your local changes. To do so, the configuration has a special provision to start a tiny local web server to serve the files written to `public/` by Hugo and Pagefind:
+
+```console
+$ PLAYWRIGHT_TEST_URL='http://localhost:5000/' npx playwright test --project=firefox
+```
+
+For more fine-grained testing, you can pass `-g ` to run only the matching test cases.
+
 ## Update manual pages
 
 First, install the Ruby prerequisites:

From 9248e493cd58a058289d7894025d9a8b2a9a103d Mon Sep 17 00:00:00 2001
From: Johannes Schindelin 
Date: Mon, 17 Mar 2025 06:57:28 +0100
Subject: [PATCH 4/4] README: adjust too-informal wording

Co-authored-by: Loymdayddaud <145969603+TheGiraffe3@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 68b2165d0e..b8c8343767 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ Since Playwright uses headless versions of popular web browsers, you most likely
 $ npx playwright install firefox
 ```
 
-Supported browsers include `firefox`, `chromium`, `webkit`, `chrome`. You can also simply download all of 'em using `npx playwright install` but please first note that they all weigh >100MB, so you might want to refrain from doing that. Side note: In GitHub Actions' hosted runners, Chrome comes pre-installed, and you might be able to use your own Chrome installation, too, if you have one.
+Supported browsers include `firefox`, `chromium`, `webkit`, `chrome`. You can also simply download all of them using `npx playwright install` but please first note that they all weigh >100MB, so you might want to refrain from doing that. Side note: In GitHub Actions' hosted runners, Chrome comes pre-installed, and you might be able to use your own Chrome installation, too, if you have one.
 
 By default, the Playwright tests target https://git-scm.com/, which is unlikely what you want: You probably want to run the tests to validate your local changes. To do so, the configuration has a special provision to start a tiny local web server to serve the files written to `public/` by Hugo and Pagefind: