git 1.19.1 → 4.4.5

data/CONTRIBUTING.md

@@ -3,161 +3,382 @@
 # @title How To Contribute
 -->
 
-# Contributing to ruby-git
-
-Thank you for your interest in contributing to the ruby-git project.
-
-This document gives the guidelines for contributing to the ruby-git project.
-These guidelines may not fit every situation.  When contributing use your best
-judgement.
-
-Propose changes to these guidelines with a pull request.
+# Contributing to the git gem
+
+- [Summary](#summary)
+- [How to contribute](#how-to-contribute)
+- [How to report an issue or request a feature](#how-to-report-an-issue-or-request-a-feature)
+- [How to submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+  - [Commit your changes to a fork of `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
+  - [Create a pull request](#create-a-pull-request)
+  - [Get your pull request reviewed](#get-your-pull-request-reviewed)
+- [Branch strategy](#branch-strategy)
+- [AI-assisted contributions](#ai-assisted-contributions)
+- [Design philosophy](#design-philosophy)
+  - [Direct mapping to git commands](#direct-mapping-to-git-commands)
+  - [Parameter naming](#parameter-naming)
+  - [Output processing](#output-processing)
+- [Coding standards](#coding-standards)
+  - [Commit message guidelines](#commit-message-guidelines)
+    - [What does this mean for contributors?](#what-does-this-mean-for-contributors)
+    - [What to know about Conventional Commits](#what-to-know-about-conventional-commits)
+  - [Unit tests](#unit-tests)
+  - [Continuous integration](#continuous-integration)
+  - [Documentation](#documentation)
+- [Building a specific version of the Git command-line](#building-a-specific-version-of-the-git-command-line)
+  - [Install pre-requisites](#install-pre-requisites)
+  - [Obtain Git source code](#obtain-git-source-code)
+  - [Build git](#build-git)
+  - [Use the new Git version](#use-the-new-git-version)
+- [Licensing](#licensing)
+
+## Summary
+
+Thank you for your interest in contributing to the `ruby-git` project.
+
+This document provides guidelines for contributing to the `ruby-git` project. While
+these guidelines may not cover every situation, we encourage you to use your best
+judgment when contributing.
+
+If you have suggestions for improving these guidelines, please propose changes via a
+pull request.
+
+Please also review and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) when
+participating in the project.
+Governance and maintainer expectations are described in
+[GOVERNANCE.md](GOVERNANCE.md).
 
 ## How to contribute
 
-You can contribute in two ways:
+You can contribute in the following ways:
 
-1. [Report an issue or make a feature request](#how-to-report-an-issue-or-make-a-feature-request)
-2. [Submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+1. [Report an issue or request a
+   feature](#how-to-report-an-issue-or-request-a-feature)
+2. [Submit a code or documentation
+   change](#how-to-submit-a-code-or-documentation-change)
 
-## How to report an issue or make a feature request
+## How to report an issue or request a feature
 
-ruby-git utilizes [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
+`ruby-git` utilizes [GitHub
+Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
 for issue tracking and feature requests.
 
-Report an issue or feature request by [creating a ruby-git Github issue](https://github.com/ruby-git/ruby-git/issues/new).
-Fill in the template to describe the issue or feature request the best you can.
+To report an issue or request a feature, please [create a `ruby-git` GitHub
+issue](https://github.com/ruby-git/ruby-git/issues/new). Fill in the template as
+thoroughly as possible to describe the issue or feature request.
 
 ## How to submit a code or documentation change
 
-There is three step process for code or documentation changes:
+There is a three-step process for submitting code or documentation changes:
 
-1. [Commit your changes to a fork of ruby-git](#commit-changes-to-a-fork-of-ruby-git)
+1. [Commit your changes to a fork of
+   `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git) using [Conventional
+   Commits](#commit-message-guidelines)
 2. [Create a pull request](#create-a-pull-request)
 3. [Get your pull request reviewed](#get-your-pull-request-reviewed)
 
-### Commit changes to a fork of ruby-git
+### Commit your changes to a fork of `ruby-git`
 
-Make your changes in a fork of the ruby-git repository.
-
-Each commit must include a [DCO sign-off](#developer-certificate-of-origin-dco)
-by adding the line `Signed-off-by: Name <email>` to the end of the commit
-message.
+Make your changes in a fork of the `ruby-git` repository.
 
 ### Create a pull request
 
-See [this article](https://help.github.com/articles/about-pull-requests/) if you
-are not familiar with GitHub Pull Requests.
+If you are not familiar with GitHub Pull Requests, please refer to [this
+article](https://help.github.com/articles/about-pull-requests/).
 
 Follow the instructions in the pull request template.
 
 ### Get your pull request reviewed
 
-Code review takes place in a GitHub pull request using the [the Github pull request review feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
+Code review takes place in a GitHub pull request using the [GitHub pull request
+review
+feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
 
 Once your pull request is ready for review, request a review from at least one
-[maintainer](MAINTAINERS.md) and any number of other contributors.
+[maintainer](MAINTAINERS.md) and any other contributors you deem necessary.
+
+During the review process, you may need to make additional commits, which should be
+squashed. Additionally, you will need to rebase your branch to the latest version of
+the target branch (e.g., `main` or `4.x`) before merging.
+
+At least one approval from a project maintainer is required before your pull request
+can be merged. The maintainer is responsible for ensuring that the pull request meets
+[the project's coding standards](#coding-standards).
+
+## Branch strategy
+
+This project maintains two active branches:
+
+- **`main`**: Active development for the next major version (v5.0.0+). This branch
+  may contain breaking changes.
+- **`4.x`**: Maintenance branch for the v4.x release series. This branch receives
+  bug fixes and backward-compatible improvements only.
+
+**Important:** Never commit directly to `main` or `4.x`. All changes must be
+submitted via pull requests from feature branches. This ensures proper code review,
+CI validation, and maintains a clean commit history.
+
+When submitting a pull request:
+
+- **New features and breaking changes**: Target the `main` branch
+- **Bug fixes**: Target `main`, and maintainers will backport to `4.x` if applicable
+- **Security fixes**: Target both branches or `4.x` if the issue only affects v4.x
+
+## AI-assisted contributions
+
+AI-assisted contributions are welcome. Please review and apply our [AI Policy](AI_POLICY.md)
+before submitting changes. You are responsible for understanding and verifying any
+AI-assisted work included in PRs and ensuring it meets our standards for quality,
+security, and licensing.
+
+## Design philosophy
+
+*Note: As of v2.x of the `git` gem, this design philosophy is aspirational. Future
+versions may include interface changes to fully align with these principles.*
+
+The `git` gem is designed as a lightweight wrapper around the `git` command-line
+tool, providing Ruby developers with a simple and intuitive interface for
+programmatically interacting with Git.
+
+This gem adheres to the "principle of least surprise," ensuring that it does not
+introduce unnecessary abstraction layers or modify Git's core functionality. Instead,
+the gem maintains a close alignment with the existing `git` command-line interface,
+avoiding extensions or alterations that could lead to unexpected behaviors.
+
+By following this philosophy, the `git` gem allows users to leverage their existing
+knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
+and paradigms.
+
+### Direct mapping to git commands
 
-During the review process, you may need to make additional commits which would
-need to be squashed.  It may also be necessary to rebase to master again if other
-changes are merged before your PR.
+Git commands are implemented within the `Git::Base` class, with each method directly
+corresponding to a `git` command. When a `Git::Base` object is instantiated via
+`Git.open`, `Git.clone`, or `Git.init`, the user can invoke these methods to interact
+with the underlying Git repository.
 
-At least one approval is required from a project maintainer before your pull
-request can be merged.  The maintainer is responsible for ensuring that the pull
-request meets [the project's coding standards](#coding-standards).
+For example, the `git add` command is implemented as `Git::Base#add`, and the `git
+ls-files` command is implemented as `Git::Base#ls_files`.
+
+When a single Git command serves multiple distinct purposes, method names within the
+`Git::Base` class should use the `git` command name as a prefix, followed by a
+descriptive suffix to indicate the specific function.
+
+For instance, `#ls_files_untracked` and `#ls_files_staged` could be used to execute
+the `git ls-files` command and return untracked and staged files, respectively.
+
+To enhance usability, aliases may be introduced to provide more user-friendly method
+names where appropriate.
+
+### Parameter naming
+
+Parameters within the `git` gem methods are named after their corresponding long
+command-line options, ensuring familiarity and ease of use for developers already
+accustomed to Git. Note that not all Git command options are supported.
+
+### Output processing
+
+The `git` gem translates the output of many Git commands into Ruby objects, making it
+easier to work with programmatically.
+
+These Ruby objects often include methods that allow for further Git operations where
+useful, providing additional functionality while staying true to the underlying Git
+behavior.
 
 ## Coding standards
 
-In order to ensure high quality, all pull requests must meet these requirements:
+To ensure high-quality contributions, all pull requests must meet the following
+requirements:
+
+### Commit message guidelines
+
+To enhance our development workflow, enable automated changelog generation, and pave
+the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional
+Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit
+messages.
+
+This structured approach to commit messages allows us to:
+
+- **Automate versioning and releases:** Tools can now automatically determine the
+  semantic version bump (patch, minor, major) based on the types of commits merged.
+- **Generate accurate changelogs:** We can automatically create and update a
+  `CHANGELOG.md` file, providing a clear history of changes for users and
+  contributors.
+- **Improve commit history readability:** A standardized format makes it easier for
+  everyone to understand the nature of changes at a glance.
+
+#### What does this mean for contributors?
+
+Going forward, all commits to this repository **MUST** adhere to the [Conventional
+Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not
+adhering to this standard will cause the CI build to fail. PRs will not be merged if
+they include non-conventional commits.
+
+A git pre-commit hook may be installed to validate your conventional commit messages
+before pushing them to GitHub by running `bin/setup` in the project root.
+
+#### What to know about Conventional Commits
+
+The simplist conventional commit is in the form `type: description` where `type`
+indicates the type of change and `description` is your usual commit message (with
+some limitations).
+
+- Types include: `feat`, `fix`, `docs`, `test`, `refactor`, and `chore`. See the full
+  list of types supported in [.commitlintrc.yml](.commitlintrc.yml).
+- The description must (1) not start with an upper case letter, (2) be no more than
+  100 characters, and (3) not end with punctuation.
+
+Examples of valid commits:
+
+- `feat: add the --merges option to Git::Lib.log`
+- `fix: exception thrown by Git::Lib.log when repo has no commits`
+- `docs: add conventional commit announcement to README.md`
 
-### 1 PR = 1 Commit
-  * All commits for a PR must be squashed into one commit
-  * To avoid an extra merge commit, the PR must be able to be merged as [a fast forward merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
-  * The easiest way to ensure a fast forward merge is to rebase your local branch
-    to the ruby-git master branch
+Commits that include breaking changes must include an exclaimation mark before the
+colon:
+
+- `feat!: removed Git::Base.commit_force`
+
+The commit messages will drive how the version is incremented for each release:
+
+- a release containing a **breaking change** will do a **major** version increment
+- a release containing a **new feature** will do a **minor** increment
+- a release containing **neither a breaking change nor a new feature** will do a
+  **patch** version increment
+
+The full conventional commit format is:
+
+```text
+<type>[optional scope][!]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- `optional body` may include multiple lines of descriptive text limited to 100 chars
+  each
+- `optional footers` only uses `BREAKING CHANGE: <description>` where description
+  should describe the nature of the backward incompatibility.
+
+Use of the `BREAKING CHANGE:` footer flags a backward incompatible change even if it
+is not flagged with an exclaimation mark after the `type`. Other footers are allowed
+by not acted upon.
+
+See [the Conventional Commits
+specification](https://www.conventionalcommits.org/en/v1.0.0/) for more details.
 
 ### Unit tests
-  * All changes must be accompanied by new or modified unit tests
-  * The entire test suite must pass when `bundle exec rake default` is run from the
-    project's local working copy.
 
-While working on specific features you can run individual test files or
-a group of tests using `bin/test`:
+- All changes must be accompanied by new or modified unit tests.
+- The entire test suite must pass when `bundle exec rake default` is run from the
+  project's local working copy.
+
+While working on specific features, you can run individual test files or a group of
+tests using `bin/test`:
 
-    # run a single file (from tests/units):
-    $ bin/test test_object
+```bash
+# run a single file (from tests/units):
+$ bin/test test_object
 
-    # run multiple files:
-    $ bin/test test_object test_archive
+# run multiple files:
+$ bin/test test_object test_archive
 
-    # run all unit tests:
-    $ bin/test
+# run all unit tests:
+$ bin/test
+
+# run unit tests with a different version of the git command line:
+$ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
+```
 
 ### Continuous integration
-  * 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.
-  * 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).
+
+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.
+
+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).
 
 ### Documentation
-  * New and updated public methods must have [YARD](https://yardoc.org/)
-    documentation added to them
-  * New and updated public facing features should be documented in the project's
-    [README.md](README.md)
 
-### Licensing sign-off
-  * Each commit must contain [the DCO sign-off](#developer-certificate-of-origin-dco)
-    in the form:  `Signed-off-by: Name <email>`
+New and updated public methods must include [YARD](https://yardoc.org/)
+documentation.
 
-## Licensing
+New and updated public-facing features should be documented in the project's
+[README.md](README.md).
 
-ruby-git uses [the MIT license](https://choosealicense.com/licenses/mit/) as
-declared in the [LICENSE](LICENSE) file.
+## Building a specific version of the Git command-line
 
-Licensing is very important to open source projects. It helps ensure the
-software continues to be available under the terms that the author desired.
+To test with a specific version of the Git command-line, you may need to build that
+version from source code. The following instructions are adapted from Atlassian’s
+[How to install Git](https://www.atlassian.com/git/tutorials/install-git) page for
+building Git on macOS.
 
-### Developer Certificate of Origin (DCO)
+### Install pre-requisites
 
-This project requires that authors have permission to submit their contributions
-under the MIT license. To make a good faith effort to ensure this, ruby-git
-requires the [Developer Certificate of Origin (DCO)](https://elinux.org/Developer_Certificate_Of_Origin)
-process be followed.
+Prerequisites only need to be installed if they are not already present.
 
-This process requires that each commit include a `Signed-off-by` line that
-indicates the author accepts the DCO.  Here is an example DCO sign-off line:
+From your terminal, install Xcode’s Command Line Tools:
 
+```shell
+xcode-select --install
 ```
-Signed-off-by: John Doe <john.doe@hisdomain.com>
+
+Install [Homebrew](http://brew.sh/) by following the instructions on the Homebrew
+page.
+
+Using Homebrew, install OpenSSL:
+
+```shell
+brew install openssl
 ```
 
-The full text of the DCO version 1.1 is below or at <http://developercertificate.org/>.
+### Obtain Git source code
+
+Download and extract the source tarball for the desired Git version from [this source
+code mirror](https://mirrors.edge.kernel.org/pub/software/scm/git/).
+
+### Build git
 
+From your terminal, change to the root directory of the extracted source code and run
+the build with following command:
+
+```shell
+NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
 ```
-Developer's Certificate of Origin 1.1
-
-By making a contribution to this project, I certify that:
-
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
-
-(b) The contribution is based upon previous work that, to the
-    best of my knowledge, is covered under an appropriate open
-    source license and I have the right under that license to
-    submit that work with modifications, whether created in whole
-    or in part by me, under the same open source license (unless
-    I am permitted to submit under a different license), as
-    Indicated in the file; or
-
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
-
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including
-    all personal information I submit with it, including my
-    sign-off) is maintained indefinitely and may be redistributed
-    consistent with this project or the open source license(s)
-    involved.
+
+The build script will place the newly compiled Git executables in the `bin-wrappers`
+directory (e.g., `bin-wrappers/git`).
+
+### Use the new Git version
+
+To configure programs that use the Git gem to utilize the newly built version, do the
+following:
+
+```ruby
+require 'git'
+
+# Set the binary path
+Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
+
+# Validate the version (if desired)
+assert_equal([2, 30, 2], Git.binary_version)
 ```
+
+Tests can be run using the newly built Git version as follows:
+
+```shell
+GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
+```
+
+Note: `GIT_PATH` refers to the directory containing the `git` executable.
+
+## Licensing
+
+`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as
+declared in the [LICENSE](LICENSE) file.
+
+Licensing is critical to open-source projects as it ensures the software remains
+available under the terms desired by the author.

data/GOVERNANCE.md

@@ -0,0 +1,106 @@
+<!--
+# @markup markdown
+# @title Governance
+-->
+
+# Governance
+
+This document explains how we steward the project with a light, principles-first
+approach: enable trusted people, minimize dormant access, and keep decisions
+transparent.
+
+## Roles
+
+A **Maintainer** is a trusted leader with write access who stewards the project's
+health and direction. Responsibilities center on triage, review, merge, and
+helping the community stay unblocked.
+
+A **Project Lead** is a maintainer with additional administrative scope (repo
+Admin, org Owner). They handle settings, secrets, access, and tie-breaks when
+needed.
+
+## Becoming a Maintainer
+
+Maintainers invite contributors who consistently ship, review, and model our
+values to become maintainers. Anyone can nominate themselves or others in an
+issue or via a private note. Current maintainers discuss nominations (see
+[Decision Making](#decision-making)) with a focus on contribution quality,
+alignment with project goals, and communication style.
+
+## Access Principles
+
+- Stewardship: Maintainer access exists to keep the project healthy and responsive.
+- Least privilege: Elevated access is temporary and kept only while it’s needed.
+- Continuity: Dormant access is paused to protect the project and unblock
+  contributors.
+- Respect: Status changes are transparent, reversible, and acknowledge past
+  contributions.
+
+## How We Apply Them
+
+- Staying active: Maintainers keep elevated access while participating (shipping,
+  reviewing, triaging, or governance).
+- When access is paused: If there’s no project activity for about a year, we’ll
+  check in. If we don’t hear back after a short window, we move the maintainer to
+  Emeritus and pause Owner/Admin/Write/package access (including CODEOWNERS
+  entries).
+- Coming back: Emeritus maintainers can be re-added quickly after a brief period of
+  renewed participation to refresh context.
+- Recognition: Emeritus maintainers remain listed to honor prior contributions.
+
+Access changes are communicated openly (e.g., PRs or issues) and reflected in the
+Maintainers list.
+
+## Decision Making
+
+Decisions are usually made by consensus among the active maintainers. If consensus
+cannot be reached, the decision is made by a majority vote. If a vote results in a
+tie, the Project Lead has the final say.
+
+## Continuity
+
+The project must be able to ship releases and respond to security issues even if
+individual maintainers become unavailable.
+
+### RubyGems Ownership
+
+RubyGems ownership (the ability to push new gem versions) is granted to a subset
+of active maintainers—typically the Project Lead and at least one other
+maintainer—to balance security with continuity. Not all maintainers require
+RubyGems access.
+
+RubyGems owners follow the same activity principles as other elevated access: if
+an owner becomes inactive, their ownership is paused alongside other permissions.
+
+### Minimum Thresholds
+
+To avoid single points of failure:
+
+- At least two active maintainers should have RubyGems ownership for the `git` gem.
+- At least two active maintainers should have GitHub org Owner or repo Admin
+  access.
+
+If thresholds drop below these levels, remaining maintainers should prioritize
+onboarding or re-activating someone to restore redundancy.
+
+### Access Audits
+
+Periodically (at least annually), maintainers review access across all systems:
+
+- GitHub organization membership and roles
+- GitHub repository admin/write permissions
+- RubyGems gem ownership
+- GitHub Actions release automation: PATs/OIDC tokens (e.g., `AUTO_RELEASE_TOKEN` scope),
+  environment protection rules/approvers for RubyGems deployments, and any OIDC
+  trust configuration
+
+The Project Lead (or a delegated maintainer) schedules and drives this review so
+continuity checks do not slip.
+
+Audits ensure access reflects current activity and that continuity thresholds are
+met.
+
+## Code of Conduct
+
+All maintainers and contributors must adhere to the project's [Code of
+Conduct](./CODE_OF_CONDUCT.md).

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2008 Scott Chacon
+Copyright (c) 2008 Scott Chacon, 2020 James Couball, and the ruby-git contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/MAINTAINERS.md

@@ -5,8 +5,21 @@
 
 # Maintainers
 
-When making changes in this repository, one of the maintainers below must review and approve your pull request.
+See [GOVERNANCE.md](GOVERNANCE.md) for a definition of the Maintainer role.
 
-* [James Couball](https://github.com/jcouball)
-* [Frank Throckmorton](https://github.com/frankthrock)
-* [Per Lundberg](https://github.com/perlun)
+## Active Maintainers
+
+- [James Couball](https://github.com/jcouball) (Project Lead)
+- [Frank Throckmorton](https://github.com/frankthrock)
+
+## Maintainers Emeritus (Alumni)
+
+**Maintainers Emeritus** are former maintainers who are no longer active. We honor
+their past contributions.
+
+- [Per Lundberg](https://github.com/perlun)
+- [Vern Burton](https://github.com/tarcinil)
+- [Daniel Perez](https://github.com/dpmex4527)
+- [Richard Vodden](https://github.com/rvodden)
+- [Roberto Decurnex](https://github.com/robertodecurnex)
+- [Scott Chacon](https://github.com/schacon) (original creator)