From 616fe0061479180653806d9b61017916480d9fe8 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:37:36 +0300 Subject: [PATCH 01/21] Refactor README intro for clarity and layout Move badges below the title to improve visual hierarchy. Reword the opening paragraph to make the purpose of the site clearer for first-time visitors. --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b8c8343767..48d4124458 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ -# 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 From 61b0883eec03f2e17cc2d08dc4d201fa8c723ad4 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:47:46 +0300 Subject: [PATCH 02/21] Add detailed Table of Contents for project documentation Replace initial local development note with a comprehensive Table of Contents Organize sections for easy navigation: Getting Started, Local Development, Testing, Content Updates, Contributing, etc. --- README.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 48d4124458..dc8efc174e 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,28 @@ 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) + +--- ```console $ scalar clone https://github.com/git/git-scm.com From 6fad6bf71327c23667ad8827e859163038e6100e Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:52:29 +0300 Subject: [PATCH 03/21] Add "Getting Started" section with recommended cloning method Introduce "Cloning the Repository" guide Recommend using scalar for efficient sparse cloning --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index dc8efc174e..1988732bdd 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,14 @@ Welcome to the repository for [git-scm.com](https://git-scm.com), the official w --- +## 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 From 000aad3f08ddfc798286b3893fc32758433cb2f4 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:54:29 +0300 Subject: [PATCH 04/21] Remove $ from shell commands to improve copy-pasting Make commands easier to copy and paste without errors --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1988732bdd..f3e3d9369e 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,9 @@ Welcome to the repository for [git-scm.com](https://git-scm.com), the official w 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: From b167db05728f2144063a8df7f4ccccb9f185fdca Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:56:48 +0300 Subject: [PATCH 05/21] Add manual sparse clone instructions and remove $ from commands Add "Alternative: Manual Sparse Clone" section for users without scalar Provide clean, prompt-free shell commands to improve copy-pasting Enhance usability of the cloning instructions --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f3e3d9369e..9e7241bd78 100644 --- a/README.md +++ b/README.md @@ -42,13 +42,15 @@ 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] From 0c06fa862ef7fe0e70adbe2e4819988fff9a4b00 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 07:59:20 +0300 Subject: [PATCH 06/21] Refine note on using sparse-checkout with existing full clones Reformat note for better readability and emphasis Clarify instructions for users with a full clone to focus on subsets Improve tone and consistency in documentation style --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9e7241bd78..368892fa93 100644 --- a/README.md +++ b/README.md @@ -53,8 +53,8 @@ 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. +> **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. Here is a detailed list of the relevant directories: From 5481388b99ee2d34909e2c5ab42b872965f106e9 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:01:42 +0300 Subject: [PATCH 07/21] Add detailed directory structure section with descriptions Provide brief explanations for each relevant directory Improve clarity for developers navigating the project layout --- README.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 368892fa93..8e1c452adb 100644 --- a/README.md +++ b/README.md @@ -56,19 +56,15 @@ git reset --hard > **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. -Here is a detailed list of the relevant directories: +### Directory Structure -- If you want to test any page rendering using Hugo: - - layouts/ - - content/ - - static/ - - assets/ +- **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 add new GUIs: - - data/ - -- 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/ From 289edb62496b4fbaf3d7bed445680f8fbb19789d Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:05:45 +0300 Subject: [PATCH 08/21] Revamp local development section with prerequisites and serving instructions Add a new "Local Development" section with subsections for prerequisites and serving the site Specify required tools: Hugo (extended v0.128.0+), Node.js, and Windows WSL recommendation Improve instructions for verifying Hugo version and serving the site locally Clarify note about pre-rendered directories and GitHub workflows --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 8e1c452adb..313dc1bab1 100644 --- a/README.md +++ b/README.md @@ -66,30 +66,30 @@ git reset --hard --- -- 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: From 3461aa188d3dd64b4d5bd007da2d65ffc506c12e Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:08:26 +0300 Subject: [PATCH 09/21] =?UTF-8?q?Clarify=20usage=20of=20Hugo=E2=80=99s=20b?= =?UTF-8?q?uilt-in=20server=20with=20ugly=20URLs=20disabled?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reword instructions to use Hugo’s built-in server. Explain the need to disable “ugly URLs” for compatibility with GitHub Pages Add a clear note defining “ugly URLs” and why serve-public.js emulates GitHub Pages behavior --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 313dc1bab1..4f6bb48772 100644 --- a/README.md +++ b/README.md @@ -91,13 +91,14 @@ node script/serve-public.js 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. From 283537a0aecd7ddc23a28937d2669a0e5f3f6879 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:11:00 +0300 Subject: [PATCH 10/21] Add "Enabling Search Locally" section and clean up shell command formatting Introduce instructions to build the site with search enabled using Hugo and Pagefind Remove $ prompt symbols from shell commands to improve copy-pasting experience Improve clarity and usability of local testing documentation --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4f6bb48772..84d1fb853d 100644 --- a/README.md +++ b/README.md @@ -100,14 +100,14 @@ HUGO_UGLYURLS=false hugo serve -w > **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": From 3f0cb77c30ae103d11212d6107626ebb55f3b7f4 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:13:36 +0300 Subject: [PATCH 11/21] Update Pagefind server instructions and add note on performance impact MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rephrase to highlight using Pagefind’s built-in server. Remove $ from shell commands for easier copy-pasting Add a clear note about slower performance and disabled live reload when using Pagefind --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 84d1fb853d..061d8c7141 100644 --- a/README.md +++ b/README.md @@ -110,16 +110,17 @@ 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`. From d9c5731833056dc863c9a9eb6cbb9dcf39a2b11a Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:20:28 +0300 Subject: [PATCH 12/21] Revise Testing section for clarity and improved formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite introduction to describe Playwright test suite and location clearly Add “Running Tests” subsection with step-by-step instructions Remove $ prompt symbols from shell commands to simplify copy-pasting Improve overall structure and readability of the testing setup documentation --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 061d8c7141..8a9b9789bc 100644 --- a/README.md +++ b/README.md @@ -122,19 +122,17 @@ npx -y pagefind --site public --serve --- -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. From aaf72d507646b601d086287a2eec0e9ebb93aa0d Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:32:24 +0300 Subject: [PATCH 13/21] Clarify Playwright setup and testing instructions Reorganize the Playwright testing section to improve clarity and usability. Adds headings, formatting, and notes on browser download sizes. Also explains how to run tests against local changes and filter tests with regex. --- README.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 8a9b9789bc..f27a21ba01 100644 --- a/README.md +++ b/README.md @@ -134,29 +134,33 @@ The site includes a test suite using [Playwright](https://playwright.dev/) to ve 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. +--- + +### 2. Install a browser for Playwright tests (e.g., Firefox) -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: +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): From 3adf702b1b6f175868c2aa1bfffa2420c9df34fb Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:36:11 +0300 Subject: [PATCH 14/21] Refactor manual pages section for clarity and structure Add clear headings under 'Content Updates' for installing Ruby dependencies and generating manual pages. Reorganize steps to separate local and remote build instructions, and format code blocks consistently for better readability. --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f27a21ba01..653fa75927 100644 --- a/README.md +++ b/README.md @@ -162,19 +162,15 @@ You can also run specific tests matching a pattern using `-g ` for more f --- -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 : From bf34f051e64e0fa3f10a404b6b228fadb602e2b0 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:38:03 +0300 Subject: [PATCH 15/21] Clarify manual page generation instructions and add localized build steps Structured manual page instructions into local and GitHub-based workflows. Added steps for building localized manual pages using git-html-l10n. Improved formatting and clarity for version-specific builds and prerequisites. --- README.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 653fa75927..afaf59d125 100644 --- a/README.md +++ b/README.md @@ -172,27 +172,32 @@ You can also run specific tests matching a pattern using `-g ` for more f 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 From b33b0f89dc6c82d4617d22abe434c4a62d0ec95f Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:40:48 +0300 Subject: [PATCH 16/21] Refactor instructions for downloads data and ProGit book updates Renamed "Update the ProGit book" section to "ProGit Book" for clarity. Added step-by-step formatting for prerequisites and script usage. Clarified how to fetch and update book content from local repositories. Updated download data instructions for improved readability. --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index afaf59d125..d41e10dca7 100644 --- a/README.md +++ b/README.md @@ -199,22 +199,21 @@ You can also run specific tests matching a pattern using `-g ` for more f 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. From ef25c49600e421339aa4d516cc9b5ae1631ffa66 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:42:50 +0300 Subject: [PATCH 17/21] Improve ProGit book update instructions Reorganized steps into clearly numbered list. Added cloning instructions and clarified directory structure. Documented alternative GitHub-based update method using API tokens. Explained how to build the book for all available languages. --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d41e10dca7..2e4b57e3a9 100644 --- a/README.md +++ b/README.md @@ -215,22 +215,27 @@ ruby ./script/update-download-data.rb 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 From b5f4412ccf14e73d11431ca5f69fe9b23c5523f7 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:43:59 +0300 Subject: [PATCH 18/21] Improve contribution instructions Encouraged contributions with a more welcoming tone. Recommended using scalar and sparse-checkout for efficiency. Added guidance on making pull requests and opening issues for features. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2e4b57e3a9..0160540470 100644 --- a/README.md +++ b/README.md @@ -239,9 +239,9 @@ ruby ./script/update-download-data.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. From aee71903d894344a590f9f6ffb2c974dfb14a62b Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:45:29 +0300 Subject: [PATCH 19/21] Add detailed instructions for adding new GUI clients Added a new section with step-by-step guidance on contributing GUI client entries. Clarified metadata fields required in the .md file. Provided image naming and formatting requirements. Ensured platform and ordering fields are clearly explained. --- README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 0160540470..7285a1b903 100644 --- a/README.md +++ b/README.md @@ -243,23 +243,26 @@ We warmly welcome contributions! Please [fork the repository on GitHub](https:// 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 Client -## Adding a new GUI +To add a new GUI client to the [list of GUI clients](https://git-scm.com/downloads/guis): -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: +1. Create a new `.md` file in `data/guis` with the following fields (enclosed within `---`): -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. + - `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) -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. +2. Add images to `static/images/guis/@2x.png` and `static/images/guis/.png` (aspect ratio: 588:332). -## Useful links +--- ### Hugo (static site generator) From 1311004f22ac411fc2b74c1691aa13313e3b8189 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:46:49 +0300 Subject: [PATCH 20/21] Refactor and enhance Useful Links section Promoted "Hugo", "Pagefind", "Lychee", and "Playwright" to top-level headings. Reorganized and standardized the formatting of resource links. Improved clarity and readability by aligning structure with other sections. --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7285a1b903..fb370f1f01 100644 --- a/README.md +++ b/README.md @@ -264,25 +264,27 @@ To add a new GUI client to the [list of GUI clients](https://git-scm.com/downloa --- -### Hugo (static site generator) +## Useful Links -* https://gohugo.io/ -* https://gohugo.io/content-management/shortcodes/ -* https://github.com/google/re2/wiki/Syntax/ (for Hugo's regular expression syntax) +### Hugo (Static Site Generator) -### Pagefind (client-side search) +- [Hugo Documentation](https://gohugo.io/) +- [Shortcodes](https://gohugo.io/content-management/shortcodes/) +- [Regular Expression Syntax](https://github.com/google/re2/wiki/Syntax/) -* https://pagefind.app/ +### Pagefind (Client-Side Search) -### Lychee (link checker) +- [Pagefind Documentation](https://pagefind.app/) -* https://lychee.cli.rs/ +### Lychee (Link Checker) -### Playwright (website UI test framework) +- [Lychee Documentation](https://lychee.cli.rs/) -* https://playwright.dev/ +### Playwright (UI Test Framework) -## License +- [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. From 863f29f7929c87c7f4226b8a0cf6cf981e659fe6 Mon Sep 17 00:00:00 2001 From: rafaeljohn9 Date: Fri, 23 May 2025 08:48:10 +0300 Subject: [PATCH 21/21] Improve formatting and clarity of License section Promoted license section to a top-level heading. Consolidated license descriptions for source code and graphical assets. Enhanced readability and link presentation. --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fb370f1f01..b20b1231fd 100644 --- a/README.md +++ b/README.md @@ -286,8 +286,7 @@ To add a new GUI client to the [list of GUI clients](https://git-scm.com/downloa --- -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/).