git 4.4.6 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.yardopts +1 -0
- data/CHANGELOG.md +348 -39
- data/CONTRIBUTING.md +1014 -144
- data/README.md +386 -504
- data/UPGRADING.md +1822 -0
- data/git.gemspec +102 -22
- data/lib/git/author_info.rb +65 -0
- data/lib/git/branch_delete_failure.rb +34 -0
- data/lib/git/branch_delete_result.rb +66 -0
- data/lib/git/branch_info.rb +237 -0
- data/lib/git/command_line/base.rb +247 -0
- data/lib/git/command_line/capturing.rb +308 -0
- data/lib/git/command_line/result.rb +88 -0
- data/lib/git/command_line/streaming.rb +236 -0
- data/lib/git/command_line.rb +45 -323
- data/lib/git/commands/add.rb +139 -0
- data/lib/git/commands/am/abort.rb +43 -0
- data/lib/git/commands/am/apply.rb +263 -0
- data/lib/git/commands/am/continue.rb +43 -0
- data/lib/git/commands/am/quit.rb +43 -0
- data/lib/git/commands/am/retry.rb +49 -0
- data/lib/git/commands/am/show_current_patch.rb +64 -0
- data/lib/git/commands/am/skip.rb +42 -0
- data/lib/git/commands/am.rb +33 -0
- data/lib/git/commands/apply.rb +242 -0
- data/lib/git/commands/archive/list_formats.rb +46 -0
- data/lib/git/commands/archive.rb +145 -0
- data/lib/git/commands/arguments.rb +4521 -0
- data/lib/git/commands/base.rb +522 -0
- data/lib/git/commands/branch/copy.rb +102 -0
- data/lib/git/commands/branch/create.rb +177 -0
- data/lib/git/commands/branch/delete.rb +88 -0
- data/lib/git/commands/branch/list.rb +178 -0
- data/lib/git/commands/branch/move.rb +102 -0
- data/lib/git/commands/branch/set_upstream.rb +86 -0
- data/lib/git/commands/branch/show_current.rb +49 -0
- data/lib/git/commands/branch/unset_upstream.rb +53 -0
- data/lib/git/commands/branch.rb +34 -0
- data/lib/git/commands/cat_file/batch.rb +385 -0
- data/lib/git/commands/cat_file/filtered.rb +105 -0
- data/lib/git/commands/cat_file/raw.rb +203 -0
- data/lib/git/commands/cat_file.rb +49 -0
- data/lib/git/commands/checkout/branch.rb +153 -0
- data/lib/git/commands/checkout/files.rb +116 -0
- data/lib/git/commands/checkout.rb +38 -0
- data/lib/git/commands/checkout_index.rb +106 -0
- data/lib/git/commands/clean.rb +102 -0
- data/lib/git/commands/clone.rb +241 -0
- data/lib/git/commands/commit.rb +273 -0
- data/lib/git/commands/commit_tree.rb +101 -0
- data/lib/git/commands/config_option_syntax/add.rb +86 -0
- data/lib/git/commands/config_option_syntax/get.rb +121 -0
- data/lib/git/commands/config_option_syntax/get_all.rb +118 -0
- data/lib/git/commands/config_option_syntax/get_color.rb +95 -0
- data/lib/git/commands/config_option_syntax/get_color_bool.rb +96 -0
- data/lib/git/commands/config_option_syntax/get_regexp.rb +119 -0
- data/lib/git/commands/config_option_syntax/get_urlmatch.rb +111 -0
- data/lib/git/commands/config_option_syntax/list.rb +111 -0
- data/lib/git/commands/config_option_syntax/remove_section.rb +79 -0
- data/lib/git/commands/config_option_syntax/rename_section.rb +83 -0
- data/lib/git/commands/config_option_syntax/replace_all.rb +109 -0
- data/lib/git/commands/config_option_syntax/set.rb +119 -0
- data/lib/git/commands/config_option_syntax/unset.rb +92 -0
- data/lib/git/commands/config_option_syntax/unset_all.rb +94 -0
- data/lib/git/commands/config_option_syntax.rb +56 -0
- data/lib/git/commands/describe.rb +156 -0
- data/lib/git/commands/diff.rb +657 -0
- data/lib/git/commands/diff_files.rb +519 -0
- data/lib/git/commands/diff_index.rb +499 -0
- data/lib/git/commands/fetch.rb +354 -0
- data/lib/git/commands/fsck.rb +138 -0
- data/lib/git/commands/gc.rb +134 -0
- data/lib/git/commands/grep.rb +339 -0
- data/lib/git/commands/init.rb +101 -0
- data/lib/git/commands/log.rb +634 -0
- data/lib/git/commands/ls_files.rb +195 -0
- data/lib/git/commands/ls_remote.rb +161 -0
- data/lib/git/commands/ls_tree.rb +135 -0
- data/lib/git/commands/maintenance/register.rb +73 -0
- data/lib/git/commands/maintenance/run.rb +105 -0
- data/lib/git/commands/maintenance/start.rb +67 -0
- data/lib/git/commands/maintenance/stop.rb +56 -0
- data/lib/git/commands/maintenance/unregister.rb +80 -0
- data/lib/git/commands/maintenance.rb +29 -0
- data/lib/git/commands/merge/abort.rb +44 -0
- data/lib/git/commands/merge/continue.rb +44 -0
- data/lib/git/commands/merge/quit.rb +46 -0
- data/lib/git/commands/merge/start.rb +250 -0
- data/lib/git/commands/merge.rb +28 -0
- data/lib/git/commands/merge_base.rb +91 -0
- data/lib/git/commands/mv.rb +82 -0
- data/lib/git/commands/name_rev.rb +119 -0
- data/lib/git/commands/pull.rb +382 -0
- data/lib/git/commands/push.rb +251 -0
- data/lib/git/commands/read_tree.rb +154 -0
- data/lib/git/commands/remote/add.rb +96 -0
- data/lib/git/commands/remote/get_url.rb +68 -0
- data/lib/git/commands/remote/list.rb +56 -0
- data/lib/git/commands/remote/prune.rb +63 -0
- data/lib/git/commands/remote/remove.rb +52 -0
- data/lib/git/commands/remote/rename.rb +76 -0
- data/lib/git/commands/remote/set_branches.rb +70 -0
- data/lib/git/commands/remote/set_head.rb +89 -0
- data/lib/git/commands/remote/set_url.rb +78 -0
- data/lib/git/commands/remote/set_url_add.rb +70 -0
- data/lib/git/commands/remote/set_url_delete.rb +71 -0
- data/lib/git/commands/remote/show.rb +77 -0
- data/lib/git/commands/remote/update.rb +79 -0
- data/lib/git/commands/remote.rb +42 -0
- data/lib/git/commands/repack.rb +281 -0
- data/lib/git/commands/reset.rb +154 -0
- data/lib/git/commands/rev_parse.rb +304 -0
- data/lib/git/commands/revert/abort.rb +45 -0
- data/lib/git/commands/revert/continue.rb +62 -0
- data/lib/git/commands/revert/quit.rb +47 -0
- data/lib/git/commands/revert/skip.rb +44 -0
- data/lib/git/commands/revert/start.rb +158 -0
- data/lib/git/commands/revert.rb +29 -0
- data/lib/git/commands/rm.rb +113 -0
- data/lib/git/commands/show.rb +632 -0
- data/lib/git/commands/show_ref/exclude_existing.rb +119 -0
- data/lib/git/commands/show_ref/exists.rb +75 -0
- data/lib/git/commands/show_ref/list.rb +149 -0
- data/lib/git/commands/show_ref/verify.rb +122 -0
- data/lib/git/commands/show_ref.rb +42 -0
- data/lib/git/commands/stash/apply.rb +81 -0
- data/lib/git/commands/stash/branch.rb +67 -0
- data/lib/git/commands/stash/clear.rb +43 -0
- data/lib/git/commands/stash/create.rb +60 -0
- data/lib/git/commands/stash/drop.rb +73 -0
- data/lib/git/commands/stash/list.rb +43 -0
- data/lib/git/commands/stash/pop.rb +87 -0
- data/lib/git/commands/stash/push.rb +112 -0
- data/lib/git/commands/stash/show.rb +158 -0
- data/lib/git/commands/stash/store.rb +72 -0
- data/lib/git/commands/stash.rb +38 -0
- data/lib/git/commands/status.rb +174 -0
- data/lib/git/commands/symbolic_ref/delete.rb +72 -0
- data/lib/git/commands/symbolic_ref/read.rb +99 -0
- data/lib/git/commands/symbolic_ref/update.rb +79 -0
- data/lib/git/commands/symbolic_ref.rb +38 -0
- data/lib/git/commands/tag/create.rb +142 -0
- data/lib/git/commands/tag/delete.rb +57 -0
- data/lib/git/commands/tag/list.rb +146 -0
- data/lib/git/commands/tag/verify.rb +71 -0
- data/lib/git/commands/tag.rb +26 -0
- data/lib/git/commands/update_ref/batch.rb +145 -0
- data/lib/git/commands/update_ref/delete.rb +90 -0
- data/lib/git/commands/update_ref/update.rb +103 -0
- data/lib/git/commands/update_ref.rb +42 -0
- data/lib/git/commands/version.rb +60 -0
- data/lib/git/commands/worktree/add.rb +139 -0
- data/lib/git/commands/worktree/list.rb +64 -0
- data/lib/git/commands/worktree/lock.rb +58 -0
- data/lib/git/commands/worktree/management_base.rb +51 -0
- data/lib/git/commands/worktree/move.rb +66 -0
- data/lib/git/commands/worktree/prune.rb +67 -0
- data/lib/git/commands/worktree/remove.rb +63 -0
- data/lib/git/commands/worktree/repair.rb +71 -0
- data/lib/git/commands/worktree/unlock.rb +47 -0
- data/lib/git/commands/worktree.rb +43 -0
- data/lib/git/commands/write_tree.rb +68 -0
- data/lib/git/commands.rb +88 -0
- data/lib/git/config.rb +64 -1
- data/lib/git/config_entry_info.rb +106 -0
- data/lib/git/configuring.rb +795 -0
- data/lib/git/detached_head_info.rb +57 -0
- data/lib/git/diff.rb +295 -12
- data/lib/git/diff_file_numstat_info.rb +31 -0
- data/lib/git/diff_file_patch_info.rb +136 -0
- data/lib/git/diff_file_raw_info.rb +129 -0
- data/lib/git/diff_info.rb +162 -0
- data/lib/git/diff_path_status.rb +80 -19
- data/lib/git/diff_result.rb +34 -0
- data/lib/git/diff_stats.rb +66 -14
- data/lib/git/dirstat_info.rb +102 -0
- data/lib/git/encoding_utils.rb +57 -1
- data/lib/git/errors.rb +107 -26
- data/lib/git/escaped_path.rb +55 -3
- data/lib/git/execution_context/global.rb +31 -0
- data/lib/git/execution_context/repository.rb +151 -0
- data/lib/git/execution_context.rb +559 -0
- data/lib/git/factories.rb +1049 -0
- data/lib/git/file_ref.rb +77 -0
- data/lib/git/fsck_object.rb +17 -9
- data/lib/git/fsck_result.rb +27 -16
- data/lib/git/log.rb +172 -65
- data/lib/git/object.rb +323 -108
- data/lib/git/parsers/branch.rb +240 -0
- data/lib/git/parsers/cat_file.rb +111 -0
- data/lib/git/parsers/config_entry.rb +110 -0
- data/lib/git/parsers/diff.rb +792 -0
- data/lib/git/parsers/fsck.rb +144 -0
- data/lib/git/parsers/grep.rb +42 -0
- data/lib/git/parsers/ls_remote.rb +79 -0
- data/lib/git/parsers/ls_tree.rb +58 -0
- data/lib/git/parsers/remote.rb +162 -0
- data/lib/git/parsers/stash.rb +292 -0
- data/lib/git/parsers/status.rb +251 -0
- data/lib/git/parsers/tag.rb +341 -0
- data/lib/git/parsers/worktree.rb +185 -0
- data/lib/git/path_resolver.rb +274 -0
- data/lib/git/remote_info.rb +203 -0
- data/lib/git/repository/branching.rb +796 -0
- data/lib/git/repository/committing.rb +221 -0
- data/lib/git/repository/context_helpers.rb +454 -0
- data/lib/git/repository/diffing.rb +743 -0
- data/lib/git/repository/inspecting.rb +252 -0
- data/lib/git/repository/logging.rb +410 -0
- data/lib/git/repository/maintenance.rb +65 -0
- data/lib/git/repository/merging.rb +429 -0
- data/lib/git/repository/object_operations.rb +1334 -0
- data/lib/git/repository/remote_operations.rb +772 -0
- data/lib/git/repository/shared_private.rb +120 -0
- data/lib/git/repository/staging.rb +409 -0
- data/lib/git/repository/stashing.rb +619 -0
- data/lib/git/repository/status_operations.rb +196 -0
- data/lib/git/repository/worktree_operations.rb +252 -0
- data/lib/git/repository.rb +204 -1
- data/lib/git/stash_info.rb +102 -0
- data/lib/git/status_file_info.rb +258 -0
- data/lib/git/status_info.rb +189 -0
- data/lib/git/system_call_guard.rb +95 -0
- data/lib/git/tag_delete_failure.rb +34 -0
- data/lib/git/tag_delete_result.rb +66 -0
- data/lib/git/tag_info.rb +99 -0
- data/lib/git/url.rb +12 -5
- data/lib/git/version.rb +111 -2
- data/lib/git/version_constraint.rb +85 -0
- data/lib/git/worktree_info.rb +128 -0
- data/lib/git.rb +319 -332
- metadata +318 -74
- data/.commitlintrc.yml +0 -38
- data/.github/copilot-instructions.md +0 -2733
- data/.github/issue_template.md +0 -15
- data/.github/pull_request_template.md +0 -17
- data/.github/workflows/continuous_integration.yml +0 -120
- data/.github/workflows/enforce_conventional_commits.yml +0 -29
- data/.github/workflows/experimental_continuous_integration.yml +0 -59
- data/.github/workflows/release.yml +0 -53
- data/.gitignore +0 -15
- data/.husky/commit-msg +0 -1
- data/.release-please-manifest.json +0 -3
- data/.rubocop.yml +0 -55
- data/.rubocop_todo.yml +0 -12
- data/Gemfile +0 -5
- data/Rakefile +0 -18
- data/lib/git/args_builder.rb +0 -111
- data/lib/git/author.rb +0 -16
- data/lib/git/base.rb +0 -1140
- data/lib/git/branch.rb +0 -423
- data/lib/git/branches.rb +0 -68
- data/lib/git/command_line_result.rb +0 -92
- data/lib/git/index.rb +0 -6
- data/lib/git/lib.rb +0 -2333
- data/lib/git/path.rb +0 -38
- data/lib/git/remote.rb +0 -39
- data/lib/git/stash.rb +0 -26
- data/lib/git/stashes.rb +0 -56
- data/lib/git/status.rb +0 -159
- data/lib/git/working_directory.rb +0 -6
- data/lib/git/worktree.rb +0 -39
- data/lib/git/worktrees.rb +0 -47
- data/package.json +0 -10
- data/redesign/1_architecture_existing.md +0 -66
- data/redesign/2_architecture_redesign.md +0 -130
- data/redesign/3_architecture_implementation.md +0 -138
- data/redesign/index.md +0 -34
- data/release-please-config.json +0 -36
- data/tasks/gem_tasks.rake +0 -10
- data/tasks/rubocop.rake +0 -12
- data/tasks/test.rake +0 -13
- data/tasks/test_gem.rake +0 -12
- data/tasks/yard.rake +0 -23
data/README.md
CHANGED
|
@@ -3,45 +3,59 @@
|
|
|
3
3
|
# @title README
|
|
4
4
|
-->
|
|
5
5
|
|
|
6
|
-
# The
|
|
6
|
+
# The git gem
|
|
7
7
|
|
|
8
8
|
[](https://badge.fury.io/rb/git)
|
|
9
|
+
[](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml)
|
|
9
10
|
[](https://rubydoc.info/gems/git/)
|
|
10
11
|
[](https://rubydoc.info/gems/git/file/CHANGELOG.md)
|
|
12
|
-
[](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
|
|
14
13
|
[](https://conventionalcommits.org)
|
|
16
|
-
[](AI_POLICY.md)
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
|
|
18
|
+
> **v6.0.0 is released.** It is a major release that removes the APIs deprecated
|
|
19
|
+
> during v5.x, raises the minimum Ruby version to 3.3 and the minimum git version
|
|
20
|
+
> to 2.43.0, and changes a few behaviors that had no deprecation path. See
|
|
21
|
+
> [Upgrading to v6.x](UPGRADING.md#upgrading-to-v6x) for the migration guide and
|
|
22
|
+
> [CHANGELOG.md](CHANGELOG.md) for full release notes. v5.x continues to receive
|
|
23
|
+
> fixes from the `5.x` branch.
|
|
17
24
|
|
|
18
25
|
- [Summary](#summary)
|
|
19
26
|
- [Install](#install)
|
|
20
|
-
- [Quick
|
|
27
|
+
- [Quick start](#quick-start)
|
|
21
28
|
- [Examples](#examples)
|
|
22
|
-
- [
|
|
23
|
-
- [
|
|
24
|
-
- [
|
|
25
|
-
|
|
26
|
-
- [
|
|
27
|
-
- [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
|
|
29
|
+
- [Gem configuration](#gem-configuration)
|
|
30
|
+
- [Git configuration](#git-configuration)
|
|
31
|
+
- [Full API](#full-api)
|
|
32
|
+
- [Errors raised by this gem](#errors-raised-by-this-gem)
|
|
33
|
+
- [Specifying and handling timeouts](#specifying-and-handling-timeouts)
|
|
28
34
|
- [Deprecations](#deprecations)
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
|
|
37
|
-
- [
|
|
35
|
+
- [Platform limitations](#platform-limitations)
|
|
36
|
+
- [Regex metacharacters on Git for Windows](#regex-metacharacters-on-git-for-windows)
|
|
37
|
+
- [Project policies](#project-policies)
|
|
38
|
+
- [Ruby version support policy](#ruby-version-support-policy)
|
|
39
|
+
- [Git version support policy](#git-version-support-policy)
|
|
40
|
+
- [Deprecation policy](#deprecation-policy)
|
|
41
|
+
- [Release support policy](#release-support-policy)
|
|
42
|
+
- [Project announcements](#project-announcements)
|
|
43
|
+
- [2026-09-04: v5.x releases move to the 5.x branch](#2026-09-04-v5x-releases-move-to-the-5x-branch)
|
|
44
|
+
- [2026-09-04: Retired branches deleted](#2026-09-04-retired-branches-deleted)
|
|
45
|
+
- [2026-08-23: v5.x deprecations and the v6.0.0 roadmap](#2026-08-23-v5x-deprecations-and-the-v600-roadmap)
|
|
46
|
+
- [2026-07-28: v5.0.0 released](#2026-07-28-v500-released)
|
|
47
|
+
- [2026-01-07: AI policy introduced](#2026-01-07-ai-policy-introduced)
|
|
48
|
+
- [2025-07-09: Architectural redesign](#2025-07-09-architectural-redesign)
|
|
49
|
+
- [2025-07-07: We now use RuboCop](#2025-07-07-we-now-use-rubocop)
|
|
50
|
+
- [2025-06-06: Default branch rename](#2025-06-06-default-branch-rename)
|
|
51
|
+
- [2025-05-15: We've switched to Conventional Commits](#2025-05-15-weve-switched-to-conventional-commits)
|
|
38
52
|
|
|
39
53
|
## Summary
|
|
40
54
|
|
|
41
55
|
The [git gem](https://rubygems.org/gems/git) provides a Ruby interface to the `git`
|
|
42
56
|
command line.
|
|
43
57
|
|
|
44
|
-
Get
|
|
58
|
+
Get a repository object by:
|
|
45
59
|
|
|
46
60
|
- opening an existing working copy with
|
|
47
61
|
[Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
|
|
@@ -50,44 +64,36 @@ Get started by obtaining a repository object by:
|
|
|
50
64
|
- cloning a repository with
|
|
51
65
|
[Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
|
|
52
66
|
|
|
53
|
-
|
|
54
|
-
|
|
67
|
+
[Git::Repository](https://rubydoc.info/gems/git/Git/Repository) documents the
|
|
68
|
+
methods you can call on a repository object.
|
|
55
69
|
|
|
56
70
|
## Install
|
|
57
71
|
|
|
72
|
+
This gem is a wrapper around the `git` command line, so a `git` executable (version
|
|
73
|
+
2.43.0 or greater) must be installed and on your `PATH`. See the [Git version support
|
|
74
|
+
policy](#git-version-support-policy) for details.
|
|
75
|
+
|
|
58
76
|
Install the gem and add to the application's Gemfile by executing:
|
|
59
77
|
|
|
60
78
|
```shell
|
|
61
79
|
bundle add git
|
|
62
80
|
```
|
|
63
81
|
|
|
64
|
-
to install
|
|
65
|
-
|
|
66
|
-
```shell
|
|
67
|
-
bundle add git --version "~> 1.19"
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
If bundler is not being used to manage dependencies, install the gem by executing:
|
|
82
|
+
If you are not using bundler to manage dependencies, install the gem by executing:
|
|
71
83
|
|
|
72
84
|
```shell
|
|
73
85
|
gem install git
|
|
74
86
|
```
|
|
75
87
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
```shell
|
|
79
|
-
gem install git --version "~> 1.19"
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
## Quick Start
|
|
88
|
+
## Quick start
|
|
83
89
|
|
|
84
90
|
All functionality for this gem starts with the top-level
|
|
85
|
-
[`Git`](https://rubydoc.info/gems/git/Git) module.
|
|
86
|
-
|
|
91
|
+
[`Git`](https://rubydoc.info/gems/git/Git) module. Use this module to run non-repo
|
|
92
|
+
scoped `git` commands such as `config`.
|
|
87
93
|
|
|
88
94
|
The `Git` module also has factory methods such as `open`, `clone`, and `init` which
|
|
89
|
-
return a [`Git::
|
|
90
|
-
`Git::
|
|
95
|
+
return a [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) object. Use
|
|
96
|
+
the `Git::Repository` object to run repo-specific `git` commands such as `add`,
|
|
91
97
|
`commit`, `push`, and `log`.
|
|
92
98
|
|
|
93
99
|
Clone, read status, and log:
|
|
@@ -96,8 +102,8 @@ Clone, read status, and log:
|
|
|
96
102
|
require 'git'
|
|
97
103
|
|
|
98
104
|
repo = Git.clone('https://github.com/ruby-git/ruby-git.git', 'ruby-git')
|
|
99
|
-
repo.
|
|
100
|
-
repo.log(5).each { |c| puts c.message }
|
|
105
|
+
repo.status_info.changed.each_key { |path| puts "changed: #{path}" }
|
|
106
|
+
repo.log(5).execute.each { |c| puts c.message }
|
|
101
107
|
```
|
|
102
108
|
|
|
103
109
|
Open an existing repo and commit:
|
|
@@ -123,25 +129,10 @@ repo.commit('initial commit')
|
|
|
123
129
|
|
|
124
130
|
## Examples
|
|
125
131
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
### Configuration
|
|
130
|
-
|
|
131
|
-
Configure the `git` command line:
|
|
132
|
+
These examples cover configuring the gem and git itself. For the full set of
|
|
133
|
+
repository operations, see [Full API](#full-api) below.
|
|
132
134
|
|
|
133
|
-
|
|
134
|
-
# Global config (in ~/.gitconfig)
|
|
135
|
-
settings = Git.global_config # returns a Hash
|
|
136
|
-
username = Git.global_config('user.email')
|
|
137
|
-
Git.global_config('user.email', 'user@example.com')
|
|
138
|
-
|
|
139
|
-
# Repository config
|
|
140
|
-
repo = Git.open('path/to/repo')
|
|
141
|
-
settings = repo.config # returns a Hash
|
|
142
|
-
username = repo.config('user.email')
|
|
143
|
-
repo.config('user.email', 'anotheruser@example.com')
|
|
144
|
-
```
|
|
135
|
+
### Gem configuration
|
|
145
136
|
|
|
146
137
|
Configure the git gem:
|
|
147
138
|
|
|
@@ -157,14 +148,14 @@ Git.config.binary_path = '/usr/local/bin/git'
|
|
|
157
148
|
Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
|
|
158
149
|
```
|
|
159
150
|
|
|
160
|
-
|
|
151
|
+
How SSH configuration is determined:
|
|
161
152
|
|
|
162
|
-
- If
|
|
163
|
-
|c| c.git_ssh = ... }`)
|
|
164
|
-
- If `git_ssh: nil
|
|
165
|
-
|
|
166
|
-
- If `git_ssh` is a non-empty string,
|
|
167
|
-
global config
|
|
153
|
+
- If the API call does not specify `git_ssh`, the gem uses the global config
|
|
154
|
+
(`Git.configure { |c| c.git_ssh = ... }`).
|
|
155
|
+
- If the call specifies `git_ssh: nil`, the gem disables SSH for that instance and
|
|
156
|
+
uses no SSH key or script.
|
|
157
|
+
- If `git_ssh` is a non-empty string, the gem uses it for that instance instead of
|
|
158
|
+
the global config.
|
|
168
159
|
|
|
169
160
|
You can also specify a custom SSH script on a per-repository basis:
|
|
170
161
|
|
|
@@ -180,382 +171,92 @@ git = Git.clone('git@github.com:user/repo.git', 'local-dir',
|
|
|
180
171
|
git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
|
|
181
172
|
```
|
|
182
173
|
|
|
183
|
-
This
|
|
184
|
-
|
|
174
|
+
This matters in multi-threaded applications where different repositories need
|
|
175
|
+
different SSH credentials.
|
|
185
176
|
|
|
186
|
-
###
|
|
177
|
+
### Git configuration
|
|
187
178
|
|
|
188
|
-
|
|
179
|
+
Read and set `git` configuration values (via `git config`):
|
|
189
180
|
|
|
190
181
|
```ruby
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
repo.repo
|
|
197
|
-
repo.dir
|
|
198
|
-
|
|
199
|
-
# ls-tree with recursion into subtrees (list files)
|
|
200
|
-
repo.ls_tree("HEAD", recursive: true)
|
|
201
|
-
|
|
202
|
-
# log - returns a Git::Log object, which is an Enumerator of Git::Commit objects
|
|
203
|
-
# default configuration returns a max of 30 commits
|
|
204
|
-
repo.log
|
|
205
|
-
repo.log(200) # 200 most recent commits
|
|
206
|
-
repo.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
|
|
207
|
-
repo.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
|
|
208
|
-
repo.log.between('v2.5', 'v2.6')
|
|
209
|
-
repo.log.each {|l| puts l.sha }
|
|
210
|
-
repo.gblob('v2.5:Makefile').log.since('2 weeks ago')
|
|
211
|
-
|
|
212
|
-
repo.object('HEAD^').to_s # git show / git rev-parse
|
|
213
|
-
repo.object('HEAD^').contents
|
|
214
|
-
repo.object('v2.5:Makefile').size
|
|
215
|
-
repo.object('v2.5:Makefile').sha
|
|
216
|
-
|
|
217
|
-
repo.gtree(treeish)
|
|
218
|
-
repo.gblob(treeish)
|
|
219
|
-
repo.gcommit(treeish)
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
commit = repo.gcommit('1cc8667014381')
|
|
223
|
-
|
|
224
|
-
commit.gtree
|
|
225
|
-
commit.parent.sha
|
|
226
|
-
commit.parents.size
|
|
227
|
-
commit.author.name
|
|
228
|
-
commit.author.email
|
|
229
|
-
commit.author.date.strftime("%m-%d-%y")
|
|
230
|
-
commit.committer.name
|
|
231
|
-
commit.date.strftime("%m-%d-%y")
|
|
232
|
-
commit.message
|
|
233
|
-
|
|
234
|
-
tree = repo.gtree("HEAD^{tree}")
|
|
235
|
-
|
|
236
|
-
tree.blobs
|
|
237
|
-
tree.subtrees
|
|
238
|
-
tree.children # blobs and subtrees
|
|
239
|
-
|
|
240
|
-
repo.rev_parse('v2.0.0:README.md')
|
|
241
|
-
|
|
242
|
-
repo.branches # returns Git::Branch objects
|
|
243
|
-
repo.branches.local
|
|
244
|
-
repo.current_branch
|
|
245
|
-
repo.branches.remote
|
|
246
|
-
repo.branches[:main].gcommit
|
|
247
|
-
repo.branches['origin/main'].gcommit
|
|
248
|
-
|
|
249
|
-
repo.grep('hello') # implies HEAD
|
|
250
|
-
repo.blob('v2.5:Makefile').grep('hello')
|
|
251
|
-
repo.tag('v2.5').grep('hello', 'docs/')
|
|
252
|
-
repo.describe()
|
|
253
|
-
repo.describe('0djf2aa')
|
|
254
|
-
repo.describe('HEAD', {:all => true, :tags => true})
|
|
255
|
-
|
|
256
|
-
repo.diff(commit1, commit2).size
|
|
257
|
-
repo.diff(commit1, commit2).stats
|
|
258
|
-
repo.diff(commit1, commit2).name_status
|
|
259
|
-
repo.gtree('v2.5').diff('v2.6').insertions
|
|
260
|
-
repo.diff('gitsearch1', 'v2.5').path('lib/')
|
|
261
|
-
repo.diff('gitsearch1', 'v2.5').path('lib/', 'docs/', 'README.md') # multiple paths
|
|
262
|
-
repo.diff('gitsearch1', repo.gtree('v2.5'))
|
|
263
|
-
repo.diff('gitsearch1', 'v2.5').path('docs/').patch
|
|
264
|
-
repo.gtree('v2.5').diff('v2.6').patch
|
|
265
|
-
|
|
266
|
-
repo.gtree('v2.5').diff('v2.6').each do |file_diff|
|
|
267
|
-
puts file_diff.path
|
|
268
|
-
puts file_diff.patch
|
|
269
|
-
puts file_diff.blob(:src).contents
|
|
270
|
-
end
|
|
271
|
-
|
|
272
|
-
repo.worktrees # returns Git::Worktree objects
|
|
273
|
-
repo.worktrees.count
|
|
274
|
-
repo.worktrees.each do |worktree|
|
|
275
|
-
worktree.dir
|
|
276
|
-
worktree.gcommit
|
|
277
|
-
worktree.to_s
|
|
278
|
-
end
|
|
279
|
-
|
|
280
|
-
# Check repository integrity with fsck
|
|
281
|
-
result = repo.fsck
|
|
282
|
-
result.dangling.each { |obj| puts "dangling #{obj.type}: #{obj.sha}" }
|
|
283
|
-
result.missing.each { |obj| puts "missing #{obj.type}: #{obj.sha}" }
|
|
284
|
-
|
|
285
|
-
# Check if repository has any issues
|
|
286
|
-
puts "Repository is clean" if result.empty?
|
|
287
|
-
|
|
288
|
-
# fsck with options
|
|
289
|
-
result = repo.fsck(unreachable: true, strict: true)
|
|
290
|
-
|
|
291
|
-
# Suppress dangling object output
|
|
292
|
-
result = repo.fsck(dangling: false)
|
|
293
|
-
|
|
294
|
-
repo.config('user.name') # returns 'Scott Chacon'
|
|
295
|
-
repo.config # returns whole config hash
|
|
296
|
-
|
|
297
|
-
# Configuration can be set when cloning using the :config option.
|
|
298
|
-
# This option can be an single configuration String or an Array
|
|
299
|
-
# if multiple config items need to be set.
|
|
300
|
-
#
|
|
301
|
-
repo = Git.clone(
|
|
302
|
-
git_uri, destination_path,
|
|
303
|
-
:config => [
|
|
304
|
-
'core.sshCommand=ssh -i /home/user/.ssh/id_rsa',
|
|
305
|
-
'submodule.recurse=true'
|
|
306
|
-
]
|
|
307
|
-
)
|
|
308
|
-
|
|
309
|
-
repo.tags # returns array of Git::Tag objects
|
|
310
|
-
|
|
311
|
-
repo.show()
|
|
312
|
-
repo.show('HEAD')
|
|
313
|
-
repo.show('v2.8', 'README.md')
|
|
314
|
-
|
|
315
|
-
Git.ls_remote('https://github.com/ruby-git/ruby-git.git') # returns a hash containing the available references of the repo.
|
|
316
|
-
Git.ls_remote('/path/to/local/repo')
|
|
317
|
-
Git.ls_remote() # same as Git.ls_remote('.')
|
|
182
|
+
# Global config (in ~/.gitconfig)
|
|
183
|
+
entries = Git.config_list(global: true) # returns Array<Git::ConfigEntryInfo>
|
|
184
|
+
entry = Git.config_get('user.email', global: true) # returns Git::ConfigEntryInfo or nil
|
|
185
|
+
email = entry&.value # => "user@example.com" or nil
|
|
186
|
+
Git.config_set('user.email', 'user@example.com', global: true)
|
|
318
187
|
|
|
319
|
-
|
|
188
|
+
# Repository config
|
|
189
|
+
repo = Git.open('path/to/repo')
|
|
190
|
+
entries = repo.config_list # returns Array<Git::ConfigEntryInfo>
|
|
191
|
+
entry = repo.config_get('user.email') # returns Git::ConfigEntryInfo or nil
|
|
192
|
+
email = entry&.value # => "anotheruser@example.com" or nil
|
|
193
|
+
repo.config_set('user.email', 'anotheruser@example.com')
|
|
320
194
|
```
|
|
321
195
|
|
|
322
|
-
###
|
|
323
|
-
|
|
324
|
-
And here are the operations that will need to write to your git repository.
|
|
325
|
-
|
|
326
|
-
```ruby
|
|
327
|
-
repo = Git.init # default is the current directory
|
|
328
|
-
repo = Git.init('project')
|
|
329
|
-
repo = Git.init(
|
|
330
|
-
'/home/schacon/proj',
|
|
331
|
-
{ :repository => '/opt/git/proj.git', :index => '/tmp/index'}
|
|
332
|
-
)
|
|
333
|
-
|
|
334
|
-
# Clone from a git url
|
|
335
|
-
git_url = 'https://github.com/ruby-git/ruby-git.git'
|
|
336
|
-
repo = Git.clone(git_url)
|
|
337
|
-
|
|
338
|
-
# Clone into /tmp/clone/ruby-git-clean
|
|
339
|
-
name = 'ruby-git-clean'
|
|
340
|
-
path = '/tmp/clone'
|
|
341
|
-
repo = Git.clone(git_url, name, :path => path)
|
|
342
|
-
repo.dir #=> /tmp/clone/ruby-git-clean
|
|
343
|
-
|
|
344
|
-
repo.config('user.name', 'Scott Chacon')
|
|
345
|
-
repo.config('user.email', 'email@email.com')
|
|
346
|
-
|
|
347
|
-
# Clone can take a filter to tell the serve to send a partial clone
|
|
348
|
-
repo = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
|
|
349
|
-
|
|
350
|
-
# Clone can control single-branch behavior (nil default keeps current git behavior)
|
|
351
|
-
repo = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
|
|
352
|
-
|
|
353
|
-
# Clone can take an optional logger
|
|
354
|
-
logger = Logger.new(STDOUT)
|
|
355
|
-
repo = Git.clone(git_url, 'my-repo', :log => logger)
|
|
356
|
-
|
|
357
|
-
repo.add # git add -- "."
|
|
358
|
-
repo.add(:all=>true) # git add --all -- "."
|
|
359
|
-
repo.add('file_path') # git add -- "file_path"
|
|
360
|
-
repo.add(['file_path_1', 'file_path_2']) # git add -- "file_path_1" "file_path_2"
|
|
361
|
-
|
|
362
|
-
repo.remove() # git rm -f -- "."
|
|
363
|
-
repo.remove('file.txt') # git rm -f -- "file.txt"
|
|
364
|
-
repo.remove(['file.txt', 'file2.txt']) # git rm -f -- "file.txt" "file2.txt"
|
|
365
|
-
repo.remove('file.txt', :recursive => true) # git rm -f -r -- "file.txt"
|
|
366
|
-
repo.remove('file.txt', :cached => true) # git rm -f --cached -- "file.txt"
|
|
367
|
-
|
|
368
|
-
repo.commit('message')
|
|
369
|
-
repo.commit_all('message')
|
|
370
|
-
|
|
371
|
-
# Sign a commit using the gpg key configured in the user.signingkey config setting
|
|
372
|
-
repo.config('user.signingkey', '0A46826A')
|
|
373
|
-
repo.commit('message', gpg_sign: true)
|
|
374
|
-
|
|
375
|
-
# Sign a commit using a specified gpg key
|
|
376
|
-
key_id = '0A46826A'
|
|
377
|
-
repo.commit('message', gpg_sign: key_id)
|
|
378
|
-
|
|
379
|
-
# Skip signing a commit (overriding any global gpgsign setting)
|
|
380
|
-
repo.commit('message', no_gpg_sign: true)
|
|
381
|
-
|
|
382
|
-
repo = Git.clone(git_url, 'myrepo')
|
|
383
|
-
repo.chdir do
|
|
384
|
-
File.write('test-file', 'blahblahblah')
|
|
385
|
-
repo.status.changed.each do |file|
|
|
386
|
-
puts file.blob(:index).contents
|
|
387
|
-
end
|
|
388
|
-
end
|
|
389
|
-
|
|
390
|
-
repo.reset # defaults to HEAD
|
|
391
|
-
repo.reset_hard(Git::Commit)
|
|
392
|
-
|
|
393
|
-
repo.branch('new_branch') # creates new or fetches existing
|
|
394
|
-
repo.branch('new_branch').checkout
|
|
395
|
-
repo.branch('new_branch').delete
|
|
396
|
-
repo.branch('existing_branch').checkout
|
|
397
|
-
repo.branch('main').contains?('existing_branch')
|
|
398
|
-
|
|
399
|
-
# delete remote branch
|
|
400
|
-
repo.push('origin', 'remote_branch_name', force: true, delete: true)
|
|
401
|
-
|
|
402
|
-
repo.checkout('new_branch')
|
|
403
|
-
repo.checkout('new_branch', new_branch: true, start_point: 'main')
|
|
404
|
-
repo.checkout(repo.branch('new_branch'))
|
|
405
|
-
|
|
406
|
-
repo.branch(name).merge(branch2)
|
|
407
|
-
repo.branch(branch2).merge # merges HEAD with branch2
|
|
408
|
-
|
|
409
|
-
repo.branch(name).in_branch(message) { # add files } # auto-commits
|
|
410
|
-
repo.merge('new_branch')
|
|
411
|
-
repo.merge('new_branch', 'merge commit message', no_ff: true)
|
|
412
|
-
repo.merge('origin/remote_branch')
|
|
413
|
-
repo.merge(repo.branch('main'))
|
|
414
|
-
repo.merge([branch1, branch2])
|
|
196
|
+
### Full API
|
|
415
197
|
|
|
416
|
-
|
|
198
|
+
The quick start and the configuration sections above cover the most common setup.
|
|
199
|
+
The [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) reference
|
|
200
|
+
covers everything else: reading history, diffs, branches, remotes, worktrees,
|
|
201
|
+
staging, and low-level index and tree work. It documents every method and the object
|
|
202
|
+
type each one returns (such as `Git::Log`, `Git::Object::Commit`, `Git::Diff`,
|
|
203
|
+
`Git::BranchInfo`, and `Git::WorktreeInfo`), so you can follow the links from a method
|
|
204
|
+
to the full API of its result.
|
|
417
205
|
|
|
418
|
-
|
|
419
|
-
r = repo.add_remote(name, Git::Base) # Git::Remote
|
|
420
|
-
|
|
421
|
-
repo.remotes # array of Git::Remotes
|
|
422
|
-
repo.remote(name).fetch
|
|
423
|
-
repo.remote(name).remove
|
|
424
|
-
repo.remote(name).merge
|
|
425
|
-
repo.remote(name).merge(branch)
|
|
426
|
-
|
|
427
|
-
repo.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
|
|
428
|
-
repo.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
|
|
429
|
-
|
|
430
|
-
repo.fetch
|
|
431
|
-
repo.fetch(repo.remotes.first)
|
|
432
|
-
repo.fetch('origin', {:ref => 'some/ref/head'} )
|
|
433
|
-
repo.fetch(all: true, force: true, depth: 2)
|
|
434
|
-
repo.fetch('origin', {:'update-head-ok' => true})
|
|
435
|
-
|
|
436
|
-
repo.pull
|
|
437
|
-
repo.pull(Git::Repo, Git::Branch) # fetch and a merge
|
|
438
|
-
|
|
439
|
-
repo.add_tag('tag_name') # returns Git::Tag
|
|
440
|
-
repo.add_tag('tag_name', 'object_reference')
|
|
441
|
-
repo.add_tag('tag_name', 'object_reference', {:options => 'here'})
|
|
442
|
-
repo.add_tag('tag_name', {:options => 'here'})
|
|
443
|
-
|
|
444
|
-
repo.delete_tag('tag_name')
|
|
445
|
-
|
|
446
|
-
repo.repack
|
|
447
|
-
|
|
448
|
-
repo.push
|
|
449
|
-
repo.push(repo.remote('name'))
|
|
206
|
+
## Errors raised by this gem
|
|
450
207
|
|
|
451
|
-
|
|
452
|
-
repo.push('origin', 'remote_branch_name', force: true, delete: true)
|
|
208
|
+
The git gem raises only `ArgumentError` or errors that subclass `Git::Error`.
|
|
453
209
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
repo.worktree('/tmp/new_worktree').add
|
|
458
|
-
repo.worktree('/tmp/new_worktree', 'branch1').add
|
|
459
|
-
repo.worktree('/tmp/new_worktree').remove
|
|
460
|
-
repo.worktrees.prune
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
### Index and Tree Operations
|
|
464
|
-
|
|
465
|
-
Some examples of more low-level index and tree operations
|
|
210
|
+
Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
|
|
211
|
+
more specific error handling.
|
|
466
212
|
|
|
467
213
|
```ruby
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
c = repo.commit_tree('message')
|
|
474
|
-
# or #
|
|
475
|
-
t = repo.write_tree
|
|
476
|
-
c = repo.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
|
|
477
|
-
|
|
478
|
-
repo.branch('branch_name').update_ref(c)
|
|
479
|
-
repo.update_ref(branch, c)
|
|
480
|
-
|
|
481
|
-
repo.with_temp_working do # new blank working directory
|
|
482
|
-
repo.checkout
|
|
483
|
-
repo.checkout(another_index)
|
|
484
|
-
repo.commit # commits to temp_index
|
|
485
|
-
end
|
|
486
|
-
end
|
|
487
|
-
|
|
488
|
-
repo.set_index('/path/to/index')
|
|
489
|
-
|
|
490
|
-
repo.with_index(path) do
|
|
491
|
-
# calls set_index, then switches back after
|
|
492
|
-
end
|
|
493
|
-
|
|
494
|
-
repo.with_working(dir) do
|
|
495
|
-
# calls set_working, then switches back after
|
|
496
|
-
end
|
|
497
|
-
|
|
498
|
-
repo.with_temp_working(dir) do
|
|
499
|
-
repo.checkout_index(:prefix => dir, :path_limiter => path)
|
|
500
|
-
# do file work
|
|
501
|
-
repo.commit # commits to index
|
|
214
|
+
begin
|
|
215
|
+
# some git operation
|
|
216
|
+
rescue Git::Error => e
|
|
217
|
+
puts "An error occurred: #{e.message}"
|
|
502
218
|
end
|
|
503
219
|
```
|
|
504
220
|
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
The
|
|
508
|
-
`Git::Error`. It does not explicitly raise any other types of errors.
|
|
509
|
-
|
|
510
|
-
The gem's own filesystem operations, such as reading a `.git` pointer file,
|
|
511
|
-
creating a temporary file, or changing directory, do not convert operating system
|
|
512
|
-
errors. These can be raised as a bare `SystemCallError` (for example `Errno::ENOENT`
|
|
513
|
-
or `Errno::EACCES`) rather than `Git::Error`. Gzip compression in `archive` can
|
|
514
|
-
likewise raise a `Zlib::Error`. Rescue `SystemCallError` and `Zlib::Error` alongside
|
|
515
|
-
`Git::Error` if your code needs to handle them. Any method that captures git
|
|
516
|
-
output can also raise `Encoding::ConverterNotFoundError` when the output contains
|
|
517
|
-
a line whose detected encoding, such as UTF-7, has no Ruby converter.
|
|
518
|
-
|
|
519
|
-
Starting with v6.0.0, the filesystem and gzip errors are raised as `Git::Error`
|
|
520
|
-
with the original error available through `cause`, and lines with no Ruby
|
|
521
|
-
converter are scrubbed instead of raising.
|
|
522
|
-
|
|
523
|
-
It is recommended to rescue `Git::Error` to catch any runtime error raised by this
|
|
524
|
-
gem unless you need more specific error handling.
|
|
221
|
+
Operating system errors from the gem's own filesystem operations, such as reading
|
|
222
|
+
a `.git` pointer file or creating a temporary file, are raised as `Git::Error`.
|
|
223
|
+
The original `SystemCallError` is available through `cause`:
|
|
525
224
|
|
|
526
225
|
```ruby
|
|
527
226
|
begin
|
|
528
|
-
|
|
227
|
+
repo = Git.open('/path/to/repo')
|
|
529
228
|
rescue Git::Error => e
|
|
530
|
-
puts
|
|
229
|
+
puts e.cause.class if e.cause.is_a?(SystemCallError) #=> Errno::EACCES
|
|
531
230
|
end
|
|
532
231
|
```
|
|
533
232
|
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
233
|
+
The promise covers errors the gem raises from its own operations. Two things pass
|
|
234
|
+
through unchanged. An error raised by a block your code passes to a method such as
|
|
235
|
+
`chdir` or `with_temp_working` is your error, and the gem does not relabel it. And
|
|
236
|
+
with the `raise` behavior described under [Deprecation policy](#deprecation-policy), a
|
|
237
|
+
deprecated call raises `ActiveSupport::DeprecationException`, which is intentionally
|
|
238
|
+
not a `Git::Error` so a broad rescue cannot hide a deprecation your code opted to
|
|
239
|
+
treat as fatal.
|
|
537
240
|
|
|
538
|
-
|
|
241
|
+
See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
|
|
539
242
|
|
|
540
|
-
|
|
541
|
-
method calls that accept a `:timeout` parameter.
|
|
243
|
+
## Specifying and handling timeouts
|
|
542
244
|
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
signal. This library may hang if the `git` command does not terminate after receiving
|
|
546
|
-
the KILL signal.
|
|
245
|
+
Set a timeout for git command line operations either globally or per method call for
|
|
246
|
+
methods that accept a `:timeout` parameter.
|
|
547
247
|
|
|
548
|
-
|
|
549
|
-
`
|
|
550
|
-
`Git::
|
|
248
|
+
The timeout is the number of seconds a `git` command may run before the gem sends
|
|
249
|
+
it `SIGKILL`. It must be a real, non-negative `Numeric`. When a command times out,
|
|
250
|
+
the gem kills it and raises `Git::TimeoutError`, which derives from
|
|
251
|
+
`Git::SignaledError` and `Git::Error`. The gem may hang if the `git` command does
|
|
252
|
+
not terminate after receiving `SIGKILL`.
|
|
551
253
|
|
|
552
|
-
If the timeout value is `0` or `nil`, no timeout
|
|
254
|
+
If the timeout value is `0` or `nil`, no timeout is enforced.
|
|
553
255
|
|
|
554
|
-
If a method accepts a `:timeout` parameter and
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
value is.
|
|
256
|
+
If a method accepts a `:timeout` parameter and receives a non-nil value, that value
|
|
257
|
+
overrides the global timeout. In this context, a value of `nil`, which is usually
|
|
258
|
+
the default, uses the global timeout value, and a value of `0` turns off timeout
|
|
259
|
+
enforcement for that method call no matter what the global value is.
|
|
559
260
|
|
|
560
261
|
To set a global timeout, use the `Git.config` object:
|
|
561
262
|
|
|
@@ -572,17 +273,17 @@ repo_url = 'https://github.com/ruby-git/ruby-git.git'
|
|
|
572
273
|
Git.clone(repo_url) # Use the global timeout value
|
|
573
274
|
Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
|
|
574
275
|
Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
|
|
575
|
-
Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::
|
|
276
|
+
Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::TimeoutError
|
|
576
277
|
```
|
|
577
278
|
|
|
578
|
-
If the command takes too long,
|
|
279
|
+
If the command takes too long, the gem raises `Git::TimeoutError`:
|
|
579
280
|
|
|
580
281
|
```ruby
|
|
581
282
|
begin
|
|
582
283
|
Git.clone(repo_url, timeout: 10)
|
|
583
284
|
rescue Git::TimeoutError => e
|
|
584
285
|
e.result.tap do |r|
|
|
585
|
-
r.class #=> Git::
|
|
286
|
+
r.class #=> Git::CommandLine::Result
|
|
586
287
|
r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
|
|
587
288
|
r.status.timeout? #=> true
|
|
588
289
|
r.git_cmd # The git command ran as an array of strings
|
|
@@ -611,6 +312,17 @@ GIT_DEPRECATION_BEHAVIOR=silence
|
|
|
611
312
|
Accepted environment variable values are the behavior names supported by your
|
|
612
313
|
installed ActiveSupport version.
|
|
613
314
|
|
|
315
|
+
A deprecated method warns on every call, so a call site inside a loop produces one
|
|
316
|
+
warning per iteration. The gem does not deduplicate warnings. To quiet one call site
|
|
317
|
+
without hiding other deprecations, wrap it in `Git::Deprecation.silence`:
|
|
318
|
+
|
|
319
|
+
```ruby
|
|
320
|
+
Git::Deprecation.silence { repo.set_index(index_file) }
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Prefer this over setting the behavior to `silence` globally, which also hides the
|
|
324
|
+
warnings for deprecations added in later releases.
|
|
325
|
+
|
|
614
326
|
If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
|
|
615
327
|
raises `ArgumentError` with the accepted behavior names.
|
|
616
328
|
|
|
@@ -618,11 +330,80 @@ See [the Active Support Deprecation
|
|
|
618
330
|
documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
|
|
619
331
|
for more details.
|
|
620
332
|
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
333
|
+
Before upgrading the git gem to the next major version, follow the upgrade procedure
|
|
334
|
+
in [UPGRADING.md](UPGRADING.md#upgrading-to-v6x). It turns the warnings into errors so
|
|
335
|
+
that you cannot miss one.
|
|
336
|
+
|
|
337
|
+
For the full list of deprecated methods and their replacements, see
|
|
338
|
+
[UPGRADING.md](UPGRADING.md).
|
|
339
|
+
|
|
340
|
+
## Platform limitations
|
|
341
|
+
|
|
342
|
+
### Regex metacharacters on Git for Windows
|
|
343
|
+
|
|
344
|
+
On Git for Windows, git's regex engine matches **bytes** rather than characters. A
|
|
345
|
+
metacharacter such as `.`, or a POSIX character class such as `[[:alpha:]]`, therefore
|
|
346
|
+
never matches a whole multi-byte character. The same call matches on Linux and macOS.
|
|
347
|
+
|
|
348
|
+
The failure is silent. Nothing raises, and the result is indistinguishable from a
|
|
349
|
+
pattern that genuinely does not occur:
|
|
350
|
+
|
|
351
|
+
```ruby
|
|
352
|
+
# File content, commit message, and config value are all 'ÄPFEL sind gut'.
|
|
353
|
+
# 'Ä' is two bytes in UTF-8 (C3 84), so '.' has to match both to match the character.
|
|
354
|
+
|
|
355
|
+
repo.grep('^.PFEL') # => {} on Windows, matches elsewhere
|
|
356
|
+
repo.log.grep('^.PFEL').execute.size # => 0 on Windows, 1 elsewhere
|
|
357
|
+
repo.config_get_all('test.desc', '^.PFEL') # => [] on Windows, matches elsewhere
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
This is a property of the regex engine git bundles on that platform, not something the
|
|
361
|
+
gem sets. It is unaffected by the locale: the behavior is identical under `en_US.UTF-8`,
|
|
362
|
+
`C.UTF-8`, `C`, and with no `LC_ALL` set at all. Literal (metacharacter-free) patterns
|
|
363
|
+
and case-insensitive matching are unaffected on every platform.
|
|
364
|
+
|
|
365
|
+
**Workaround.** Perl-compatible regular expressions do match characters on Git for
|
|
366
|
+
Windows, so the methods that can reach a PCRE engine accept an opt-in selector:
|
|
367
|
+
|
|
368
|
+
```ruby
|
|
369
|
+
repo.grep('^.PFEL', nil, perl_regexp: true) # matches on every platform
|
|
370
|
+
repo.log.perl_regexp.grep('^.PFEL').execute # matches on every platform
|
|
371
|
+
repo.full_log_commits(grep: '^.PFEL', perl_regexp: true)
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Two caveats:
|
|
375
|
+
|
|
376
|
+
- **PCRE is a different dialect.** Git's other modes are POSIX basic regular
|
|
377
|
+
expressions (the default) and POSIX extended regular expressions (selected
|
|
378
|
+
explicitly). Selecting PCRE is a deliberate choice by the caller, so the gem does
|
|
379
|
+
not substitute it automatically based on the host.
|
|
380
|
+
- **PCRE must be compiled in.** Git for Windows and the mainstream Linux and macOS
|
|
381
|
+
packages ship it, but git built without `USE_LIBPCRE` fails with `cannot use
|
|
382
|
+
Perl-compatible regexes...`.
|
|
383
|
+
|
|
384
|
+
**There is no workaround for `git config` value patterns.** They are POSIX extended
|
|
385
|
+
regular expressions with no PCRE mode, so `config_get`, `config_get_all`,
|
|
386
|
+
`config_get_regexp`, `config_replace_all`, `config_unset`, and `config_unset_all` cannot
|
|
387
|
+
match a metacharacter against a non-ASCII character on Git for Windows. Match on ASCII
|
|
388
|
+
text or an exact value instead.
|
|
389
|
+
|
|
390
|
+
`config_replace_all` deserves particular care, because there the failure is worse than
|
|
391
|
+
an empty result. When the value pattern selects nothing, `git config --replace-all`
|
|
392
|
+
*adds* the new value as an additional entry rather than replacing one, and exits zero:
|
|
624
393
|
|
|
625
|
-
|
|
394
|
+
```ruby
|
|
395
|
+
# Existing value of test.desc is 'ÄPFEL sind gut'
|
|
396
|
+
repo.config_replace_all('test.desc', 'NEW', '^.PFEL')
|
|
397
|
+
|
|
398
|
+
repo.config_get_all('test.desc').map(&:value)
|
|
399
|
+
# => ["NEW"] elsewhere, replaced as intended
|
|
400
|
+
# => ["ÄPFEL sind gut", "NEW"] on Windows, original kept and duplicate added
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
So a replace can silently leave the original value in place and add a second entry beside
|
|
404
|
+
it. Confirm with `config_get_all` when the key must end up single-valued.
|
|
405
|
+
|
|
406
|
+
## Project policies
|
|
626
407
|
|
|
627
408
|
These documents set expectations for behavior, contribution workflows, AI-assisted
|
|
628
409
|
changes, decision making, maintainer roles, and licensing. Please review them before
|
|
@@ -635,135 +416,236 @@ opening issues or pull requests.
|
|
|
635
416
|
| [AI_POLICY](AI_POLICY.md) | AI-assisted contributions are welcome. Contributors are expected to read and apply the AI Policy, and ensure any AI-assisted work meets our quality, security, and licensing standards. |
|
|
636
417
|
| [Ruby version support policy](#ruby-version-support-policy) | Supported Ruby runtimes and platforms; bump decisions and CI coverage expectations. |
|
|
637
418
|
| [Git version support policy](#git-version-support-policy) | Minimum supported git version and how version bumps are communicated and enforced. |
|
|
419
|
+
| [Deprecation policy](#deprecation-policy) | When an API may be removed, what a deprecation warning says, and how to upgrade across a major version. |
|
|
420
|
+
| [Release support policy](#release-support-policy) | Which branch releases what, and how long each major series is supported. |
|
|
638
421
|
| [GOVERNANCE](GOVERNANCE.md) | Principles-first governance defining maintainer/project lead roles, least-privilege access, consensus/majority decisions, and nomination/emeritus steps. |
|
|
639
422
|
| [MAINTAINERS](MAINTAINERS.md) | Lists active maintainers (Project Lead noted) and emeritus alumni with links; see governance for role scope. |
|
|
640
423
|
| [LICENSE](LICENSE) | MIT License terms for using, modifying, and redistributing this project. |
|
|
641
424
|
|
|
642
|
-
### Ruby
|
|
425
|
+
### Ruby version support policy
|
|
643
426
|
|
|
644
427
|
This gem is expected to function correctly on:
|
|
645
428
|
|
|
646
429
|
- All [non-EOL versions](https://www.ruby-lang.org/en/downloads/branches/) of the MRI
|
|
647
430
|
Ruby on Mac, Linux, and Windows
|
|
648
|
-
-
|
|
649
|
-
|
|
431
|
+
- JRuby and TruffleRuby on Linux, starting from the earliest release whose Ruby
|
|
432
|
+
compatibility target is at or above the oldest supported MRI version, unless a
|
|
433
|
+
newer release is otherwise needed (for example, when a release does not
|
|
434
|
+
implement a feature the gem depends on)
|
|
650
435
|
|
|
651
|
-
|
|
436
|
+
Consult the CI build matrix in
|
|
437
|
+
[`.github/workflows/continuous_integration.yml`](.github/workflows/continuous_integration.yml)
|
|
438
|
+
for the exact JRuby and TruffleRuby versions tested. Newer releases of each engine
|
|
439
|
+
are expected to work but are not tested.
|
|
440
|
+
|
|
441
|
+
Because the JRuby and TruffleRuby floors derive from the MRI floor, they move
|
|
442
|
+
whenever the oldest supported MRI version changes.
|
|
443
|
+
|
|
444
|
+
This project intends to support the latest version of JRuby on Windows once
|
|
652
445
|
the [process_executer](https://github.com/main-branch/process_executer) gem properly
|
|
653
446
|
supports subprocess status reporting on JRuby for Windows (see
|
|
654
447
|
[main-branch/process_executer#156](https://github.com/main-branch/process_executer/issues/156)).
|
|
655
448
|
|
|
656
|
-
### Git
|
|
449
|
+
### Git version support policy
|
|
450
|
+
|
|
451
|
+
This gem requires git 2.43.0 or later, as the gemspec declares. The floor weighs the
|
|
452
|
+
git features the gem depends on, the systems users still run, and the git versions
|
|
453
|
+
CI can test.
|
|
454
|
+
|
|
455
|
+
Git 2.43.0 was released on November 20, 2023. The gem may work with an older git,
|
|
456
|
+
but the project does not test or support versions before 2.43.0. Users on an older
|
|
457
|
+
git should upgrade to at least 2.43.0.
|
|
458
|
+
|
|
459
|
+
A later major or minor release may raise the floor when the gem adopts a newer git
|
|
460
|
+
feature or when keeping compatibility with an old git becomes impractical. The
|
|
461
|
+
CHANGELOG and release notes document each such change.
|
|
462
|
+
|
|
463
|
+
### Deprecation policy
|
|
464
|
+
|
|
465
|
+
This gem removes an API only in a major release, and only after a normal release
|
|
466
|
+
deprecated it with a runtime warning and documented its replacement in
|
|
467
|
+
[UPGRADING.md](UPGRADING.md). A normal release is one that is not a pre-release. The
|
|
468
|
+
warning names the major release that removes the API once that is decided. Until then
|
|
469
|
+
it says the API will be removed in a future major release.
|
|
470
|
+
|
|
471
|
+
The recommended way to upgrade across a major version:
|
|
472
|
+
|
|
473
|
+
1. Upgrade to the latest release of the major series you are on.
|
|
474
|
+
2. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
|
|
475
|
+
your test suite and, if possible, staging.
|
|
476
|
+
3. Fix each deprecation using the entries in [UPGRADING.md](UPGRADING.md) until the
|
|
477
|
+
suite is clean.
|
|
478
|
+
4. Work through the changes that a clean run does not catch, listed in that major's
|
|
479
|
+
section of [UPGRADING.md](UPGRADING.md).
|
|
480
|
+
5. Upgrade to the next major release.
|
|
481
|
+
|
|
482
|
+
Because every deprecation warning is present in the last release of a major series,
|
|
483
|
+
steps 2 and 3 find every call to a deprecated API. A major release may also change a
|
|
484
|
+
behavior that had no deprecation path, such as the return type of a method that
|
|
485
|
+
keeps its name; step 4 covers those. The version-specific steps are in
|
|
486
|
+
[UPGRADING.md](UPGRADING.md#upgrading-to-v6x). See [Deprecations](#deprecations)
|
|
487
|
+
for how to configure the warnings.
|
|
488
|
+
|
|
489
|
+
### Release support policy
|
|
490
|
+
|
|
491
|
+
All development happens on `main`, which releases the next version of the gem,
|
|
492
|
+
including the next major version. The next release from `main` is v6.0.0. Every
|
|
493
|
+
further v5.x release is cut from `5.x`.
|
|
494
|
+
|
|
495
|
+
Each supported previous major series is maintained on a branch named for that
|
|
496
|
+
series, currently `5.x` and `4.x`. These branches receive bug fixes and security
|
|
497
|
+
fixes, and backward-compatible features at the maintainers' discretion. Fixes land on
|
|
498
|
+
`main` first and are backported, except a fix for a problem that exists only in a
|
|
499
|
+
maintenance branch, which targets that branch directly.
|
|
657
500
|
|
|
658
|
-
|
|
659
|
-
|
|
501
|
+
Support for a major series ends when the second major after it is released. v4.x is
|
|
502
|
+
supported until v6.0.0 ships, and v5.x until v7.0.0.
|
|
660
503
|
|
|
661
|
-
|
|
662
|
-
- A reasonable balance between supporting older systems and leveraging modern git
|
|
663
|
-
capabilities
|
|
664
|
-
- The practical limitations of testing across multiple git versions in CI
|
|
504
|
+
## Project announcements
|
|
665
505
|
|
|
666
|
-
|
|
667
|
-
versions of git, compatibility with versions prior to 2.28.0 is not tested or
|
|
668
|
-
guaranteed. Users on older git versions should upgrade to at least 2.28.0.
|
|
506
|
+
### 2026-09-04: v5.x releases move to the `5.x` branch
|
|
669
507
|
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
508
|
+
On September 4, 2026, we created the `5.x` branch from v5.4.1. Every further v5.x
|
|
509
|
+
release is cut from that branch, and the next release from `main` is v6.0.0. Nothing
|
|
510
|
+
changes for users of the gem: v5.x continues to receive bug fixes and security fixes
|
|
511
|
+
per the [Release support policy](#release-support-policy), and v4.x is supported
|
|
512
|
+
until v6.0.0 ships.
|
|
674
513
|
|
|
675
|
-
|
|
514
|
+
For contributors, fixes still land on `main` first and are backported to `5.x`. A fix
|
|
515
|
+
for a problem that exists only in v5.x targets `5.x` directly. See the
|
|
516
|
+
[branch strategy](CONTRIBUTING.md#branch-strategy) and
|
|
517
|
+
[issue #1717](https://github.com/ruby-git/ruby-git/issues/1717), the v6.0.0 roadmap.
|
|
676
518
|
|
|
677
|
-
### 2026-
|
|
519
|
+
### 2026-09-04: Retired branches deleted
|
|
520
|
+
|
|
521
|
+
On September 4, 2026, we deleted the `v1` and `master` branches. Neither had a
|
|
522
|
+
purpose: support for v1.x ended when v3.0.0 shipped, per the
|
|
523
|
+
[Release support policy](#release-support-policy), and `master` was the pre-rename
|
|
524
|
+
default branch, frozen since the rename to `main` on 2025-06-06. Every v1.x release
|
|
525
|
+
remains available as a tag, so nothing released was lost.
|
|
526
|
+
|
|
527
|
+
The branches that remain are the ones the release support policy describes: `main`
|
|
528
|
+
releases the next version, `4.x` maintains the v4.x series, and `5.x` maintains the
|
|
529
|
+
v5.x series. See [issue #1786](https://github.com/ruby-git/ruby-git/issues/1786) for
|
|
530
|
+
the details.
|
|
531
|
+
|
|
532
|
+
### 2026-08-23: v5.x deprecations and the v6.0.0 roadmap
|
|
533
|
+
|
|
534
|
+
The v6.0.0 plan is public. The remaining ActiveRecord-style
|
|
535
|
+
classes (`Git::Branch`, `Git::Remote`, `Git::Stash`, `Git::Worktree`,
|
|
536
|
+
`Git::Object::Tag`, `Git::Status`, `Git::Author`, and their collections) will be
|
|
537
|
+
deprecated during the v5.x series in favor of the immutable `*Info` value-object
|
|
538
|
+
APIs. v6.0.0 will remove each deprecated class once a normal v5.x release has carried
|
|
539
|
+
its deprecation warning and UPGRADING.md entry, per the
|
|
540
|
+
[Deprecation policy](#deprecation-policy). v6.0.0 will not ship until every planned
|
|
541
|
+
deprecation has shipped that way. v6.0.0 also raises the version floors to git 2.43.0
|
|
542
|
+
and Ruby 3.3.
|
|
543
|
+
|
|
544
|
+
[Issue #1717](https://github.com/ruby-git/ruby-git/issues/1717) is the roadmap
|
|
545
|
+
and tracks scope, order, and status. If your code uses the classes above, you can
|
|
546
|
+
start migrating now. Each deprecation names its replacement, and
|
|
547
|
+
[UPGRADING.md](UPGRADING.md) carries the migration guide as releases ship.
|
|
548
|
+
|
|
549
|
+
### 2026-07-28: v5.0.0 released
|
|
550
|
+
|
|
551
|
+
We have published [`git v5.0.0`](https://rubygems.org/gems/git/versions/5.0.0), the
|
|
552
|
+
first stable release of the v5.x series, after five public beta releases in June and
|
|
553
|
+
July 2026.
|
|
554
|
+
|
|
555
|
+
v5.0.0 is a major release with breaking changes. See
|
|
556
|
+
[UPGRADING.md](UPGRADING.md) for the complete migration guide.
|
|
557
|
+
|
|
558
|
+
To install:
|
|
559
|
+
|
|
560
|
+
```ruby
|
|
561
|
+
gem 'git', '~> 5.0'
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
Or:
|
|
565
|
+
|
|
566
|
+
```sh
|
|
567
|
+
gem install git
|
|
568
|
+
```
|
|
678
569
|
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
changes are fully understood, meet our quality bar, and respect licensing
|
|
682
|
-
requirements.
|
|
570
|
+
Most v4.x code requires no changes. Compatibility shims keep the old API working
|
|
571
|
+
while emitting deprecation warnings that tell you what to migrate before v6.0.0.
|
|
683
572
|
|
|
684
|
-
|
|
685
|
-
quick to read, easy to remember, and avoids unnecessary policy overhead while still
|
|
686
|
-
setting clear expectations.
|
|
573
|
+
### 2026-01-07: AI policy introduced
|
|
687
574
|
|
|
688
|
-
|
|
575
|
+
We have adopted an [AI Policy](AI_POLICY.md) that sets expectations for
|
|
576
|
+
AI-assisted contributions. Read it before opening a PR. It asks that you understand
|
|
577
|
+
every change you submit, that the work meets the project's quality bar, and that it
|
|
578
|
+
respects licensing requirements.
|
|
689
579
|
|
|
690
|
-
The
|
|
691
|
-
|
|
692
|
-
difficult to maintain and evolve. This redesign aims to address these issues by
|
|
693
|
-
introducing a clearer, more robust, and more testable structure.
|
|
580
|
+
The policy states principles rather than a checklist, so it is short to read and
|
|
581
|
+
still sets clear expectations.
|
|
694
582
|
|
|
695
|
-
|
|
696
|
-
architecture and the proposed changes. We encourage our community and contributors to
|
|
697
|
-
review them:
|
|
583
|
+
### 2025-07-09: Architectural redesign
|
|
698
584
|
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
3. [Implementation Plan](redesign/3_architecture_implementation.md): The step-by-step
|
|
704
|
-
plan for implementing the redesign.
|
|
585
|
+
On this date we announced an architectural redesign of the git gem. The architecture
|
|
586
|
+
at the time was difficult to maintain and change. The redesign replaced it with a
|
|
587
|
+
three-layer structure of commands, parsers, and a `Git::Repository` facade, which is
|
|
588
|
+
easier to test because each layer can be exercised on its own.
|
|
705
589
|
|
|
706
|
-
|
|
707
|
-
|
|
590
|
+
The redesign shipped in v5.0.0 and is complete. `Git::Base` and `Git::Lib` are
|
|
591
|
+
gone, along with the `g.lib` accessor. See [UPGRADING.md](UPGRADING.md) for what
|
|
592
|
+
changed and how to migrate.
|
|
708
593
|
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
documented methods like `g.commit`, `g.add`, and `g.status` should find the
|
|
714
|
-
transition to v5.0.0 straightforward.
|
|
715
|
-
>
|
|
716
|
-
> The breaking changes will primarily affect users who have been relying on the
|
|
717
|
-
internal g.lib accessor, which will be removed as part of this cleanup. For more
|
|
718
|
-
details, please see the "Impact on Users" section in [the redesign
|
|
719
|
-
document](redesign/2_architecture_redesign.md).
|
|
594
|
+
The three documents written to plan it are kept as a historical record in
|
|
595
|
+
[`archive/v5-redesign/`](archive/v5-redesign/). They describe the state of the code
|
|
596
|
+
before and during the migration and are not current policy. The standards that apply
|
|
597
|
+
to new code live in [`.github/skills/`](.github/skills/).
|
|
720
598
|
|
|
721
|
-
|
|
599
|
+
1. [Analysis of the Current Architecture](archive/v5-redesign/1_architecture_existing.md):
|
|
600
|
+
a breakdown of the v4.x design and its challenges.
|
|
601
|
+
2. [The Proposed Redesign](archive/v5-redesign/2_architecture_redesign.md): an overview
|
|
602
|
+
of the three-layer architecture.
|
|
603
|
+
3. [Implementation Plan](archive/v5-redesign/3_architecture_implementation.md): the
|
|
604
|
+
step-by-step plan that was followed.
|
|
722
605
|
|
|
723
|
-
|
|
724
|
-
adopted [RuboCop](https://rubocop.org/) as our static code analyzer and formatter.
|
|
606
|
+
### 2025-07-07: We now use RuboCop
|
|
725
607
|
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
608
|
+
The `ruby-git` project has adopted [RuboCop](https://rubocop.org/) as its static
|
|
609
|
+
code analyzer and formatter so that contributions share one style. All new
|
|
610
|
+
contributions must follow the style rules the project's RuboCop configuration
|
|
611
|
+
enforces.
|
|
729
612
|
|
|
730
|
-
RuboCop
|
|
613
|
+
Run RuboCop from the project's Rakefile:
|
|
731
614
|
|
|
732
615
|
```shell
|
|
733
616
|
rake rubocop
|
|
734
617
|
```
|
|
735
618
|
|
|
736
|
-
RuboCop
|
|
737
|
-
|
|
619
|
+
RuboCop also runs as part of the default rake task, which our continuous integration
|
|
620
|
+
workflow runs.
|
|
738
621
|
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
scope possible.
|
|
622
|
+
PRs with RuboCop offenses will not be merged. In rare cases, it might be acceptable
|
|
623
|
+
to disable a RuboCop check for the most limited scope possible.
|
|
742
624
|
|
|
743
|
-
If you have a problem fixing a
|
|
625
|
+
If you have a problem fixing a RuboCop offense, don't be afraid to ask a
|
|
744
626
|
contributor.
|
|
745
627
|
|
|
746
|
-
### 2025-06-06: Default
|
|
628
|
+
### 2025-06-06: Default branch rename
|
|
747
629
|
|
|
748
|
-
On June
|
|
630
|
+
On June 6, 2025, we renamed the default branch from `master` to `main`.
|
|
749
631
|
|
|
750
|
-
Instructions for renaming your local or forked branch to match
|
|
751
|
-
|
|
632
|
+
Instructions for renaming your local or forked branch to match are in the gist
|
|
633
|
+
[Default Branch Name
|
|
752
634
|
Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d).
|
|
753
635
|
|
|
754
|
-
### 2025-05-15: We've
|
|
636
|
+
### 2025-05-15: We've switched to Conventional Commits
|
|
755
637
|
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
638
|
+
The `ruby-git` project has adopted the [Conventional Commits
|
|
639
|
+
standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages.
|
|
640
|
+
This enables automated changelog generation and is a step toward continuous
|
|
641
|
+
delivery.
|
|
760
642
|
|
|
761
|
-
|
|
762
|
-
Commits
|
|
763
|
-
|
|
643
|
+
All commits to this repository must follow the Conventional Commits standard.
|
|
644
|
+
Commits that do not follow it will fail the CI build, and PRs that include them will
|
|
645
|
+
not be merged.
|
|
764
646
|
|
|
765
|
-
|
|
766
|
-
|
|
647
|
+
To validate your commit messages locally before pushing them to GitHub, install the
|
|
648
|
+
git `commit-msg` hook by running `bin/setup` in the project root.
|
|
767
649
|
|
|
768
650
|
Read more about this change in the [Commit Message Guidelines section of
|
|
769
|
-
CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)
|
|
651
|
+
CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines).
|