Skip to content

Commit 2e23d47

Browse files
committed
Update instructions for building a specific version of Git
1 parent 70565e3 commit 2e23d47

File tree

1 file changed

+69
-44
lines changed

1 file changed

+69
-44
lines changed

CONTRIBUTING.md

Lines changed: 69 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,12 @@
2121
* [Unit tests](#unit-tests)
2222
* [Continuous integration](#continuous-integration)
2323
* [Documentation](#documentation)
24+
* [Building a specific version of the Git command-line](#building-a-specific-version-of-the-git-command-line)
25+
* [Install pre-requisites](#install-pre-requisites)
26+
* [Obtain Git source code](#obtain-git-source-code)
27+
* [Build git](#build-git)
28+
* [Use the new Git version](#use-the-new-git-version)
2429
* [Licensing](#licensing)
25-
* [Building a specific version of the git command-line](#building-a-specific-version-of-the-git-command-line)
2630

2731
## Summary
2832

@@ -182,72 +186,93 @@ $ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
182186

183187
### Continuous integration
184188

185-
All tests must pass in the project's [GitHub Continuous Integration build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the pull request will be merged.
189+
All tests must pass in the project's [GitHub Continuous Integration
190+
build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the
191+
pull request will be merged.
186192

187-
The [Continuous Integration workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml) runs both `bundle exec rake default` and `bundle exec rake test:gem` from the project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
193+
The [Continuous Integration
194+
workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml)
195+
runs both `bundle exec rake default` and `bundle exec rake test:gem` from the
196+
project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
188197

189198
### Documentation
190199

191-
New and updated public methods must include [YARD](https://yardoc.org/) documentation.
200+
New and updated public methods must include [YARD](https://yardoc.org/)
201+
documentation.
192202

193-
New and updated public-facing features should be documented in the project's [README.md](README.md).
203+
New and updated public-facing features should be documented in the project's
204+
[README.md](README.md).
194205

195-
## Licensing
206+
## Building a specific version of the Git command-line
207+
208+
To test with a specific version of the Git command-line, you may need to build that
209+
version from source code. The following instructions are adapted from Atlassian’s
210+
[How to install Git](https://www.atlassian.com/git/tutorials/install-git) page for
211+
building Git on macOS.
212+
213+
### Install pre-requisites
214+
215+
Prerequisites only need to be installed if they are not already present.
216+
217+
From your terminal, install Xcode’s Command Line Tools:
218+
219+
```shell
220+
xcode-select --install
221+
```
196222

197-
`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as declared in the [LICENSE](LICENSE) file.
223+
Install [Homebrew](http://brew.sh/) by following the instructions on the Homebrew
224+
page.
198225

199-
Licensing is critical to open-source projects as it ensures the software remains available under the terms desired by the author.
226+
Using Homebrew, install OpenSSL:
200227

201-
## Building a specific version of the git command-line
228+
```shell
229+
brew install openssl
230+
```
202231

203-
For testing, it is helpful to be able to build and use a specific version of the git
204-
command-line with the git gem.
232+
### Obtain Git source code
205233

206-
Instructions to do this can be found on the page [How to install
207-
Git](https://www.atlassian.com/git/tutorials/install-git) from Atlassian.
234+
Download and extract the source tarball for the desired Git version from [this source
235+
code mirror](https://mirrors.edge.kernel.org/pub/software/scm/git/).
208236

209-
I have successfully used the instructions in the section "Build Git from source on OS
210-
X" on MacOS 15. I have copied the following instructions from the Atlassian page.
237+
### Build git
211238

212-
1. From your terminal install XCode's Command Line Tools:
239+
From your terminal, change to the root directory of the extracted source code and run
240+
the build with following command:
213241

214-
```shell
215-
xcode-select --install
216-
```
242+
```shell
243+
NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
244+
```
217245

218-
2. Install [Homebrew](http://brew.sh/)
246+
The build script will place the newly compiled Git executables in the `bin-wrappers`
247+
directory (e.g., `bin-wrappers/git`).
219248

220-
3. Using Homebrew, install openssl:
249+
### Use the new Git version
221250

222-
```shell
223-
brew install openssl
224-
```
251+
To configure programs that use the Git gem to utilize the newly built version, do the
252+
following:
225253

226-
4. Download the source tarball for the desired version from
227-
[here](https://mirrors.edge.kernel.org/pub/software/scm/git/) and extract it
254+
```ruby
255+
require 'git'
228256

229-
5. Build Git run make with the following command:
257+
# Set the binary path
258+
Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
230259

231-
```shell
232-
NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
233-
```
260+
# Validate the version (if desired)
261+
assert_equal([2, 30, 2], Git.binary_version)
262+
```
234263

235-
6. The newly built git command will be found at `bin-wrappers/git`
264+
Tests can be run using the newly built Git version as follows:
236265

237-
7. Use the new git command-line version
266+
```shell
267+
GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
268+
```
238269

239-
Configure the git gem to use the newly built version:
270+
Note: `GIT_PATH` refers to the directory containing the `git` executable.
240271

241-
```ruby
242-
require 'git'
243-
# set the binary path
244-
Git.configure { |config| config.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
245-
# validate the version
246-
assert_equal([2, 30, 2], Git.binary_version)
247-
```
272+
## Licensing
248273

249-
or run tests using the newly built version:
274+
`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as
275+
declared in the [LICENSE](LICENSE) file.
250276

251-
```shell
252-
GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
253-
```
277+
Licensing is critical to open-source projects as it ensures the software remains
278+
available under the terms desired by the author.

0 commit comments

Comments
 (0)