Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: describe how to run the tests #1981

Merged
merged 4 commits into from
Mar 17, 2025
Merged

README: describe how to run the tests #1981

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
021a647
README: stop using rarely-used `ShellSession` markup
dscho Mar 15, 2025
775de01
README: use `console` markup consistently
dscho Mar 15, 2025
ec0fe0b
README: describe how to run the tests
dscho Mar 15, 2025
9248e49
README: adjust too-informal wording
dscho Mar 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 86 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ 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 <directory>...`](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
```

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
Expand Down Expand Up @@ -55,97 +55,155 @@ 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.

Pro-Tip: Do this in a sparse checkout that excludes large parts of `content/`, to speed up the rendering time.

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`).

## 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 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:

```console
$ PLAYWRIGHT_TEST_URL='http://localhost:5000/' npx playwright test --project=firefox
```

For more fine-grained testing, you can pass `-g <regex>` to run only the matching test cases.

## Update manual pages

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

Expand Down
Loading