You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+86-28
Original file line number
Diff line number
Diff line change
@@ -11,15 +11,15 @@ This site is built with [Hugo](https://gohugo.io/) and served via GitHub Pages.
11
11
> [!NOTE]
12
12
> 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 <directory>...`](https://git-scm.com/docs/git-sparse-checkout) command. Typically, you will want to start like this:
$ git sparse-checkout set layouts content static assets hugo.yml data script
@@ -55,97 +55,155 @@ To render the site locally, you'll need [Hugo](https://gohugo.io/)'s **extended*
55
55
56
56
You can verify the Hugo version like this:
57
57
58
-
$ hugo version
59
-
hugo v0.128.0+extended linux/amd64 BuildDate=unknown
58
+
```console
59
+
$ hugo version
60
+
hugo v0.128.0+extended linux/amd64 BuildDate=unknown
61
+
```
60
62
61
63
You can serve the site locally via:
62
64
63
-
$ node script/serve-public.js
65
+
```console
66
+
$ node script/serve-public.js
67
+
```
64
68
65
69
The site should be running on http://127.0.0.1:5000.
66
70
67
71
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:
68
72
69
-
$ HUGO_UGLYURLS=false hugo serve -w
73
+
```console
74
+
$ HUGO_UGLYURLS=false hugo serve -w
75
+
```
70
76
71
77
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.
72
78
73
79
Pro-Tip: Do this in a sparse checkout that excludes large parts of `content/`, to speed up the rendering time.
74
80
75
81
To test the site locally _with_ the search enabled, run this instead:
76
82
77
-
$ hugo
78
-
$ npx -y pagefind --site public
79
-
$ node script/serve-public.js
83
+
```console
84
+
$ hugo
85
+
$ npx -y pagefind --site public
86
+
$ node script/serve-public.js
87
+
```
80
88
81
89
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":
82
90
83
-
$ HUGO_UGLYURLS=false hugo
84
-
$ npx -y pagefind --site public --serve
91
+
```console
92
+
$ HUGO_UGLYURLS=false hugo
93
+
$ npx -y pagefind --site public --serve
94
+
```
85
95
86
96
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`).
87
97
98
+
## Running the test suite
99
+
100
+
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`.
101
+
102
+
To run these tests in your local setup, you need a working node.js installation. After that, you need to install Playwright:
103
+
104
+
```console
105
+
$ npm install @playwright/test
106
+
```
107
+
108
+
Since Playwright uses headless versions of popular web browsers, you most likely need to install at least one of them, e.g. via:
109
+
110
+
```console
111
+
$ npx playwright install firefox
112
+
```
113
+
114
+
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.
115
+
116
+
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:
117
+
118
+
```console
119
+
$ PLAYWRIGHT_TEST_URL='http://localhost:5000/' npx playwright test --project=firefox
120
+
```
121
+
122
+
For more fine-grained testing, you can pass `-g <regex>` to run only the matching test cases.
123
+
88
124
## Update manual pages
89
125
90
126
First, install the Ruby prerequisites:
91
127
92
-
$ bundler install
128
+
```console
129
+
$ bundler install
130
+
```
93
131
94
132
Then, you can build the manual pages using a local Git source clone like this:
95
133
96
-
$ ruby ./script/update-docs.rb /path/to/git/.git en
134
+
```console
135
+
$ ruby ./script/update-docs.rb /path/to/git/.git en
136
+
```
97
137
98
138
This will populate the manual pages for all Git versions. You can also populate them only for a specific Git version (faster):
99
139
100
-
$ version=v2.23.0
101
-
$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
140
+
```console
141
+
$ version=v2.23.0
142
+
$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en
143
+
```
102
144
103
145
Or you can populate the man pages from GitHub (much slower) like this:
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/).
145
201
146
202
If you want to build the book for all available languages, just omit the language code parameter:
0 commit comments