diff --git a/README.md b/README.md index b8c8343767..b20b1231fd 100644 --- a/README.md +++ b/README.md @@ -1,256 +1,292 @@ -# Git Homepage [![CI](https://github.com/git/git-scm.com/actions/workflows/ci.yml/badge.svg)](https://github.com/git/git-scm.com/actions/workflows/ci.yml) [![Help Contribute to Open Source](https://www.codetriage.com/git/git-scm.com/badges/users.svg)](https://www.codetriage.com/git/git-scm.com) +# Git Homepage -This is the repository for the [git-scm.com](https://git-scm.com) site. It is meant to be the -first place a person new to Git will land and download or learn about the -Git SCM system. +[![CI](https://github.com/git/git-scm.com/actions/workflows/ci.yml/badge.svg)](https://github.com/git/git-scm.com/actions/workflows/ci.yml) +[![Help Contribute to Open Source](https://www.codetriage.com/git/git-scm.com/badges/users.svg)](https://www.codetriage.com/git/git-scm.com) -This site is built with [Hugo](https://gohugo.io/) and served via GitHub Pages. +Welcome to the repository for [git-scm.com](https://git-scm.com), the official website for Git. This site is designed to be the starting point for anyone interested in downloading, learning about, or contributing to the Git SCM system. The site is built with [Hugo](https://gohugo.io/) and served via GitHub Pages. -## Local development setup +--- -> [!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: +## Table of Contents + +- [Getting Started](#getting-started) + - [Cloning the Repository](#cloning-the-repository) + - [Directory Structure](#directory-structure) +- [Local Development](#local-development) + - [Prerequisites](#prerequisites) + - [Serving the Site Locally](#serving-the-site-locally) + - [Enabling Search Locally](#enabling-search-locally) +- [Testing](#testing) +- [Content Updates](#content-updates) + - [Manual Pages](#manual-pages) + - [Downloads Data](#downloads-data) + - [ProGit Book](#progit-book) +- [Contributing](#contributing) +- [Adding a New GUI Client](#adding-a-new-gui-client) +- [Useful Links](#useful-links) +- [License](#license) + +--- + +## Getting Started + +### Cloning the Repository + +#### 1. Recommended Approach: Using Scalar + +We recommend using [`scalar`](https://git-scm.com/docs/scalar) for an efficient and focused clone. This allows you to work only on the parts of the repository relevant to your interests. ```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 +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: +#### 2. Alternative: Manual Sparse Clone + +If `scalar` is not available, you can perform a sparse, partial clone manually: ```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 -$ git reset --hard +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 +git reset --hard ``` -> [!NOTE] -> If you _already_ have a full clone and wish to accelerate development by focusing only on a small subset of the pages, you may want to run the `git sparse-checkout set [...]` command mentioned above. - -Here is a detailed list of the relevant directories: +> **Note:** +> If you already have a full clone and wish to focus on a subset of the repository, you may use the `git sparse-checkout set [...]` command as shown above. -- If you want to test any page rendering using Hugo: - - layouts/ - - content/ - - static/ - - assets/ +### Directory Structure -- To add new GUIs: - - data/ +- **layouts/**, **content/**, **static/**, **assets/**: For testing page rendering with Hugo. +- **data/**: For adding new GUI client data. +- **script/**: For pre-rendering pages sourced from other repositories (e.g., ProGit book). +- **.github/**: Contains GitHub workflow configurations. +- **external/book/**, **external/docs/**: Pre-rendered pages (do not edit directly). -- To work on pre-rendering pages that originate from other repositories (such as the ProGit book): - - script/ +--- -- To work on the GitHub workflows that perform the automated, scheduled pre-rendering: - - .github/ +## Local Development -- The pre-rendered pages (ProGit book, its translated versions, the manual pages, their translated versions): - - external/book/ - - external/docs/ - You will want to avoid editing these directly, as they contain pages that are pre-rendered via GitHub workflows, sourcing content from other repositories. +### Prerequisites -To render the site locally, you'll need [Hugo](https://gohugo.io/)'s **extended** version v0.128.0 or later. On Windows, we recommend using the Windows Subsystem for Linux (WSL) because some file names contain colons which prevent them from being checked out on Windows file systems. +- [Hugo](https://gohugo.io/), **extended** version v0.128.0 or later. +- [Node.js](https://nodejs.org/). +- On Windows, it is recommended to use Windows Subsystem for Linux (WSL) due to file naming constraints. -You can verify the Hugo version like this: +Verify your Hugo installation: ```console $ hugo version hugo v0.128.0+extended linux/amd64 BuildDate=unknown ``` -You can serve the site locally via: +### Serving the Site Locally + +To serve the site using the provided script: ```console -$ node script/serve-public.js +node script/serve-public.js ``` -The site should be running on http://127.0.0.1:5000. +The site will be available at [http://127.0.0.1:5000](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: +Alternatively, to use Hugo's built-in server (served at [http://127.0.0.1:1313](http://127.0.0.1:1313)), disable "ugly URLs": ```console -$ HUGO_UGLYURLS=false hugo serve -w +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. +> **Note:** +> "Ugly URLs" refer to URLs ending with `.html` (e.g., `/about.html`). GitHub Pages prefers these for compatibility. The `serve-public.js` script emulates this behavior. -Pro-Tip: Do this in a sparse checkout that excludes large parts of `content/`, to speed up the rendering time. +### Enabling Search Locally -To test the site locally _with_ the search enabled, run this instead: +To test the site with search enabled: ```console -$ hugo -$ npx -y pagefind --site public -$ node script/serve-public.js +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": +Alternatively, to use Pagefind's built-in server (at [http://127.0.0.1:1414](http://127.0.0.1:1414)): ```console -$ HUGO_UGLYURLS=false hugo -$ npx -y pagefind --site public --serve +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`). +> **Note:** +> Running Pagefind may slow down the process and disables live reloading. -## 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`. +## Testing -To run these tests in your local setup, you need a working node.js installation. After that, you need to install Playwright: +The site includes a test suite using [Playwright](https://playwright.dev/) to verify UI correctness. Tests are located in the `tests/` directory and configured via `playwright.config.js`. -```console -$ npm install @playwright/test -``` +### Running Tests -Since Playwright uses headless versions of popular web browsers, you most likely need to install at least one of them, e.g. via: +1. Install Playwright: -```console -$ npx playwright install firefox -``` + ```console + npm install @playwright/test + ``` -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: +### 2. Install a browser for Playwright tests (e.g., Firefox) + +Playwright supports several browsers including `firefox`, `chromium`, `webkit`, and `chrome`. You can install a specific browser like Firefox using: ```console -$ PLAYWRIGHT_TEST_URL='http://localhost:5000/' npx playwright test --project=firefox +npx playwright install firefox ``` -For more fine-grained testing, you can pass `-g ` to run only the matching test cases. +> **Note:** +> You can install all supported browsers with `npx playwright install`, but be aware that each browser download is over 100MB. To save space and time, install only the browsers you need. +> In GitHub Actions hosted runners, Chrome is pre-installed, and you might also be able to use your local Chrome installation. + +--- -## Update manual pages +### 3. Run tests against your local site -First, install the Ruby prerequisites: +By default, Playwright tests run against [https://git-scm.com/](https://git-scm.com/). To test your local changes, run a local server (e.g., on `http://localhost:5000/`) and then run the tests targeting it: ```console -$ bundler install +PLAYWRIGHT_TEST_URL='http://localhost:5000/' npx playwright test --project=firefox ``` -Then, you can build the manual pages using a local Git source clone like this: +You can also run specific tests matching a pattern using `-g ` for more fine-grained testing. -```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): +## Content Updates -```console -$ version=v2.23.0 -$ REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en -``` +### Manual Pages -Or you can populate the man pages from GitHub (much slower) like this: +1. Install Ruby prerequisites: -```console -$ export GITHUB_API_TOKEN=github_personal_auth_token -$ REBUILD_DOC=$version ruby ./script/update-docs.rb remote en # specific version -``` + ```console + bundler install + ``` -Similarly, you can also populate the localized man pages. From a local clone of https://github.com/jnavila/git-html-l10n : +2. Build manual pages from a local Git clone: -```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 -``` + ```console + ruby ./script/update-docs.rb /path/to/git/.git en + ``` -Or you can do it from GitHub (much slower) like this: + To build for a specific version: -```console -$ export GITHUB_API_TOKEN=github_personal_auth_token -$ REBUILD_DOC=$version ruby ./script/update-docs.rb remote l10n # specific version -``` + ```console + version=v2.23.0 + REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git/.git en + ``` -## Update the `Downloads` pages + To build from GitHub (slower): -Now you need to get the latest downloads for the downloads pages: + ```console + export GITHUB_API_TOKEN=github_personal_auth_token + REBUILD_DOC=$version ruby ./script/update-docs.rb remote en + ``` -```console -$ ruby ./script/update-download-data.rb -``` + For localized man pages, use a local clone of [git-html-l10n](https://github.com/jnavila/git-html-l10n): + + ```console + ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n + REBUILD_DOC=$version ruby ./script/update-docs.rb /path/to/git-html-l10n/.git l10n + ``` -## Update the ProGit book +### Downloads Data -First, you will have to get the necessary prerequisites: +Update the downloads data for the site: ```console -$ bundler install +ruby ./script/update-download-data.rb ``` -Now you'll probably want some book data. +### ProGit Book -You'll have to get the book content from a repository on your computer by specifying the path: +1. Install prerequisites: -```console -$ git clone https://github.com/progit/progit2-fr ../progit2-fr -$ ruby ./script/update-book2.rb fr ../progit2-fr -``` + ```console + bundler install + ``` -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. +2. Clone the book repository and update: -Alternatively, you need to have access to the [Pro Git project on GitHub](https://github.com/progit/progit2) through the API. + ```console + git clone https://github.com/progit/progit2-fr ../progit2-fr + ruby ./script/update-book2.rb fr ../progit2-fr + ``` -```console -$ export GITHUB_API_TOKEN=github_personal_auth_token -$ ruby ./script/update-book2.rb en -``` + Alternatively, fetch from GitHub: -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/). + ```console + export GITHUB_API_TOKEN=github_personal_auth_token + ruby ./script/update-book2.rb en + ``` -If you want to build the book for all available languages, just omit the language code parameter: + To build for all languages: -```console -$ ruby ./script/update-book2.rb -``` + ```console + ruby ./script/update-book2.rb + ``` + +--- ## Contributing -If you wish to contribute to this website, please [fork it on GitHub](https://github.com/git/git-scm.com). +We warmly welcome contributions! Please [fork the repository on GitHub](https://github.com/git/git-scm.com), clone it using [`scalar`](https://git-scm.com/docs/scalar), and use [`git sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout) to focus on relevant files. -Then, clone it using [`scalar`](https://git-scm.com/docs/scalar) (this avoids long clone times) and then use [`git sparse-checkout add `](https://git-scm.com/docs/git-sparse-checkout) to check out the files relevant to your work. +After making your changes, commit and push to a named branch in your fork, then open a pull request. For significant features, consider [opening an issue](https://github.com/git/git-scm.com/issues/new) first to discuss your proposal. -After making the changes, commit and push to a named branch in your fork, then open a pull request. If it is a big feature, you might want to [start an issue](https://github.com/git/git-scm.com/issues/new) first to make sure it's something that will be accepted. +--- -## Adding a new GUI +## Adding a New GUI Client -The [list of GUI clients](https://git-scm.com/downloads/guis) has been constructed by the community for a long time. If you want to add another tool you'll need to follow a few steps: +To add a new GUI client to the [list of GUI clients](https://git-scm.com/downloads/guis): -1. Add a new `.md` file with the GUI client details: data/guis - 1. The fields need to be enclosed within `---` lines - 2. The fields `name`, `project_url`, `price`, `license` should be very straightforward to fill. - 3. The field `image_tag` corresponds to the path of the image of the tool (should start with `images/guis/`). - 4. `platforms` is a list of at least 1 platform in which the tool is supported. The possibilities are: `Windows`, `Mac`, `Linux`, `Android`, and `iOS` - 5. `order` can be filled with the biggest number already existing, plus 1 (this number determines the order in which the GUIs are rendered). This is the only field whose value should _not_ be enclosed in double-quote characters. - 6. `trend_name` is an optional field that can be used for helping sorting the clients. +1. Create a new `.md` file in `data/guis` with the following fields (enclosed within `---`): -2. Add the image to `static/images/guis/@2x.png` and `static/images/guis/.png` making sure the aspect ratio matches a 588:332 image. + - `name` + - `project_url` + - `price` + - `license` + - `image_tag` (path starting with `images/guis/`) + - `platforms` (list: `Windows`, `Mac`, `Linux`, `Android`, `iOS`) + - `order` (next available integer, not in quotes) + - `trend_name` (optional) -## Useful links +2. Add images to `static/images/guis/@2x.png` and `static/images/guis/.png` (aspect ratio: 588:332). -### Hugo (static site generator) +--- -* https://gohugo.io/ -* https://gohugo.io/content-management/shortcodes/ -* https://github.com/google/re2/wiki/Syntax/ (for Hugo's regular expression syntax) +## Useful Links -### Pagefind (client-side search) +### Hugo (Static Site Generator) -* https://pagefind.app/ +- [Hugo Documentation](https://gohugo.io/) +- [Shortcodes](https://gohugo.io/content-management/shortcodes/) +- [Regular Expression Syntax](https://github.com/google/re2/wiki/Syntax/) -### Lychee (link checker) +### Pagefind (Client-Side Search) -* https://lychee.cli.rs/ +- [Pagefind Documentation](https://pagefind.app/) -### Playwright (website UI test framework) +### Lychee (Link Checker) -* https://playwright.dev/ +- [Lychee Documentation](https://lychee.cli.rs/) -## License +### Playwright (UI Test Framework) + +- [Playwright Documentation](https://playwright.dev/) -The source code for the site is licensed under the MIT license, which you can find in -the MIT-LICENSE.txt file. +--- + +## License -All graphical assets are licensed under the -[Creative Commons Attribution 3.0 Unported License](https://creativecommons.org/licenses/by/3.0/). +The source code for this site is licensed under the MIT license (see `MIT-LICENSE.txt`). +All graphical assets are licensed under the [Creative Commons Attribution 3.0 Unported License](https://creativecommons.org/licenses/by/3.0/).