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/UPGRADING.md
ADDED
|
@@ -0,0 +1,1822 @@
|
|
|
1
|
+
# Upgrading the `git` gem
|
|
2
|
+
|
|
3
|
+
This document covers breaking changes and migration steps when upgrading the
|
|
4
|
+
`git` gem to a new major version. Each section describes what changed and how
|
|
5
|
+
to update your code when upgrading from the preceding major version.
|
|
6
|
+
|
|
7
|
+
- [Upgrading to v6.x](#upgrading-to-v6x)
|
|
8
|
+
- [Before you upgrade](#before-you-upgrade)
|
|
9
|
+
- [Minimum Ruby version](#minimum-ruby-version)
|
|
10
|
+
- [Minimum git version](#minimum-git-version)
|
|
11
|
+
- [Minimum addressable version](#minimum-addressable-version)
|
|
12
|
+
- [Minimum activesupport version](#minimum-activesupport-version)
|
|
13
|
+
- [Changes the deprecation run does not catch or does not explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain)
|
|
14
|
+
- [Filesystem errors raised as `Git::Error`](#filesystem-errors-raised-as-giterror)
|
|
15
|
+
- [Gzip failures in `archive` raised as `Git::Error`](#gzip-failures-in-archive-raised-as-giterror)
|
|
16
|
+
- [Relative `:repository` and `:index` paths](#relative-repository-and-index-paths)
|
|
17
|
+
- [Tilde expansion in `Git.init` and `Git.clone` paths](#tilde-expansion-in-gitinit-and-gitclone-paths)
|
|
18
|
+
- [Context helpers yield a separate repository](#context-helpers-yield-a-separate-repository)
|
|
19
|
+
- [`Git.init`, `Git.open`, and `Git.bare` reject unknown options](#gitinit-gitopen-and-gitbare-reject-unknown-options)
|
|
20
|
+
- [`tag_create` raises when the created tag is missing](#tag_create-raises-when-the-created-tag-is-missing)
|
|
21
|
+
- [`stash_list` returns an Array of `Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)
|
|
22
|
+
- [`stash_store` raises when the stored entry is missing](#stash_store-raises-when-the-stored-entry-is-missing)
|
|
23
|
+
- [`worktree_add` returns `Git::WorktreeInfo` and raises when the worktree is missing](#worktree_add-returns-gitworktreeinfo-and-raises-when-the-worktree-is-missing)
|
|
24
|
+
- [`Git::Deprecation` horizon is prose](#gitdeprecation-horizon-is-prose)
|
|
25
|
+
- [Removed APIs](#removed-apis)
|
|
26
|
+
- [Deprecated in v6.0.0](#deprecated-in-v600)
|
|
27
|
+
- [`set_index` and `set_working` deprecated](#set_index-and-set_working-deprecated)
|
|
28
|
+
- [`Git::GitExecuteError` deprecated](#gitgitexecuteerror-deprecated)
|
|
29
|
+
- [Upgrading to v5.x](#upgrading-to-v5x)
|
|
30
|
+
- [Overview](#overview)
|
|
31
|
+
- [Breaking changes](#breaking-changes)
|
|
32
|
+
- [`Git::Base` removed](#gitbase-removed)
|
|
33
|
+
- [Return type of `Git.open`, `Git.clone`, `Git.init`, `Git.bare`](#return-type-of-gitopen-gitclone-gitinit-gitbare)
|
|
34
|
+
- [Unsupported options raise `ArgumentError`](#unsupported-options-raise-argumenterror)
|
|
35
|
+
- [`Git::Lib` removed](#gitlib-removed)
|
|
36
|
+
- [`Git::Log#object` is not a path limiter](#gitlogobject-is-not-a-path-limiter)
|
|
37
|
+
- [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated)
|
|
38
|
+
- [Deprecated methods](#deprecated-methods)
|
|
39
|
+
- [Facade method renames](#facade-method-renames)
|
|
40
|
+
- [`Git::Repository` method renames](#gitrepository-method-renames)
|
|
41
|
+
- [`Git::Repository` alias renames](#gitrepository-alias-renames)
|
|
42
|
+
- [`Git::Repository` option renames](#gitrepository-option-renames)
|
|
43
|
+
- [v4.x-style configuration methods](#v4x-style-configuration-methods)
|
|
44
|
+
- [`Git` module mixin deprecations](#git-module-mixin-deprecations)
|
|
45
|
+
- [Module-level `Git` function deprecations](#module-level-git-function-deprecations)
|
|
46
|
+
- [`Git::Author` deprecated](#gitauthor-deprecated)
|
|
47
|
+
- [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated)
|
|
48
|
+
- [Legacy stash API deprecated](#legacy-stash-api-deprecated)
|
|
49
|
+
- [`Git::Repository#remotes` deprecated](#gitrepositoryremotes-deprecated)
|
|
50
|
+
- [`Git::Remote` deprecated](#gitremote-deprecated)
|
|
51
|
+
- [`Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated](#gitcommandscatfileraw-allow_unknown_type-option-deprecated)
|
|
52
|
+
- [`Git::Branch` and `Git::Branches` deprecated](#gitbranch-and-gitbranches-deprecated)
|
|
53
|
+
- [`Git::Object::Tag` deprecated](#gitobjecttag-deprecated)
|
|
54
|
+
- [`Git::Status` deprecated](#gitstatus-deprecated)
|
|
55
|
+
- [`Git::Worktree` and `Git::Worktrees` deprecated](#gitworktree-and-gitworktrees-deprecated)
|
|
56
|
+
- [`Git.clone` option renames](#gitclone-option-renames)
|
|
57
|
+
- [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated)
|
|
58
|
+
- [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated)
|
|
59
|
+
- [`Git.export` `:remote` option deprecated](#gitexport-remote-option-deprecated)
|
|
60
|
+
|
|
61
|
+
## Upgrading to v6.x
|
|
62
|
+
|
|
63
|
+
v6.0.0 removes the APIs deprecated during v5.x under the project's
|
|
64
|
+
[deprecation policy](README.md#deprecation-policy), raises the Ruby, git, and
|
|
65
|
+
dependency floors, and changes a small number of behaviors that had no deprecation
|
|
66
|
+
path. [Issue 1717](https://github.com/ruby-git/ruby-git/issues/1717) tracks its scope.
|
|
67
|
+
|
|
68
|
+
This section is organized by what you have to do rather than by what changed:
|
|
69
|
+
|
|
70
|
+
- [Before you upgrade](#before-you-upgrade) gives the version floors and the upgrade
|
|
71
|
+
procedure. Read it first.
|
|
72
|
+
- [Changes the deprecation run does not catch or does not
|
|
73
|
+
explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain) covers
|
|
74
|
+
every change that a clean run under `GIT_DEPRECATION_BEHAVIOR=raise` does not find,
|
|
75
|
+
and the two warnings whose fix is not a removed API's replacement. Read each entry.
|
|
76
|
+
- [Removed APIs](#removed-apis) is one table of every API removed in v6.0.0 and its
|
|
77
|
+
replacement. Every one of them warned in v5.x when called, constructed, or used, so
|
|
78
|
+
the raise behavior finds each call, and the table links to the entry under
|
|
79
|
+
"Upgrading to v5.x" that maps each call shape to its replacement. A bare reference
|
|
80
|
+
to a removed constant did not warn, so step 8 has you search for those.
|
|
81
|
+
- [Deprecated in v6.0.0](#deprecated-in-v600) covers the APIs that warn in v6.0.0 and
|
|
82
|
+
are removed in a later major release.
|
|
83
|
+
|
|
84
|
+
If you are upgrading from v4.x directly, the v5.x warnings never ran against your
|
|
85
|
+
code, so also read [Upgrading to v5.x](#upgrading-to-v5x). Its entries map each v4.x
|
|
86
|
+
call to its replacement, and the [Removed APIs](#removed-apis) table tells you which of
|
|
87
|
+
those replacements are now the only option.
|
|
88
|
+
|
|
89
|
+
### Before you upgrade
|
|
90
|
+
|
|
91
|
+
1. Upgrade to Ruby 3.3 or later if you are still on Ruby 3.2 (see
|
|
92
|
+
[Minimum Ruby version](#minimum-ruby-version)).
|
|
93
|
+
2. Check that `git --version` reports 2.43.0 or later everywhere the gem runs (see
|
|
94
|
+
[Minimum git version](#minimum-git-version)).
|
|
95
|
+
3. Run `bundle update addressable` and confirm the lockfile resolves addressable
|
|
96
|
+
2.9.0 or later (see [Minimum addressable version](#minimum-addressable-version)).
|
|
97
|
+
4. Run `bundle update activesupport` and confirm the lockfile resolves activesupport
|
|
98
|
+
7.0.9 or later (see [Minimum activesupport version](#minimum-activesupport-version)).
|
|
99
|
+
5. Upgrade to the latest v5.x release.
|
|
100
|
+
6. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
|
|
101
|
+
your test suite and, if possible, staging.
|
|
102
|
+
7. Fix each deprecation until the suite is clean. The [Removed APIs](#removed-apis)
|
|
103
|
+
table links each removed API's replacement. Three warnings are not removals:
|
|
104
|
+
- `stash_list` keeps its name and changes its return type (see [`stash_list`
|
|
105
|
+
returns an Array of `Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)).
|
|
106
|
+
- A context-helper block with no positional parameter, which v5.6.0 and later
|
|
107
|
+
warn about (see [Context helpers yield a separate
|
|
108
|
+
repository](#context-helpers-yield-a-separate-repository)).
|
|
109
|
+
- `Git::GitExecuteError`, which still warns in v6.0.0 (see
|
|
110
|
+
[`Git::GitExecuteError` deprecated](#gitgitexecuteerror-deprecated)).
|
|
111
|
+
8. Search your code for each constant in the [Removed APIs](#removed-apis) table. A
|
|
112
|
+
bare reference such as `is_a?(Git::Base)`, `rescue Git::Status`, or
|
|
113
|
+
`case ... when Git::Author` never warned in v5.x, so the raise behavior does not
|
|
114
|
+
find it, and it raises `NameError` in v6.0.0.
|
|
115
|
+
9. Work through each entry under [Changes the deprecation run does not catch or does
|
|
116
|
+
not explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain). The two
|
|
117
|
+
that affect the most code:
|
|
118
|
+
- Replace any `rescue Errno::*` around gem calls with `rescue Git::Error` (see
|
|
119
|
+
[Filesystem errors raised as `Git::Error`](#filesystem-errors-raised-as-giterror)).
|
|
120
|
+
- Give every `with_index`, `with_temp_index`, `with_working`, and
|
|
121
|
+
`with_temp_working` block a parameter and call methods on it rather than on the
|
|
122
|
+
outer repository; v5.6.0 and later warn for a block with no positional parameter
|
|
123
|
+
(see [Context helpers yield a separate
|
|
124
|
+
repository](#context-helpers-yield-a-separate-repository)).
|
|
125
|
+
10. Upgrade to v6.0.0.
|
|
126
|
+
|
|
127
|
+
#### Minimum Ruby version
|
|
128
|
+
|
|
129
|
+
v6.0.0 requires Ruby 3.3.0 or later. v5.x supports Ruby 3.2, which reached end of
|
|
130
|
+
life on 2026-03-31. The
|
|
131
|
+
[Ruby version support policy](README.md#ruby-version-support-policy) commits the
|
|
132
|
+
gem to the MRI versions that are still maintained, so the floor moves when a Ruby
|
|
133
|
+
version leaves maintenance rather than with the gem's major version. Ruby 3.3 is
|
|
134
|
+
in security maintenance until about 2027-03-31, so it stays supported in v6.0.0.
|
|
135
|
+
A 3.4 floor can land in a later v6.x release once 3.3 reaches end of life.
|
|
136
|
+
|
|
137
|
+
JRuby and TruffleRuby support is unchanged.
|
|
138
|
+
|
|
139
|
+
If your application still runs on Ruby 3.2, upgrade Ruby before upgrading the gem,
|
|
140
|
+
or stay on the latest v5.x release.
|
|
141
|
+
|
|
142
|
+
#### Minimum git version
|
|
143
|
+
|
|
144
|
+
v6.0.0 requires git 2.43.0 or later. v5.x required 2.28.0.
|
|
145
|
+
|
|
146
|
+
Git 2.43.0 was released on November 20, 2023, and is the version shipped by
|
|
147
|
+
Ubuntu 24.04, RHEL 8.10 and 9.4, SLES 15 SP6, openSUSE Leap 15.6, and Alpine 3.19.
|
|
148
|
+
Ubuntu 22.04 (git 2.34) and Debian 12 (git 2.39) are the supported platforms whose
|
|
149
|
+
stock git falls below the new floor. On Ubuntu 22.04, install a newer git (for
|
|
150
|
+
example from the [git-core PPA](https://launchpad.net/~git-core/+archive/ubuntu/ppa));
|
|
151
|
+
on Debian 12, install it from
|
|
152
|
+
[bookworm-backports](https://backports.debian.org/Instructions/); or stay on v5.x.
|
|
153
|
+
Apple's git 2.39 from Xcode 16 also falls below the floor; Xcode 26 ships git 2.50.
|
|
154
|
+
|
|
155
|
+
Features that need a git newer than 2.43.0 stay gated per command and raise
|
|
156
|
+
`Git::VersionError` on older installations, as `git am --retry` (2.46.0) does today.
|
|
157
|
+
|
|
158
|
+
#### Minimum addressable version
|
|
159
|
+
|
|
160
|
+
v6.0.0 depends on `addressable ~> 2.9`. v5.x accepts `~> 2.8`.
|
|
161
|
+
|
|
162
|
+
Addressable 2.9.0 (released in April 2026) fixes the ReDoS vulnerability in
|
|
163
|
+
`Addressable::Template#match`
|
|
164
|
+
([GHSA-h27x-rffw-24p4](https://github.com/sporkmonger/addressable/security/advisories/GHSA-h27x-rffw-24p4)).
|
|
165
|
+
Addressable 2.8.10 mitigates only part of it, and the advisory lists every release
|
|
166
|
+
below 2.9.0 as affected. The gem never calls `Addressable::Template`, so v5.x is not
|
|
167
|
+
affected and keeps the wider constraint. v6.0.0 raises the floor to the 2.9 series so
|
|
168
|
+
that dependency scanners stop flagging the gem's resolved dependency tree.
|
|
169
|
+
|
|
170
|
+
The `~> 2.8` constraint already permits 2.9.0, so most applications resolve it after
|
|
171
|
+
`bundle update addressable`. The upgrade fails only when another gem in the bundle
|
|
172
|
+
caps addressable below 2.9.0. In that case, update or replace that gem, or stay on
|
|
173
|
+
the latest v5.x release.
|
|
174
|
+
|
|
175
|
+
#### Minimum activesupport version
|
|
176
|
+
|
|
177
|
+
v6.0.0 depends on `activesupport >= 7.0.9`. v5.x accepts `>= 5.0`.
|
|
178
|
+
|
|
179
|
+
Two things set the floor. The `Git::GitExecuteError` deprecation warning passes its
|
|
180
|
+
text to ActiveSupport's `DeprecatedConstantProxy` through the `message:` keyword, which
|
|
181
|
+
no release before 6.0.3 accepts on Ruby 3. Separately, activesupport requires
|
|
182
|
+
`base64`, `bigdecimal`, `drb`, and `mutex_m` from the standard library, and Ruby 3.4
|
|
183
|
+
removed those from the default gems, so on Ruby 3.4 or later `require 'git'` fails
|
|
184
|
+
under Bundler unless a gem in the bundle declares them. Activesupport 7.0.9 is the
|
|
185
|
+
first 7.0.x release that declares them as dependencies; every 7.1.0 and later release
|
|
186
|
+
does too. The floor applies on every Ruby version so that Bundler reports the conflict
|
|
187
|
+
when it resolves the bundle, instead of `require 'git'` failing on Ruby 3.4.
|
|
188
|
+
|
|
189
|
+
Most applications already resolve a newer activesupport. The upgrade fails only when
|
|
190
|
+
another gem in the bundle caps activesupport below 7.0.9. In that case, update or
|
|
191
|
+
replace that gem, or stay on the latest v5.x release.
|
|
192
|
+
|
|
193
|
+
### Changes the deprecation run does not catch or does not explain
|
|
194
|
+
|
|
195
|
+
Most changes below never emitted a warning in v5.x, because the method keeps its name
|
|
196
|
+
and changes what it returns or does, or keeps working after the upgrade with a
|
|
197
|
+
different result. Two of them warned, `stash_list` and the context-helper block form,
|
|
198
|
+
but neither is a removed API, so the [Removed APIs](#removed-apis) table has no row
|
|
199
|
+
for them and their entries live here. A clean run under
|
|
200
|
+
`GIT_DEPRECATION_BEHAVIOR=raise` is therefore not proof that your code is unaffected.
|
|
201
|
+
Search your code for each one before upgrading.
|
|
202
|
+
|
|
203
|
+
#### Filesystem errors raised as `Git::Error`
|
|
204
|
+
|
|
205
|
+
The gem's own filesystem calls used to let a bare `SystemCallError` escape, which
|
|
206
|
+
contradicted the documented contract that the gem raises only `ArgumentError` or a
|
|
207
|
+
`Git::Error` subclass. Those calls now raise `Git::Error`, with the original error
|
|
208
|
+
available through `cause`.
|
|
209
|
+
|
|
210
|
+
The affected methods are `Git.open` (reading a gitdir pointer file), `Git.export`,
|
|
211
|
+
`Git::Repository#chdir`, `#with_index`, `#with_working`, `#with_temp_index`,
|
|
212
|
+
`#with_temp_working`, `#set_index`, `#set_working`, `#cat_file_contents`,
|
|
213
|
+
`#each_conflict`, `#archive`, and `#repo_size`. `Git.init`, `Git.clone`, `Git.bare`,
|
|
214
|
+
and `Git.open` also raise `Git::Error` when the directory argument or a
|
|
215
|
+
`:repository`, `:index`, or `:chdir` option cannot be expanded to an absolute path,
|
|
216
|
+
which happens when the process working directory has been removed.
|
|
217
|
+
|
|
218
|
+
```ruby
|
|
219
|
+
# v5.x
|
|
220
|
+
begin
|
|
221
|
+
Git.open('/path/to/repo')
|
|
222
|
+
rescue Errno::EACCES => e
|
|
223
|
+
handle_permission_problem(e)
|
|
224
|
+
end
|
|
225
|
+
|
|
226
|
+
# v6.x
|
|
227
|
+
begin
|
|
228
|
+
Git.open('/path/to/repo')
|
|
229
|
+
rescue Git::Error => e
|
|
230
|
+
raise unless e.cause.is_a?(Errno::EACCES)
|
|
231
|
+
|
|
232
|
+
handle_permission_problem(e.cause)
|
|
233
|
+
end
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Code that already rescues `Git::Error` needs no change. A `SystemCallError` raised by
|
|
237
|
+
your own block inside `chdir`, `with_working`, `with_temp_index`, `with_temp_working`,
|
|
238
|
+
or the block form of `cat_file_contents` still propagates unchanged, so the gem never
|
|
239
|
+
relabels an error raised by your code.
|
|
240
|
+
|
|
241
|
+
#### Gzip failures in `archive` raised as `Git::Error`
|
|
242
|
+
|
|
243
|
+
`Git::Repository#archive` with `format: 'tgz'` or `add_gzip: true` used to let a
|
|
244
|
+
`Zlib::Error` subclass escape when compression failed. It now raises `Git::Error`, with
|
|
245
|
+
the `Zlib::Error` available through `cause`. Code that already rescues `Git::Error`
|
|
246
|
+
needs no change.
|
|
247
|
+
|
|
248
|
+
#### Relative `:repository` and `:index` paths
|
|
249
|
+
|
|
250
|
+
A relative `:repository` option of `Git.open` or `Git.init`, and a relative `:index`
|
|
251
|
+
option of `Git.open`, `Git.init`, or `Git.clone`, is now expanded against the process
|
|
252
|
+
working directory, the same way the positional directory argument, `set_index`, and
|
|
253
|
+
`set_working` treat a relative path. A relative `:repository` used to be expanded
|
|
254
|
+
against the working directory, and a relative `:index` against the git directory.
|
|
255
|
+
For `Git.clone` with the `:chdir` option, a relative `:index` is expanded against
|
|
256
|
+
`:chdir` instead, like the clone directory itself.
|
|
257
|
+
|
|
258
|
+
Omitted options resolve as before: `:repository` defaults to `<working_dir>/.git` and
|
|
259
|
+
`:index` to `<git_dir>/index`. Absolute paths are unaffected. A relative `:repository`
|
|
260
|
+
option of `Git.clone` keeps its meaning: it is relative to `:chdir` when given and to
|
|
261
|
+
the process working directory otherwise, which is where git already resolved it.
|
|
262
|
+
|
|
263
|
+
```ruby
|
|
264
|
+
# v5.x: the index is bound to /path/to/repo/.git/scratch.index
|
|
265
|
+
repo = Git.open('/path/to/repo', index: 'scratch.index')
|
|
266
|
+
|
|
267
|
+
# v6.x: the index is bound to scratch.index in the process working directory.
|
|
268
|
+
# Join the path yourself to keep the v5.x location.
|
|
269
|
+
repo = Git.open('/path/to/repo', index: '/path/to/repo/.git/scratch.index')
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
#### Tilde expansion in `Git.init` and `Git.clone` paths
|
|
273
|
+
|
|
274
|
+
`Git.init` and `Git.clone` now expand the directory argument and the `:repository` and
|
|
275
|
+
`:index` options before handing the path to git, so `~` is the home directory, as it
|
|
276
|
+
already is for `Git.bare`, `set_index`, and `set_working`. `Git.clone` expands its
|
|
277
|
+
`:chdir` option the same way, and `Git.open` expands its directory argument before
|
|
278
|
+
checking that it exists, so `Git.open('~/scratch')` opens the repository instead of
|
|
279
|
+
raising `ArgumentError`. git does no tilde expansion on its arguments, so a `~`-prefixed
|
|
280
|
+
path used to make git create a directory literally named `~` under the process working
|
|
281
|
+
directory, or under `:chdir` for `Git.clone`. For `Git.init('~/scratch')` the returned
|
|
282
|
+
repository then pointed at `$HOME/scratch`, which git had not created, and the first
|
|
283
|
+
command run on it failed. For a `~`-prefixed `:repository` or `:chdir` option of
|
|
284
|
+
`Git.clone`, git failed before cloning anything.
|
|
285
|
+
|
|
286
|
+
A caller who passed a `~`-prefixed path and wanted a directory named `~` must anchor
|
|
287
|
+
the path to keep it. Expanding before git runs is also visible in three other ways:
|
|
288
|
+
|
|
289
|
+
- git receives absolute paths, so a `:log` that recorded `Cloning into 'my-repo'...` now
|
|
290
|
+
records the absolute path.
|
|
291
|
+
- A `:repository`, `:index`, or `:chdir` that cannot be expanded raises before git runs,
|
|
292
|
+
with nothing on disk, instead of after the clone or init completed: `Git::Error` when
|
|
293
|
+
the process working directory has been removed, and `ArgumentError` for a `~user`
|
|
294
|
+
prefix that names no user.
|
|
295
|
+
- `..` is normalized lexically before git sees the path. `Git.init('a/../b')` creates
|
|
296
|
+
only `b`, where `git init a/../b` at a shell prompt also created `a`, and a path
|
|
297
|
+
through a symlinked directory resolves to where the link appears rather than where it
|
|
298
|
+
points.
|
|
299
|
+
|
|
300
|
+
The rule these methods now share is recorded in
|
|
301
|
+
[ADR-0010](docs/adr/0010-a-repository-locating-path-means-what-it-would-mean-at-a-shell-prompt.md).
|
|
302
|
+
|
|
303
|
+
```ruby
|
|
304
|
+
# v5.x: git creates ./~/scratch; the returned repository points at $HOME/scratch
|
|
305
|
+
repo = Git.init('~/scratch')
|
|
306
|
+
|
|
307
|
+
# v6.x: git creates $HOME/scratch and the returned repository is bound to it
|
|
308
|
+
repo = Git.init('~/scratch')
|
|
309
|
+
|
|
310
|
+
# v6.x: anchor the path to keep a directory literally named ~
|
|
311
|
+
repo = Git.init('./~/scratch')
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
#### Context helpers yield a separate repository
|
|
315
|
+
|
|
316
|
+
`Git::Repository#with_index`, `#with_temp_index`, `#with_working`, and
|
|
317
|
+
`#with_temp_working` used to rebind the receiver to the other index or working tree
|
|
318
|
+
for the duration of the block and yield the receiver itself. They now build a second
|
|
319
|
+
repository of the receiver's class bound to that index or working tree, yield it,
|
|
320
|
+
and leave the receiver bound to its original index and working tree.
|
|
321
|
+
|
|
322
|
+
Code that uses the block parameter and finishes with it before the block ends needs
|
|
323
|
+
no change. A block that declares no positional parameter, the v5.x form, now raises
|
|
324
|
+
`ArgumentError` before the block runs. Starting in v5.6.0 that form warns through
|
|
325
|
+
`Git::Deprecation`, so clear the warning on the latest v5.x release before upgrading.
|
|
326
|
+
A call with no block raises `ArgumentError` instead of `LocalJumpError`. Code that
|
|
327
|
+
declares the parameter but ignores it and calls methods on the outer repository
|
|
328
|
+
inside the block runs those calls against the original index or working tree. Use the
|
|
329
|
+
block parameter instead:
|
|
330
|
+
|
|
331
|
+
```ruby
|
|
332
|
+
# v5.x
|
|
333
|
+
repo.with_temp_index do
|
|
334
|
+
repo.read_tree('HEAD')
|
|
335
|
+
repo.write_tree
|
|
336
|
+
end
|
|
337
|
+
|
|
338
|
+
# v6.x
|
|
339
|
+
repo.with_temp_index do |indexed|
|
|
340
|
+
indexed.read_tree('HEAD')
|
|
341
|
+
indexed.write_tree
|
|
342
|
+
end
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
The same applies to reading `index` or `dir` inside the block to find the temporary
|
|
346
|
+
path: read them on the block parameter. A block that needs only the changed process
|
|
347
|
+
directory, such as one that writes files inside `with_temp_working`, still declares
|
|
348
|
+
the parameter (`do |_scratch|`).
|
|
349
|
+
|
|
350
|
+
A helper nested inside another must also be called on the block parameter. A nested
|
|
351
|
+
call on the outer repository derives from the outer repository's original index and
|
|
352
|
+
working tree, so it does not see the outer block's temporary location:
|
|
353
|
+
|
|
354
|
+
```ruby
|
|
355
|
+
# v5.x
|
|
356
|
+
repo.with_temp_working do
|
|
357
|
+
repo.with_temp_index do
|
|
358
|
+
repo.add('.')
|
|
359
|
+
repo.write_tree
|
|
360
|
+
end
|
|
361
|
+
end
|
|
362
|
+
|
|
363
|
+
# v6.x
|
|
364
|
+
repo.with_temp_working do |scratch|
|
|
365
|
+
scratch.with_temp_index do |indexed|
|
|
366
|
+
indexed.add('.')
|
|
367
|
+
indexed.write_tree
|
|
368
|
+
end
|
|
369
|
+
end
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Calling `set_index` or `set_working` on the outer repository inside the block is no
|
|
373
|
+
longer undone when the block ends. In v5.x the block restored the receiver's
|
|
374
|
+
original index and working tree on exit; in v6.x there is no restore step, so the
|
|
375
|
+
receiver stays bound to whatever `set_index` or `set_working` gave it. Both methods
|
|
376
|
+
are deprecated in v6.0.0 (see [`set_index` and `set_working`
|
|
377
|
+
deprecated](#set_index-and-set_working-deprecated)).
|
|
378
|
+
|
|
379
|
+
The repository yielded by `with_temp_index` or `with_temp_working` stays bound to
|
|
380
|
+
the temporary path after the block removes it. This is the one case where code that
|
|
381
|
+
already used the block parameter has to change. If the yielded repository escapes
|
|
382
|
+
the block, directly or inside an object that holds it and later runs commands, calls
|
|
383
|
+
against the removed working tree raise `Git::Error`. Against the removed index,
|
|
384
|
+
reads do not raise: git treats the missing index file as an empty index, so
|
|
385
|
+
`ls_files` returns nothing and `status_info` reports every tracked file both as
|
|
386
|
+
deleted and as untracked. Writes such as `add` do raise `Git::Error`. Reads from
|
|
387
|
+
the object database, such as `Git::Object::AbstractObject#contents`, still work. In
|
|
388
|
+
v5.x an escaped object held the outer repository, which had been rebound to the
|
|
389
|
+
original path by then.
|
|
390
|
+
|
|
391
|
+
The yielded repository is built with `self.class.new(execution_context:)`, so a
|
|
392
|
+
subclass of `Git::Repository` has to accept that call. A subclass whose `initialize`
|
|
393
|
+
takes different keywords raises `ArgumentError` from these helpers. One that takes a
|
|
394
|
+
positional argument instead receives the keywords as a Hash and yields a
|
|
395
|
+
misconfigured repository, so check the constructor rather than waiting for an
|
|
396
|
+
exception.
|
|
397
|
+
|
|
398
|
+
`with_working` and `with_temp_working` still change the process working directory
|
|
399
|
+
with `Dir.chdir` for the duration of the block, so they remain unsafe to call from
|
|
400
|
+
more than one thread at a time.
|
|
401
|
+
|
|
402
|
+
#### `Git.init`, `Git.open`, and `Git.bare` reject unknown options
|
|
403
|
+
|
|
404
|
+
`Git.init`, `Git.open`, and `Git.bare` now raise `ArgumentError` when the options
|
|
405
|
+
hash contains a key they do not accept, the same way `Git.ls_remote` already does.
|
|
406
|
+
v5.x ignored unknown keys, so a typo such as `respository:` or an unsupported key
|
|
407
|
+
silently returned a repository bound to paths the caller did not ask for, and
|
|
408
|
+
`Git.init` created the repository in the default location instead of the one
|
|
409
|
+
the mistyped key was meant to name.
|
|
410
|
+
|
|
411
|
+
For the APIs that did validate option names in v5.x, see
|
|
412
|
+
[Unsupported options raise `ArgumentError`](#unsupported-options-raise-argumenterror).
|
|
413
|
+
|
|
414
|
+
The accepted keys are:
|
|
415
|
+
|
|
416
|
+
- `Git.init`: `:bare`, `:initial_branch`, `:repository`, `:separate_git_dir`,
|
|
417
|
+
`:index`, `:log`, `:git_ssh`, and `:binary_path`
|
|
418
|
+
- `Git.open`: `:repository`, `:index`, `:log`, `:git_ssh`, and `:binary_path`
|
|
419
|
+
- `Git.bare`: `:index`, `:log`, `:git_ssh`, and `:binary_path`
|
|
420
|
+
|
|
421
|
+
The check runs before any filesystem or git call, so a bad key fails fast. To fix a
|
|
422
|
+
call that now raises, drop the key.
|
|
423
|
+
|
|
424
|
+
```ruby
|
|
425
|
+
# v5.x: the typo is ignored and the .git directory is auto-detected
|
|
426
|
+
# v6.x: raises ArgumentError, "Unknown options: respository"
|
|
427
|
+
repo = Git.open('/path/to/worktree', respository: '/srv/repo.git')
|
|
428
|
+
|
|
429
|
+
# v6.x: the corrected call opens the repository
|
|
430
|
+
repo = Git.open('/path/to/worktree', repository: '/srv/repo.git')
|
|
431
|
+
|
|
432
|
+
# v5.x: the typo is ignored and the repository is created at /path/to/worktree/.git
|
|
433
|
+
# v6.x: raises ArgumentError, "Unknown options: separate_gitdir"
|
|
434
|
+
repo = Git.init('/path/to/worktree', separate_gitdir: '/srv/repo.git')
|
|
435
|
+
|
|
436
|
+
# v6.x: the corrected call creates the repository at /srv/repo.git
|
|
437
|
+
repo = Git.init('/path/to/worktree', separate_git_dir: '/srv/repo.git')
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
#### `tag_create` raises when the created tag is missing
|
|
441
|
+
|
|
442
|
+
In v5.x, `g.tag_create` returned `nil` when the tag it had just created was missing from
|
|
443
|
+
the tag list (for example, another process deleted it before the lookup). It never
|
|
444
|
+
emitted a deprecation warning, since the method keeps its name. In v6.0.0 it raises
|
|
445
|
+
`Git::UnexpectedResultError` instead, so its return value is always a `Git::TagInfo`.
|
|
446
|
+
Search for `tag_create` before upgrading and remove any check for a `nil` result.
|
|
447
|
+
|
|
448
|
+
#### `stash_list` returns an Array of `Git::StashInfo`
|
|
449
|
+
|
|
450
|
+
In v5.x, `g.stash_list` returned the `git stash list` text as a `String` and emitted a
|
|
451
|
+
`Git::Deprecation` warning on every call. A project that silences or ignores deprecation
|
|
452
|
+
warnings never acts on that notice, and in v6.0.0 the call keeps working with a
|
|
453
|
+
different return type: `Array<Git::StashInfo>`, newest first, the same value as
|
|
454
|
+
`Git::Repository#stash_infos`, which stays as a permanent alias. Search for `stash_list`
|
|
455
|
+
before upgrading. Code that needs the text builds it from the entries:
|
|
456
|
+
`g.stash_list.map { |s| "#{s.name}: #{s.message}" }.join("\n")`.
|
|
457
|
+
|
|
458
|
+
#### `stash_store` raises when the stored entry is missing
|
|
459
|
+
|
|
460
|
+
In v5.x, `g.stash_store` returned the top entry of the stash list after the store, so it
|
|
461
|
+
returned `nil` when the list was empty and another process's entry when one had been
|
|
462
|
+
pushed in between. It never emitted a deprecation warning, since the method keeps its
|
|
463
|
+
name. In v6.0.0 it returns the entry for the commit it stored and raises
|
|
464
|
+
`Git::UnexpectedResultError` when that entry is missing, so its return value is always a
|
|
465
|
+
`Git::StashInfo`. A commit that does not resolve raises `Git::FailedError` before
|
|
466
|
+
anything is stored. A `nil` commit or one that begins with `-` raises `ArgumentError` as
|
|
467
|
+
in v5.x, with a different message; one that begins with `^` raises `ArgumentError` where
|
|
468
|
+
v5.x raised `Git::FailedError`. An annotated tag name now stores the tagged commit; v5.x
|
|
469
|
+
stored the tag object, which hid every entry from `git stash list`. Search for
|
|
470
|
+
`stash_store` before upgrading and remove any check for a `nil` result.
|
|
471
|
+
|
|
472
|
+
#### `worktree_add` returns `Git::WorktreeInfo` and raises when the worktree is missing
|
|
473
|
+
|
|
474
|
+
In v4.x and v5.x, `g.worktree_add` returned the `git worktree add` output
|
|
475
|
+
(`"HEAD is now at …"`) as a `String` and never emitted a deprecation warning, since the
|
|
476
|
+
method keeps its name. In v6.0.0 it returns the new worktree's `Git::WorktreeInfo`, the
|
|
477
|
+
same entry `g.worktree_list` reports for it, and raises `Git::UnexpectedResultError`
|
|
478
|
+
when that entry is missing after the add, as `tag_create` and `stash_store` do. A
|
|
479
|
+
`rescue Git::FailedError` around the call no longer covers every error it can raise.
|
|
480
|
+
Search for `worktree_add` before upgrading.
|
|
481
|
+
Code that used the return value as a `String` reads `info.path`, `info.head`, and
|
|
482
|
+
`info.branch` instead; `Git::WorktreeInfo#to_s` is the path, so string interpolation of
|
|
483
|
+
the result yields the worktree path.
|
|
484
|
+
|
|
485
|
+
#### `Git::Deprecation` horizon is prose
|
|
486
|
+
|
|
487
|
+
v6.0.0 constructs `Git::Deprecation` with the horizon `"in a future major release"`.
|
|
488
|
+
v5.x used `"6.0.0"`. The gem never puts the horizon into a warning, so the warnings
|
|
489
|
+
themselves do not change. The horizon reaches your code through the
|
|
490
|
+
`Git::Deprecation.deprecation_horizon` reader, the `deprecation_horizon` key of the
|
|
491
|
+
payload the `:notify` behavior publishes, and the third argument of a custom
|
|
492
|
+
`behavior` or `disallowed_behavior` proc declared with four parameters. Code that
|
|
493
|
+
parses that value as a version, for example with `Gem::Version.new`, now raises; read
|
|
494
|
+
the removal version from the warning text instead, which names it once it is decided.
|
|
495
|
+
|
|
496
|
+
### Removed APIs
|
|
497
|
+
|
|
498
|
+
Every API in this table emitted a deprecation warning in v5.x that named its
|
|
499
|
+
replacement when it was called, constructed, or used, and each row links to the entry
|
|
500
|
+
under "Upgrading to v5.x" that maps every call shape, reader, and option to its
|
|
501
|
+
replacement, including return shape differences. A bare reference to a removed
|
|
502
|
+
constant (`is_a?`, `rescue`, `case ... when`, `defined?`) did not warn, except for
|
|
503
|
+
`Git::CommandLineResult`, so search for each constant in the table as well as
|
|
504
|
+
clearing the warnings. In v6.0.0 a removed constant raises `NameError` when
|
|
505
|
+
referenced, a removed method raises `NoMethodError` when called, and a removed option
|
|
506
|
+
raises `ArgumentError` like any other unsupported option (see [Unsupported options
|
|
507
|
+
raise `ArgumentError`](#unsupported-options-raise-argumenterror)).
|
|
508
|
+
|
|
509
|
+
| Removed in v6.0.0 | Use instead | Migration entry |
|
|
510
|
+
| --- | --- | --- |
|
|
511
|
+
| `Git::Repository#add_remote`, `#remove_remote`, `#set_remote_url`, `#add_tag`, `#delete_tag` | `remote_add`, `remote_remove`, `remote_set_url`, `tag_create`, `tag_delete` | [Facade method renames](#facade-method-renames) |
|
|
512
|
+
| `Git::Repository#empty?`, `#reset_hard`, `#conflicts`, `#is_local_branch?`, `#is_remote_branch?`, `#is_branch?`, `#branches_all` | `no_commits?`, `reset(commitish, hard: true)`, `each_conflict`, `local_branch?`, `remote_branch?`, `branch?`, `branch_list` | [`Git::Repository` method renames](#gitrepository-method-renames) |
|
|
513
|
+
| `Git::Repository#object_contents`, `#object_size`, `#object_type`, `#commit_data`, `#tag_data`, `#revparse`, `#namerev`, `#diff_name_status` | `cat_file_contents`, `cat_file_size`, `cat_file_type`, `cat_file_commit`, `cat_file_tag`, `rev_parse`, `name_rev`, `diff_path_status` | [`Git::Repository` alias renames](#gitrepository-alias-renames) |
|
|
514
|
+
| `clean(ff: true)` and `clean(force_force: true)`; `diff_path_status(path: ...)`; `commit(add_all: true)`; the positional `check` argument of `set_working` and `set_index` | `force: 2`; `:path_limiter`; `:all`; `must_exist:` | [`Git::Repository` option renames](#gitrepository-option-renames) |
|
|
515
|
+
| `Git::Repository#config` and `#global_config`; `Git.global_config`; `config` and `global_config` as instance methods of the `Git` module | `config_get`, `config_set`, and `config_list` on `Git::Repository` or `Git`, with `global: true` for the global scope | [v4.x-style configuration methods](#v4x-style-configuration-methods), [`Git` module mixin deprecations](#git-module-mixin-deprecations) |
|
|
516
|
+
| `Git.binary_version`; `Git.ls_remote(nil)` | `Git.git_version` (`.to_a` for the Array); `Git.ls_remote` with no argument or `'.'` | [Module-level `Git` function deprecations](#module-level-git-function-deprecations) |
|
|
517
|
+
| `Git.clone` options `:path`, `:recursive`, and `:remote` | `:chdir`, `:recurse_submodules`, and `:origin` | [`Git.clone` option renames](#gitclone-option-renames) |
|
|
518
|
+
| `Git.export` option `:remote` | Delete the option; it has no replacement | [`Git.export` `:remote` option deprecated](#gitexport-remote-option-deprecated) |
|
|
519
|
+
| `Git::Base` | Include an application-owned module into `Git::Repository` | [`Git::Base` removed](#gitbase-removed) |
|
|
520
|
+
| `Git::Repository#lib` | Call the facade method directly on the repository | [`Git::Lib` removed](#gitlib-removed) |
|
|
521
|
+
| `Git::CommandLineResult` | `Git::CommandLine::Result` | [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated) |
|
|
522
|
+
| `Git::Log#each`, `#size`, `#to_s`, `#first`, `#last`, `#[]`, and every other `Enumerable` method on `Git::Log` | `Git::Log#execute`, which returns a `Git::Log::Result` with the same methods | [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated) |
|
|
523
|
+
| `Git::Object::Commit#set_commit` | `from_data` | [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated) |
|
|
524
|
+
| `Git::Author` | `Git::AuthorInfo` (`parse` to build one, `with` in place of the writers) | [`Git::Author` deprecated](#gitauthor-deprecated) |
|
|
525
|
+
| `Git::Branch#stashes` | `Git::Repository#stash_infos` | [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
|
|
526
|
+
| `Git::Stash`, `Git::Stashes`, `Git::Repository#stashes_all`, `#stash_save` | `stash_list` (or its alias `stash_infos`), `stash_push`, and the name-based stash operations | [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
|
|
527
|
+
| `Git::Repository#remotes` | `remote_list`, or `remote_names` for the names alone | [`Git::Repository#remotes` deprecated](#gitrepositoryremotes-deprecated) |
|
|
528
|
+
| `Git::Remote`, `Git::Repository#remote`, `#config_remote` | `remote_list`, which returns `Git::RemoteInfo` objects; filter `config_list` on the `remote.<name>.` prefix for keys it does not model | [`Git::Remote` deprecated](#gitremote-deprecated) |
|
|
529
|
+
| The `allow_unknown_type:` option of `Git::Commands::CatFile::Raw` | No replacement | [`Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated](#gitcommandscatfileraw-allow_unknown_type-option-deprecated) |
|
|
530
|
+
| `Git::Branch`, `Git::Branches`, `Git::Repository#branch`, `#branches` | `branch_list`, which returns `Git::BranchInfo` objects, and the name-based branch operations | [`Git::Branch` and `Git::Branches` deprecated](#gitbranch-and-gitbranches-deprecated) |
|
|
531
|
+
| `Git::Object::Tag`, `Git::Repository#tag`, `#tags`, `#tag_add`, and the `is_tag` argument of `Git::Object.new` | `tag_list` and `tag_create`, which return `Git::TagInfo` objects | [`Git::Object::Tag` deprecated](#gitobjecttag-deprecated) |
|
|
532
|
+
| `Git::Status`, `Git::Status::StatusFile`, `Git::Repository#status` | `status_info`, which returns a `Git::StatusInfo` | [`Git::Status` deprecated](#gitstatus-deprecated) |
|
|
533
|
+
| `Git::Worktree`, `Git::Worktrees`, `Git::Repository#worktree`, `#worktrees`, `#worktrees_all` | `worktree_list`, which returns `Git::WorktreeInfo` objects, and the path-based worktree operations | [`Git::Worktree` and `Git::Worktrees` deprecated](#gitworktree-and-gitworktrees-deprecated) |
|
|
534
|
+
|
|
535
|
+
Notes on specific rows:
|
|
536
|
+
|
|
537
|
+
- `add_tag`: go straight to `tag_create`. The `tag_add` that the v5.x warning names is
|
|
538
|
+
removed too.
|
|
539
|
+
- `diff_name_status` callers that passed `:path` must also switch to `:path_limiter`.
|
|
540
|
+
- `cat_file` is unaffected and stays as a legacy name for `cat_file_contents`, and
|
|
541
|
+
`stash_infos` stays as an alias of `stash_list`.
|
|
542
|
+
- `set_working` and `set_index`: a positional `check` argument raises `ArgumentError`
|
|
543
|
+
for the wrong number of arguments. Pass `must_exist:` instead; it defaults to
|
|
544
|
+
`true`. An explicit `must_exist: nil` no longer means "not given". v5.x treated it
|
|
545
|
+
as `true`, and v6.0.0 treats it as `false` like any other falsy value. Omit the
|
|
546
|
+
keyword to get the default. Both methods are deprecated in v6.0.0 (see [`set_index`
|
|
547
|
+
and `set_working` deprecated](#set_index-and-set_working-deprecated)), so consider
|
|
548
|
+
replacing the call instead of updating its arguments.
|
|
549
|
+
- `Git.ls_remote(nil)`: an explicit `nil` repository argument raises `ArgumentError`
|
|
550
|
+
with the message `repository must not be nil`. Omitting the argument still defaults
|
|
551
|
+
to `'.'`, so `Git.ls_remote` and `Git.ls_remote('.', opts)` are unchanged.
|
|
552
|
+
- `Git.config` (the gem-configuration accessor used as `Git.config.binary_path`) and
|
|
553
|
+
`Git.configure` are not part of the configuration API removal and are unchanged.
|
|
554
|
+
- `Git.export` `:remote` renamed the clone's remote, and `Git.export` deletes the `.git`
|
|
555
|
+
directory before returning, so the name was never observable.
|
|
556
|
+
- `allow_unknown_type`: git 2.50 removed the unknown-type feature and accepts the flag
|
|
557
|
+
as a no-op, and on git 2.43 through 2.49 the ability to query the type and size of an
|
|
558
|
+
object of unknown type goes with the option.
|
|
559
|
+
- `status` to `status_info`: the `changed`, `added`, `deleted`, and `untracked` readers
|
|
560
|
+
keep their names, but the categories are derived from both porcelain status
|
|
561
|
+
characters and clean tracked paths are no longer listed. Read the v5.x entry before
|
|
562
|
+
changing the call.
|
|
563
|
+
- `g.branch(name)`: the string constructor could mis-split a remote-tracking name when
|
|
564
|
+
the remote name itself contains a slash (`remotes/team/upstream/main`). `branch_list`
|
|
565
|
+
resolves configured remote names and has no such limitation.
|
|
566
|
+
|
|
567
|
+
### Deprecated in v6.0.0
|
|
568
|
+
|
|
569
|
+
Both APIs below keep working in v6.0.0 and warn through `Git::Deprecation` every time
|
|
570
|
+
they are used. A later major release removes them.
|
|
571
|
+
|
|
572
|
+
#### `set_index` and `set_working` deprecated
|
|
573
|
+
|
|
574
|
+
`Git::Repository#set_index` and `#set_working` rebind the receiver to another index
|
|
575
|
+
file or working tree. They are the last mutable state on `Git::Repository`. Once
|
|
576
|
+
they are gone, a repository object is bound at construction and never changes.
|
|
577
|
+
Until then, the rebind retargets every object that holds the receiver, such as a
|
|
578
|
+
`Git::Object`, a `Git::Log`, or a second caller that was handed the same
|
|
579
|
+
repository. v6.0.0 keeps both methods but warns on every call through
|
|
580
|
+
`Git::Deprecation`, and a later major release removes them. The warnings are:
|
|
581
|
+
|
|
582
|
+
- `Git::Repository#set_index is deprecated and will be removed in a future major
|
|
583
|
+
release. Open a repository bound to the index instead: Git.open(dir, index: path)
|
|
584
|
+
or Git.bare(git_dir, index: path).`
|
|
585
|
+
- `Git::Repository#set_working is deprecated and will be removed in a future major
|
|
586
|
+
release. Open a repository bound to the working tree instead: Git.open(work_dir,
|
|
587
|
+
repository: git_dir).`
|
|
588
|
+
|
|
589
|
+
Open a repository bound to the index or working tree up front instead of rebinding
|
|
590
|
+
it afterward. `Git.open` accepts `:index` and `:repository`, and `Git.bare` accepts
|
|
591
|
+
`:index`:
|
|
592
|
+
|
|
593
|
+
```ruby
|
|
594
|
+
# instead of
|
|
595
|
+
repo = Git.open('/path/to/repo')
|
|
596
|
+
repo.set_index('/path/to/custom.index')
|
|
597
|
+
|
|
598
|
+
# open the bound repository
|
|
599
|
+
repo = Git.open('/path/to/repo', index: '/path/to/custom.index')
|
|
600
|
+
|
|
601
|
+
# instead of
|
|
602
|
+
repo = Git.bare('/srv/repo.git')
|
|
603
|
+
repo.set_index('/tmp/scratch.index')
|
|
604
|
+
|
|
605
|
+
# open the bound bare repository
|
|
606
|
+
repo = Git.bare('/srv/repo.git', index: '/tmp/scratch.index')
|
|
607
|
+
|
|
608
|
+
# instead of
|
|
609
|
+
repo.set_working('/path/to/worktree')
|
|
610
|
+
|
|
611
|
+
# open the bound repository
|
|
612
|
+
repo = Git.open('/path/to/worktree', repository: '/path/to/repo/.git')
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
`Git.open` and `Git.bare` build the repository from scratch and carry over nothing
|
|
616
|
+
the caller does not pass. A receiver opened with a custom `:index`, `:git_ssh`,
|
|
617
|
+
`:binary_path`, or `:log` passes the same values again; `set_working` kept the
|
|
618
|
+
receiver's index, so its replacement needs `:index` whenever that index was custom.
|
|
619
|
+
When `:repository` is given without `:index`, the index resolves to
|
|
620
|
+
`<repository>/index`.
|
|
621
|
+
|
|
622
|
+
A replacement built from an existing object reads the paths back from it.
|
|
623
|
+
`repo.repo`, `repo.dir`, and `repo.index` return the `.git` directory, working tree,
|
|
624
|
+
and index file as `Pathname`s. A repository opened without `:index` has `repo.index`
|
|
625
|
+
pointing at `<git dir>/index`, so passing it back is harmless. The repository exposes
|
|
626
|
+
no public reader for `:git_ssh`, `:binary_path`, or `:log`, so a caller that opened
|
|
627
|
+
with any of them passes the same values again from wherever they were first built:
|
|
628
|
+
|
|
629
|
+
```ruby
|
|
630
|
+
# instead of
|
|
631
|
+
repo.set_working('/path/to/worktree')
|
|
632
|
+
|
|
633
|
+
# rebind from an existing object, keeping its .git directory and index
|
|
634
|
+
rebound = Git.open('/path/to/worktree',
|
|
635
|
+
repository: repo.repo.to_s, index: repo.index.to_s,
|
|
636
|
+
git_ssh: ssh_command, binary_path: git_binary, log: logger)
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
A caller that needs a copy of an existing object for the duration of a block, with
|
|
640
|
+
every setting intact, uses `with_index` or `with_working` and the block parameter.
|
|
641
|
+
The yielded repository keeps every setting the call does not replace: the logger,
|
|
642
|
+
`git_ssh`, `binary_path`, and the receiver's working tree under `with_index` or its
|
|
643
|
+
index under `with_working`:
|
|
644
|
+
|
|
645
|
+
```ruby
|
|
646
|
+
repo.with_working('/path/to/worktree') do |bound|
|
|
647
|
+
bound.add('.')
|
|
648
|
+
end
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
`set_working(dir, must_exist: false)` has no replacement. `Git.open` and
|
|
652
|
+
`with_working` both raise `ArgumentError` when the working directory does not exist,
|
|
653
|
+
so a repository can no longer be bound to a directory that is created later. When the
|
|
654
|
+
missing directory's parent exists, git runs commands that do not read the working
|
|
655
|
+
tree, such as `rev_parse` or `current_branch`, and only commands that need the
|
|
656
|
+
working tree fail until it exists; when the parent is missing too, git rejects every
|
|
657
|
+
command with an invalid path error. Create the directory, then call `Git.open`. If
|
|
658
|
+
your code needs the deferred bind, open an issue describing the use case; under
|
|
659
|
+
ADR-0007 that becomes a feature request. `set_index(path, must_exist: false)` has no
|
|
660
|
+
gap: the `:index` option is not checked for existence.
|
|
661
|
+
|
|
662
|
+
#### `Git::GitExecuteError` deprecated
|
|
663
|
+
|
|
664
|
+
`Git::GitExecuteError` has been a deprecated alias for `Git::Error` since v2.0.0 and
|
|
665
|
+
has warned whenever it is rescued or instantiated since then. The warning now follows
|
|
666
|
+
the project's deprecation policy: it names the replacement and says the alias is
|
|
667
|
+
removed in a future major release, and this entry records it. The warning is:
|
|
668
|
+
|
|
669
|
+
- `Git::GitExecuteError is deprecated and will be removed in a future major release.
|
|
670
|
+
Use Git::Error instead.`
|
|
671
|
+
|
|
672
|
+
Replace every reference with `Git::Error`. The two constants name the same class, so a
|
|
673
|
+
`rescue Git::Error` clause catches everything a `rescue Git::GitExecuteError` clause did.
|
|
674
|
+
|
|
675
|
+
```ruby
|
|
676
|
+
# instead of
|
|
677
|
+
rescue Git::GitExecuteError => e
|
|
678
|
+
|
|
679
|
+
# rescue the class directly
|
|
680
|
+
rescue Git::Error => e
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
|
|
685
|
+
## Upgrading to v5.x
|
|
686
|
+
|
|
687
|
+
### Overview
|
|
688
|
+
|
|
689
|
+
v5.0.0 replaces the internal architecture while keeping the v4.x API working
|
|
690
|
+
for most users. Most v4.x code runs on v5.x without changes.
|
|
691
|
+
|
|
692
|
+
The new architecture introduces a layered design (`Git::Commands`,
|
|
693
|
+
`Git::Repository`, and associated parsers). Compatibility shims, deprecated
|
|
694
|
+
forwarding methods that map old call patterns to the new API, keep v4.x code
|
|
695
|
+
working. These shims emit deprecation warnings that tell you what to change and
|
|
696
|
+
what v6.0.0 removes.
|
|
697
|
+
|
|
698
|
+
Hard breaks are limited to the few things that had no safe migration path.
|
|
699
|
+
The [Breaking changes](#breaking-changes) section describes them, followed by
|
|
700
|
+
[Deprecated methods](#deprecated-methods) that still work in v5.x but are
|
|
701
|
+
removed in v6.0.0.
|
|
702
|
+
|
|
703
|
+
To suppress or configure deprecation warnings, see the [Deprecations](README.md#deprecations)
|
|
704
|
+
section of the README.
|
|
705
|
+
|
|
706
|
+
Changes at a glance:
|
|
707
|
+
|
|
708
|
+
| Change | Type | Impact | Action required |
|
|
709
|
+
|--------|------|--------|-----------------|
|
|
710
|
+
| `Git::Base` removed | Hard break | High for code that references it by name | Replace with `Git::Repository` (returned by `Git.open` etc.) |
|
|
711
|
+
| `Git::Lib` removed | Hard break | High for `.lib.*` callers | Use the equivalent method directly on the repo object (see table below) |
|
|
712
|
+
| `Git.open` etc. return `Git::Repository` (not `Git::Base`) | Hard break | Low for most callers; breaks `is_a?(Git::Base)` | Update type checks and update `be_a(Git::Base)` in tests |
|
|
713
|
+
| Unsupported options now raise `ArgumentError` | Behavior change | Medium for code passing unknown or misspelled options | Check option names against the documented API |
|
|
714
|
+
| `Git::Log#object` is not a path limiter | Behavior change | Medium for code that used `object(path)` to filter logs by path | Use `Git::Log#path` for path filtering |
|
|
715
|
+
| `Git::CommandLineResult` deprecated | Deprecation (removed in v6.0.0) | Low; only affects code that references the constant by name | Use `Git::CommandLine::Result` instead |
|
|
716
|
+
|
|
717
|
+
---
|
|
718
|
+
|
|
719
|
+
### Breaking changes
|
|
720
|
+
|
|
721
|
+
#### `Git::Base` removed
|
|
722
|
+
|
|
723
|
+
`Git::Base`, the class that `Git.open`, `Git.clone`, `Git.init`, and `Git.bare`
|
|
724
|
+
returned, is removed in v5.0.0. All four entry points now return
|
|
725
|
+
`Git::Repository`, which exposes the same public API.
|
|
726
|
+
|
|
727
|
+
Code that must be updated:
|
|
728
|
+
|
|
729
|
+
```ruby
|
|
730
|
+
# v4.x: explicit Git::Base reference (raises NameError in v5.x)
|
|
731
|
+
repo = Git::Base.new(working_directory: '/path/to/repo')
|
|
732
|
+
|
|
733
|
+
# v5.x: use the entry-point methods; do not construct Git::Repository directly
|
|
734
|
+
repo = Git.open('/path/to/repo')
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
```ruby
|
|
738
|
+
# v4.x: type-checking against Git::Base (raises NameError in v5.x because Git::Base is removed)
|
|
739
|
+
raise unless repo.is_a?(Git::Base)
|
|
740
|
+
|
|
741
|
+
# v5.x: check against Git::Repository
|
|
742
|
+
raise unless repo.is_a?(Git::Repository)
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
```ruby
|
|
746
|
+
# v4.x: requiring the internal file (raises LoadError in v5.x)
|
|
747
|
+
require 'git/base'
|
|
748
|
+
|
|
749
|
+
# v5.x: the public entry point is git itself; no internal require needed
|
|
750
|
+
require 'git'
|
|
751
|
+
```
|
|
752
|
+
|
|
753
|
+
**The public API is unchanged.** `Git::Repository` provides every method that
|
|
754
|
+
`Git::Base` did. Code that calls methods on the object returned by `Git.open`
|
|
755
|
+
(e.g., `repo.commit`, `repo.status`, `repo.add`) requires no changes.
|
|
756
|
+
|
|
757
|
+
**Monkeypatching `Git::Base` is deprecated.** v5.x includes a temporary
|
|
758
|
+
compatibility shim for applications that define instance methods on `Git::Base`.
|
|
759
|
+
The shim makes those methods available on `Git::Repository` instances, but each
|
|
760
|
+
method definition emits a deprecation warning, and v6.0.0 removes the shim.
|
|
761
|
+
|
|
762
|
+
Move custom repository helpers to an application-owned extension module and
|
|
763
|
+
include or prepend that module into `Git::Repository` during application setup:
|
|
764
|
+
|
|
765
|
+
```ruby
|
|
766
|
+
# Deprecated in v5.x and removed in v6.0.0
|
|
767
|
+
module Git::Base
|
|
768
|
+
def worktree_clean?
|
|
769
|
+
status.changed.empty?
|
|
770
|
+
end
|
|
771
|
+
end
|
|
772
|
+
|
|
773
|
+
# v5.x: keep the extension in application-owned code
|
|
774
|
+
module MyAppGitRepositoryExtensions
|
|
775
|
+
def worktree_clean?
|
|
776
|
+
status.changed.empty?
|
|
777
|
+
end
|
|
778
|
+
end
|
|
779
|
+
|
|
780
|
+
Git::Repository.include(MyAppGitRepositoryExtensions)
|
|
781
|
+
```
|
|
782
|
+
|
|
783
|
+
---
|
|
784
|
+
|
|
785
|
+
#### Return type of `Git.open`, `Git.clone`, `Git.init`, `Git.bare`
|
|
786
|
+
|
|
787
|
+
`Git.open`, `Git.clone`, `Git.init`, and `Git.bare` now return
|
|
788
|
+
`Git::Repository` instead of `Git::Base`.
|
|
789
|
+
|
|
790
|
+
For most callers this is transparent, because the returned object responds to
|
|
791
|
+
the same methods. Update code that checks `is_a?(Git::Base)` or `be_a(Git::Base)`
|
|
792
|
+
in tests:
|
|
793
|
+
|
|
794
|
+
```ruby
|
|
795
|
+
# v4.x
|
|
796
|
+
expect(Git.open(repo_path)).to be_a(Git::Base)
|
|
797
|
+
|
|
798
|
+
# v5.x
|
|
799
|
+
expect(Git.open(repo_path)).to be_a(Git::Repository)
|
|
800
|
+
```
|
|
801
|
+
|
|
802
|
+
`Git::Repository` does not define `.open`, `.bare`, `.clone`, or `.init` class
|
|
803
|
+
methods. Always use `Git.open`, `Git.bare`, `Git.clone`, and `Git.init` to
|
|
804
|
+
construct a repository object.
|
|
805
|
+
|
|
806
|
+
---
|
|
807
|
+
|
|
808
|
+
#### Unsupported options raise `ArgumentError`
|
|
809
|
+
|
|
810
|
+
In v5.x, only some APIs reject unknown options: `Git.clone`, `Git.ls_remote`,
|
|
811
|
+
and most `Git::Repository` methods that accept an options hash (for example,
|
|
812
|
+
`#add`) raise `ArgumentError` for option names they do not recognize. The
|
|
813
|
+
factory methods `Git.init`, `Git.open`, and `Git.bare` do not validate option
|
|
814
|
+
names in v5.x. All three reject unknown keys in v6.0.0 (see
|
|
815
|
+
[`Git.init`, `Git.open`, and `Git.bare` reject unknown options](#gitinit-gitopen-and-gitbare-reject-unknown-options)).
|
|
816
|
+
|
|
817
|
+
For APIs that validate options, names that v4.x silently ignored may raise
|
|
818
|
+
`ArgumentError` in v5.x. Check option names against the documented API when
|
|
819
|
+
upgrading, especially for calls that pass keyword options through helper
|
|
820
|
+
methods or shared option hashes.
|
|
821
|
+
|
|
822
|
+
For example, `Git.clone` supports `log:`, not `logger:`. A misspelled or
|
|
823
|
+
unsupported option that v4.x ignored must be corrected:
|
|
824
|
+
|
|
825
|
+
```ruby
|
|
826
|
+
# v4.x: silently ignored; did not configure clone logging
|
|
827
|
+
Git.clone(url, path, logger: logger)
|
|
828
|
+
|
|
829
|
+
# v5.x: use the documented option name
|
|
830
|
+
Git.clone(url, path, log: logger)
|
|
831
|
+
```
|
|
832
|
+
|
|
833
|
+
---
|
|
834
|
+
|
|
835
|
+
#### `Git::Lib` removed
|
|
836
|
+
|
|
837
|
+
The object returned by `Git.open`, `Git.clone`, `Git.init`, and `Git.bare` previously
|
|
838
|
+
exposed a `#lib` method that gave access to `Git::Lib`, the gem's internal
|
|
839
|
+
implementation class. `Git::Lib` is removed in v5.0.0.
|
|
840
|
+
|
|
841
|
+
In v5.x, calling `#lib` on a repo object returns `self` with a deprecation
|
|
842
|
+
warning, so `g.lib.some_method(args)` calls `g.some_method(args)`, but only if
|
|
843
|
+
`some_method` exists on `Git::Repository`. Methods that were unique to `Git::Lib`
|
|
844
|
+
and have no counterpart on `Git::Repository` raise `NoMethodError` immediately.
|
|
845
|
+
The `#lib` method itself is removed in v6.0.0.
|
|
846
|
+
|
|
847
|
+
Most of what `g.lib.*` exposed is available directly on the repository object
|
|
848
|
+
(`g.*`). See the tables below for every affected method.
|
|
849
|
+
|
|
850
|
+
##### Methods that work through the `#lib` shim (with deprecation warning)
|
|
851
|
+
|
|
852
|
+
The following v4.x `g.lib.*` call shapes are forwarded to their `Git::Repository`
|
|
853
|
+
counterpart by the `#lib` shim, which returns `self`. They emit a deprecation
|
|
854
|
+
warning; migrate to the replacement shown to silence it.
|
|
855
|
+
|
|
856
|
+
> **Config return type change.** `g.lib.config_get(name)` returned a
|
|
857
|
+
> `String`; `g.lib.config_list` returned a `Hash`.
|
|
858
|
+
> The v5.x replacements `config_get` and `config_list` return
|
|
859
|
+
> `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>` respectively. Those
|
|
860
|
+
> objects expose `.value` (the String), `.key`, `.scope`, and `.origin`.
|
|
861
|
+
>
|
|
862
|
+
> If you only need the String value:
|
|
863
|
+
> - `g.config_get(name)&.value` replaces `g.lib.config_get(name)`
|
|
864
|
+
> - `g.config_list.to_h { |e| [e.key, e.value] }` replaces `g.lib.config_list`
|
|
865
|
+
>
|
|
866
|
+
> If your code was using the v4.x public `g.config(name)` API (not `g.lib.*`),
|
|
867
|
+
> that deprecated bridge still returns a `String` in v5.x and continues to work
|
|
868
|
+
> until v6.0.0.
|
|
869
|
+
|
|
870
|
+
| v4.x call | Replacement in v5.x |
|
|
871
|
+
|-----------|---------------------|
|
|
872
|
+
| `g.lib.config_get(name)` | `g.config_get(name)`. Returns `Git::ConfigEntryInfo`; use `.value` for the String |
|
|
873
|
+
| `g.lib.config_list` | `g.config_list`. Returns `Array<Git::ConfigEntryInfo>` |
|
|
874
|
+
| `g.lib.config_set(name, value)` | `g.config_set(name, value)` |
|
|
875
|
+
| `g.lib.git_version` | `g.git_version` |
|
|
876
|
+
| `g.lib.stash_list` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
|
|
877
|
+
| `g.lib.unmerged` | `g.unmerged` |
|
|
878
|
+
| `g.lib.change_head_branch(name)` | `g.change_head_branch(name)` |
|
|
879
|
+
| `g.lib.ls_remote(location, opts)` | `g.ls_remote(location, opts)` |
|
|
880
|
+
| `g.lib.current_branch_state` | `g.current_branch_state` |
|
|
881
|
+
|
|
882
|
+
> **`current_branch_state` return type change.** `g.lib.current_branch_state`
|
|
883
|
+
> returned a `Git::Lib::HeadState` (a mutable `Struct`). `g.current_branch_state`
|
|
884
|
+
> returns a `Git::Repository::Branching::HeadState` (an immutable `Data` object).
|
|
885
|
+
> Both expose `.state` (`:active`, `:unborn`, or `:detached`) and `.name`. If your
|
|
886
|
+
> code relies on the struct being mutable or uses positional construction
|
|
887
|
+
> (`Git::Lib::HeadState.new(:active, 'main')`), update to keyword construction:
|
|
888
|
+
> `Git::Repository::Branching::HeadState.new(state: :active, name: 'main')`.
|
|
889
|
+
|
|
890
|
+
##### Methods that raise `NoMethodError` in v5.x
|
|
891
|
+
|
|
892
|
+
These `Git::Lib` method names have no counterpart on `Git::Repository`, so
|
|
893
|
+
`g.lib.method_name` raises `NoMethodError` even in v5.x because the `#lib` shim
|
|
894
|
+
has nothing to forward them to. Update call sites directly:
|
|
895
|
+
|
|
896
|
+
| v4.x call | Replacement in v5.x |
|
|
897
|
+
|-----------|---------------------|
|
|
898
|
+
| `g.lib.global_config_get(name)` | `g.config_get(name, global: true)` |
|
|
899
|
+
| `g.lib.global_config_list` | `g.config_list(global: true)` |
|
|
900
|
+
| `g.lib.global_config_set(name, value)` | `g.config_set(name, value, global: true)` |
|
|
901
|
+
| `g.lib.branch_current` | `g.current_branch` |
|
|
902
|
+
| `g.lib.parse_config(file)` | `g.config_list(file: file)` |
|
|
903
|
+
|
|
904
|
+
##### Methods with no replacement
|
|
905
|
+
|
|
906
|
+
| v4.x call | Notes |
|
|
907
|
+
|-----------|-------|
|
|
908
|
+
| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branch_list`, `g.tag_list`, or `g.remote_list` instead. |
|
|
909
|
+
|
|
910
|
+
##### Internal plumbing methods (no replacement)
|
|
911
|
+
|
|
912
|
+
The following methods were public on `Git::Lib` in name only. They are internal
|
|
913
|
+
helpers with no plausible external use and have no replacement in v5.0.0:
|
|
914
|
+
|
|
915
|
+
- `assert_args_are_not_options`
|
|
916
|
+
- `assert_valid_opts`
|
|
917
|
+
- `cat_file_object_meta`
|
|
918
|
+
- `command_capturing`
|
|
919
|
+
- `command_streaming`
|
|
920
|
+
- `each_cat_file_header`
|
|
921
|
+
- `handle_deprecated_path_option`
|
|
922
|
+
- `normalize_pathspecs`
|
|
923
|
+
- `parse_cat_file_meta`
|
|
924
|
+
- `parse_config_list`
|
|
925
|
+
- `process_commit_data`
|
|
926
|
+
- `validate_pathspec_types`
|
|
927
|
+
|
|
928
|
+
---
|
|
929
|
+
|
|
930
|
+
#### `Git::Log#object` is not a path limiter
|
|
931
|
+
|
|
932
|
+
In previous 4.x releases, some uses of `Git::Log#object(path)` could appear to
|
|
933
|
+
filter log output by path when combined with `#between` or other revision range
|
|
934
|
+
options. This relied on ambiguous `git log` argument handling and was not the
|
|
935
|
+
intended API for path filtering.
|
|
936
|
+
|
|
937
|
+
In v5.x, `Git::Log#object` is a revision expression. When both `#object` and
|
|
938
|
+
`#between` are specified, `#between` takes precedence. Code that used `#object`
|
|
939
|
+
to limit commits to a path should use `#path` instead.
|
|
940
|
+
|
|
941
|
+
```ruby
|
|
942
|
+
# v4.x: ambiguous; could appear to filter commits touching this path
|
|
943
|
+
git.log(500).object('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
|
|
944
|
+
|
|
945
|
+
# v5.x: use #path for path filtering
|
|
946
|
+
git.log(500).path('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
|
|
947
|
+
|
|
948
|
+
# #object remains appropriate for revision expressions
|
|
949
|
+
git.log.object('HEAD~10..HEAD').execute
|
|
950
|
+
```
|
|
951
|
+
|
|
952
|
+
---
|
|
953
|
+
|
|
954
|
+
#### `Git::CommandLineResult` deprecated
|
|
955
|
+
|
|
956
|
+
`Git::CommandLineResult` was an alias for `Git::CommandLine::Result` introduced
|
|
957
|
+
for backward compatibility. It is deprecated in v5.0.0 and removed in v6.0.0.
|
|
958
|
+
Accessing `Git::CommandLineResult` emits a deprecation warning.
|
|
959
|
+
|
|
960
|
+
```ruby
|
|
961
|
+
# v4.x
|
|
962
|
+
result.is_a?(Git::CommandLineResult)
|
|
963
|
+
|
|
964
|
+
# v5.x
|
|
965
|
+
result.is_a?(Git::CommandLine::Result)
|
|
966
|
+
```
|
|
967
|
+
|
|
968
|
+
This change is only relevant if your code references `Git::CommandLineResult`
|
|
969
|
+
by name (typically in type checks or documentation). Code that uses the result
|
|
970
|
+
object returned by git commands is unaffected.
|
|
971
|
+
|
|
972
|
+
---
|
|
973
|
+
|
|
974
|
+
### Deprecated methods
|
|
975
|
+
|
|
976
|
+
The following methods are available in v5.x with deprecation warnings and are
|
|
977
|
+
removed in v6.0.0. Migrate to the replacement shown to silence the warnings. The
|
|
978
|
+
[Removed APIs](#removed-apis) table under "Upgrading to v6.x" indexes these entries.
|
|
979
|
+
|
|
980
|
+
`Git::GitExecuteError` is not listed here because v6.0.0 keeps it. It has warned since
|
|
981
|
+
v2.0.0 and still warns in v6.0.0; see [`Git::GitExecuteError`
|
|
982
|
+
deprecated](#gitgitexecuteerror-deprecated) under "Upgrading to v6.x" for the
|
|
983
|
+
replacement.
|
|
984
|
+
|
|
985
|
+
#### Facade method renames
|
|
986
|
+
|
|
987
|
+
v5.x renamed five methods to follow the project's `noun_verb` naming convention.
|
|
988
|
+
The old names continue to work but emit deprecation warnings:
|
|
989
|
+
|
|
990
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
991
|
+
|-----------------------------------------------------|-------------|
|
|
992
|
+
| `g.add_remote(name, url, opts)` | `g.remote_add(name, url, opts)` |
|
|
993
|
+
| `g.remove_remote(name)` | `g.remote_remove(name)` |
|
|
994
|
+
| `g.set_remote_url(name, url)` | `g.remote_set_url(name, url)` |
|
|
995
|
+
| `g.add_tag(name, ...)` | `g.tag_add(name, ...)` |
|
|
996
|
+
| `g.delete_tag(name)` | `g.tag_delete(name)` |
|
|
997
|
+
|
|
998
|
+
#### `Git::Repository` method renames
|
|
999
|
+
|
|
1000
|
+
v5.x renamed seven more `Git::Repository` methods. The old names continue to work
|
|
1001
|
+
but emit deprecation warnings. Each old name returns exactly what its
|
|
1002
|
+
replacement returns, except `branches_all`.
|
|
1003
|
+
|
|
1004
|
+
> **Return shape change.** `g.branches_all` returns an `Array` of 4-element
|
|
1005
|
+
> tuples `[refname, current, worktree, symref]`, where `refname` is the short
|
|
1006
|
+
> form (`main` or `remotes/origin/main`), `current` and `worktree` are booleans,
|
|
1007
|
+
> and `symref` is the symbolic-ref target or `nil`. `g.branch_list` returns
|
|
1008
|
+
> `Array<Git::BranchInfo>` with `refname` (always the full ref: `refs/heads/main`
|
|
1009
|
+
> or `refs/remotes/origin/main`), `short_name`, `remote_name`, `remote?`,
|
|
1010
|
+
> `current?`, `other_worktree?`, `symref`, `target_oid`, and `upstream`. This
|
|
1011
|
+
> expression reproduces the legacy tuples:
|
|
1012
|
+
>
|
|
1013
|
+
> ```ruby
|
|
1014
|
+
> g.branch_list.map do |i|
|
|
1015
|
+
> refname = i.remote? ? "remotes/#{i.remote_name}/#{i.short_name}" : i.short_name
|
|
1016
|
+
> [refname, i.current?, i.other_worktree?, i.symref]
|
|
1017
|
+
> end
|
|
1018
|
+
> ```
|
|
1019
|
+
|
|
1020
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1021
|
+
|-----------------------------------------------------|-------------|
|
|
1022
|
+
| `g.empty?` | `g.no_commits?`. `true` when the repository has no commits |
|
|
1023
|
+
| `g.reset_hard` | `g.reset(nil, hard: true)`. `reset` takes the commitish positionally, so pass `nil` before the options; returns git's stdout, as `reset_hard` did |
|
|
1024
|
+
| `g.reset_hard(commitish)` | `g.reset(commitish, hard: true)`. `reset_hard` ignored any `:hard` option passed to it and always reset with `--hard` |
|
|
1025
|
+
| `g.conflicts { \|file, yours, theirs\| ... }` | `g.each_conflict { \|file, yours, theirs\| ... }`. Same block arguments; returns the unmerged paths |
|
|
1026
|
+
| `g.is_local_branch?(name)` | `g.local_branch?(name)` |
|
|
1027
|
+
| `g.is_remote_branch?(name)` | `g.remote_branch?(name)` |
|
|
1028
|
+
| `g.is_branch?(name)` | `g.branch?(name)` |
|
|
1029
|
+
| `g.branches_all` | `g.branch_list`. Returns `Array<Git::BranchInfo>`; see the return shape change above |
|
|
1030
|
+
|
|
1031
|
+
#### `Git::Repository` alias renames
|
|
1032
|
+
|
|
1033
|
+
Eight `Git::Repository` methods have a second, older name carried over from v4.x.
|
|
1034
|
+
Releases before v5.7.0 kept the older names as aliases with no warning. From
|
|
1035
|
+
v5.7.0 on, each old name emits a deprecation warning. Each old name takes the
|
|
1036
|
+
same arguments and returns exactly what its replacement returns.
|
|
1037
|
+
|
|
1038
|
+
> **`diff_name_status`:** a `:path` option emits its own deprecation warning
|
|
1039
|
+
> after the method-name warning. Pass `:path_limiter` instead, as described
|
|
1040
|
+
> under [`Git::Repository` option renames](#gitrepository-option-renames) below.
|
|
1041
|
+
|
|
1042
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1043
|
+
|-----------------------------------------------------|-------------|
|
|
1044
|
+
| `g.object_contents(object)` | `g.cat_file_contents(object)` |
|
|
1045
|
+
| `g.object_size(object)` | `g.cat_file_size(object)` |
|
|
1046
|
+
| `g.object_type(object)` | `g.cat_file_type(object)` |
|
|
1047
|
+
| `g.commit_data(object)` | `g.cat_file_commit(object)` |
|
|
1048
|
+
| `g.tag_data(object)` | `g.cat_file_tag(object)` |
|
|
1049
|
+
| `g.revparse(objectish)` | `g.rev_parse(objectish)` |
|
|
1050
|
+
| `g.namerev(commit_ish)` | `g.name_rev(commit_ish)` |
|
|
1051
|
+
| `g.diff_name_status(from, to, opts)` | `g.diff_path_status(from, to, opts)` |
|
|
1052
|
+
|
|
1053
|
+
#### `Git::Repository` option renames
|
|
1054
|
+
|
|
1055
|
+
Five methods accept a v4.x option or positional argument under its old name.
|
|
1056
|
+
The old form still works in v5.x but emits a deprecation warning and is
|
|
1057
|
+
translated to the v5.x form shown below.
|
|
1058
|
+
|
|
1059
|
+
> **`clean`.** `force: 2` runs `git clean -ff`, which also removes untracked
|
|
1060
|
+
> nested git repositories. A `false` or `nil` value for `:ff` or `:force_force`
|
|
1061
|
+
> still warns and has no effect; a value other than `true`, `false`, or `nil`
|
|
1062
|
+
> raises `ArgumentError`. When the deprecated key is `true` and a valid
|
|
1063
|
+
> `:force` is also given, `:force` is raised to `2` (a `:force` already at `2`
|
|
1064
|
+
> is unchanged). An invalid `:force` value such as `0` is passed through
|
|
1065
|
+
> unchanged and still raises `ArgumentError`; the deprecated key does not mask
|
|
1066
|
+
> it.
|
|
1067
|
+
|
|
1068
|
+
> **`diff_path_status`.** `:path_limiter` accepts the same values as `:path`
|
|
1069
|
+
> (a `String`, a `Pathname`, or an `Array` of them). When both keys are given,
|
|
1070
|
+
> `:path_limiter` wins and no warning is emitted.
|
|
1071
|
+
|
|
1072
|
+
> **`set_working` and `set_index`.** `must_exist:` defaults to `true`. When
|
|
1073
|
+
> both the positional argument and `must_exist:` are given, they are OR'ed so
|
|
1074
|
+
> the more restrictive value wins.
|
|
1075
|
+
|
|
1076
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1077
|
+
|-----------------------------------------------------|-------------|
|
|
1078
|
+
| `g.clean(ff: true)` | `g.clean(force: 2)` |
|
|
1079
|
+
| `g.clean(force_force: true)` | `g.clean(force: 2)` |
|
|
1080
|
+
| `g.diff_path_status(ref1, ref2, path: p)` | `g.diff_path_status(ref1, ref2, path_limiter: p)` |
|
|
1081
|
+
| `g.commit(message, add_all: true)` | `g.commit(message, all: true)`. Runs `git commit -a` |
|
|
1082
|
+
| `g.set_working(dir, check)` | `g.set_working(dir, must_exist: check)` |
|
|
1083
|
+
| `g.set_index(file, check)` | `g.set_index(file, must_exist: check)` |
|
|
1084
|
+
|
|
1085
|
+
#### v4.x-style configuration methods
|
|
1086
|
+
|
|
1087
|
+
The v4.x `config` and `global_config` methods accepted varying argument shapes
|
|
1088
|
+
to read, write, or list configuration. v5.x replaces them with separate,
|
|
1089
|
+
purpose-named methods. The same applies to the module-level
|
|
1090
|
+
`Git.global_config`, whose replacements are `Git.config_get`, `Git.config_set`,
|
|
1091
|
+
and `Git.config_list` called with `global: true`.
|
|
1092
|
+
|
|
1093
|
+
> **Return type change.** The v4.x `g.config(name)` and `Git.global_config(name)`
|
|
1094
|
+
> returned a `String`; `g.config` and `Git.global_config` returned a `Hash`. The
|
|
1095
|
+
> v5.x replacements `config_get` and `config_list` return `Git::ConfigEntryInfo`
|
|
1096
|
+
> (or `nil` when the key is not set) and `Array<Git::ConfigEntryInfo>`
|
|
1097
|
+
> respectively. Use `.value` to get the String value:
|
|
1098
|
+
> - `g.config_get(name)&.value` returns a String or nil
|
|
1099
|
+
> - `g.config_list.to_h { |e| [e.key, e.value] }` returns a Hash of key to value
|
|
1100
|
+
>
|
|
1101
|
+
> The setters `g.config(name, value)` and `Git.global_config(name, value)`
|
|
1102
|
+
> returned the raw command result; `config_set` returns `nil`.
|
|
1103
|
+
|
|
1104
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1105
|
+
|-----------------------------------------------------|-------------|
|
|
1106
|
+
| `g.config(name)` | `g.config_get(name)`. Returns `Git::ConfigEntryInfo`; use `.value` for the String |
|
|
1107
|
+
| `g.config` | `g.config_list`. Returns `Array<Git::ConfigEntryInfo>` |
|
|
1108
|
+
| `g.config(name, value)` | `g.config_set(name, value)` |
|
|
1109
|
+
| `g.global_config(name)` | `g.config_get(name, global: true)` |
|
|
1110
|
+
| `g.global_config` | `g.config_list(global: true)` |
|
|
1111
|
+
| `g.global_config(name, value)` | `g.config_set(name, value, global: true)` |
|
|
1112
|
+
| `Git.global_config(name)` | `Git.config_get(name, global: true)`. Returns `Git::ConfigEntryInfo` or `nil`; use `.value` for the String |
|
|
1113
|
+
| `Git.global_config` | `Git.config_list(global: true)`. Returns `Array<Git::ConfigEntryInfo>` |
|
|
1114
|
+
| `Git.global_config(name, value)` | `Git.config_set(name, value, global: true)` |
|
|
1115
|
+
|
|
1116
|
+
#### `Git` module mixin deprecations
|
|
1117
|
+
|
|
1118
|
+
Extending or including the `Git` module to call `config` and `global_config`
|
|
1119
|
+
as bare methods is deprecated:
|
|
1120
|
+
|
|
1121
|
+
| Deprecated usage | Replacement |
|
|
1122
|
+
|-----------------|-------------|
|
|
1123
|
+
| `include Git; config(name)` | `Git.config_get(name)` |
|
|
1124
|
+
| `include Git; config(name, value)` | `Git.config_set(name, value)` |
|
|
1125
|
+
| `include Git; config` | `Git.config_list` |
|
|
1126
|
+
| `include Git; global_config(name)` | `Git.config_get(name, global: true)` |
|
|
1127
|
+
| `include Git; global_config(name, value)` | `Git.config_set(name, value, global: true)` |
|
|
1128
|
+
| `include Git; global_config` | `Git.config_list(global: true)` |
|
|
1129
|
+
|
|
1130
|
+
`Git.config_get`, `Git.config_set`, and `Git.config_list` run `git config` in
|
|
1131
|
+
the current directory, which is what the mixin `config` method did. The
|
|
1132
|
+
return types differ as described under
|
|
1133
|
+
[v4.x-style configuration methods](#v4x-style-configuration-methods).
|
|
1134
|
+
|
|
1135
|
+
#### Module-level `Git` function deprecations
|
|
1136
|
+
|
|
1137
|
+
Two module-level functions on `Git` accept a legacy call shape or return a
|
|
1138
|
+
legacy type that is deprecated:
|
|
1139
|
+
|
|
1140
|
+
- `Git.ls_remote` defaults its repository argument to `'.'`. Passing `nil`
|
|
1141
|
+
explicitly still works but warns; omit the argument or pass `'.'`. The
|
|
1142
|
+
options hash is positional, so when you pass options you must also pass the
|
|
1143
|
+
repository: `Git.ls_remote('.', opts)`, not `Git.ls_remote(opts)`.
|
|
1144
|
+
- `Git.binary_version` is replaced by `Git.git_version`, which keeps the
|
|
1145
|
+
optional binary path argument.
|
|
1146
|
+
|
|
1147
|
+
> **Return type change.** `Git.binary_version` returned an `Array<Integer>` of
|
|
1148
|
+
> `[major, minor, patch]`. `Git.git_version` returns a `Git::Version`, which
|
|
1149
|
+
> supports comparison and exposes `major`, `minor`, and `patch`.
|
|
1150
|
+
> `Git.git_version.to_a` reproduces the legacy array. The return value of
|
|
1151
|
+
> `Git.ls_remote` is unchanged.
|
|
1152
|
+
|
|
1153
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1154
|
+
|-----------------------------------------------------|-------------|
|
|
1155
|
+
| `Git.ls_remote(nil)` | `Git.ls_remote` or `Git.ls_remote('.')` |
|
|
1156
|
+
| `Git.ls_remote(nil, opts)` | `Git.ls_remote('.', opts)` |
|
|
1157
|
+
| `Git.binary_version` | `Git.git_version`. Returns `Git::Version`; use `.to_a` for the `[major, minor, patch]` Array |
|
|
1158
|
+
| `Git.binary_version(binary_path)` | `Git.git_version(binary_path)` |
|
|
1159
|
+
|
|
1160
|
+
#### `Git::Author` deprecated
|
|
1161
|
+
|
|
1162
|
+
Starting in v5.3.0, the methods that return author, committer, or tagger data
|
|
1163
|
+
return an immutable `Git::AuthorInfo` value object instead of the mutable
|
|
1164
|
+
`Git::Author`. Those methods are `Git::Object::Commit#author`,
|
|
1165
|
+
`Git::Object::Commit#committer`, `Git::Object::Tag#tagger`, and
|
|
1166
|
+
`Git::TagInfo#tagger`.
|
|
1167
|
+
|
|
1168
|
+
`Git::AuthorInfo` exposes the same `name`, `email`, and `date` readers, so code
|
|
1169
|
+
that only reads these attributes needs no changes. Code that mutated a
|
|
1170
|
+
`Git::Author` through `name=`, `email=`, or `date=` has to change.
|
|
1171
|
+
`Git::AuthorInfo` is frozen, and `#with` returns a modified copy rather than
|
|
1172
|
+
updating in place (e.g. `info = info.with(name: 'New Name')`).
|
|
1173
|
+
|
|
1174
|
+
Constructing `Git::Author` directly emits a deprecation warning naming
|
|
1175
|
+
`Git::AuthorInfo` as the replacement. The class is removed in v6.0.0.
|
|
1176
|
+
|
|
1177
|
+
| Deprecated usage | Replacement |
|
|
1178
|
+
|-----------------|-------------|
|
|
1179
|
+
| `Git::Author.new('Name <email> 1627849923 +0200')` | `Git::AuthorInfo.parse('Name <email> 1627849923 +0200')` |
|
|
1180
|
+
| `author.name = 'New Name'` | `author = author.with(name: 'New Name')` (returns a new object) |
|
|
1181
|
+
|
|
1182
|
+
#### `Git::Branch#stashes` deprecated
|
|
1183
|
+
|
|
1184
|
+
`Git::Branch#stashes` ignores the branch it is called on and returns every stash
|
|
1185
|
+
in the repository, so `g.branch('feature').stashes` and `g.branch('main').stashes`
|
|
1186
|
+
return the same entries. Call `Git::Repository#stash_infos` instead; it is the
|
|
1187
|
+
query `Git::Branch#stashes` was already running.
|
|
1188
|
+
|
|
1189
|
+
> **Return type change.** `Git::Branch#stashes` returns a `Git::Stashes`
|
|
1190
|
+
> collection of `Git::Stash` objects. `g.stash_infos` returns an array of
|
|
1191
|
+
> `Git::StashInfo` values. Both are newest first, so indexes carry over unchanged.
|
|
1192
|
+
> `Git::Stash#message` strips the `WIP on <branch>:` or `On <branch>:` prefix;
|
|
1193
|
+
> `Git::StashInfo#message` keeps the full message and exposes the branch name as
|
|
1194
|
+
> `Git::StashInfo#branch`.
|
|
1195
|
+
|
|
1196
|
+
`Git::Stashes` also exposes `save`, `apply`, and `clear`. Those map to the
|
|
1197
|
+
repository's `stash_push`, `stash_apply`, and `stash_clear`. `Git::Stashes#apply(i)`
|
|
1198
|
+
already passed `i` to git as `stash@{i}` (`0` = newest), and `g.stash_apply(i)` does
|
|
1199
|
+
the same, so that index needs no conversion. The `Git::Stashes` class is deprecated
|
|
1200
|
+
as well; [Legacy stash API deprecated](#legacy-stash-api-deprecated) maps each of
|
|
1201
|
+
its methods.
|
|
1202
|
+
|
|
1203
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1204
|
+
|-----------------------------------------------------|-------------|
|
|
1205
|
+
| `g.branch(name).stashes` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
|
|
1206
|
+
| `g.branch(name).stashes.each { \|s\| puts s.message }` | `g.stash_infos.each { \|info\| puts info.message }` |
|
|
1207
|
+
| `g.branch(name).stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse`. See the ordering note in [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
|
|
1208
|
+
| `g.branch(name).stashes.size` | `g.stash_infos.size` |
|
|
1209
|
+
| `g.branch(name).stashes[i].message` (`0` = newest, `i` coerced with `to_i`) | `g.stash_infos[i.to_i].message` |
|
|
1210
|
+
| `g.branch(name).stashes.save(message)` | `g.stash_push(message: message)` |
|
|
1211
|
+
| `g.branch(name).stashes.apply` | `g.stash_apply` |
|
|
1212
|
+
| `g.branch(name).stashes.apply(i)` (`0` = newest) | `g.stash_apply(i)` |
|
|
1213
|
+
| `g.branch(name).stashes.clear` | `g.stash_clear`. Returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
|
|
1214
|
+
|
|
1215
|
+
#### Legacy stash API deprecated
|
|
1216
|
+
|
|
1217
|
+
Starting in v5.4.0, the stash methods on `Git::Repository` are built around the
|
|
1218
|
+
immutable `Git::StashInfo` value object. `g.stash_infos` returns every entry as a
|
|
1219
|
+
`Git::StashInfo`, and `stash_push`, `stash_pop`, `stash_drop`, `stash_show`,
|
|
1220
|
+
`stash_branch`, `stash_create`, and `stash_store` each map onto the `git stash`
|
|
1221
|
+
subcommand of the same name. Every method that takes a stash (`stash_apply`,
|
|
1222
|
+
`stash_pop`, `stash_drop`, `stash_show`, `stash_branch`) accepts a `Git::StashInfo`,
|
|
1223
|
+
a `stash@{N}` name, an Integer index (`0` = newest), or `nil` for the newest entry.
|
|
1224
|
+
|
|
1225
|
+
The legacy methods and classes are deprecated and removed in v6.0.0:
|
|
1226
|
+
`Git::Repository#stashes_all`, `Git::Repository#stash_save`,
|
|
1227
|
+
`Git::Repository#stash_list`, `Git::Stash`, and `Git::Stashes`. Constructing a
|
|
1228
|
+
`Git::Stash` or `Git::Stashes` emits one warning per object.
|
|
1229
|
+
|
|
1230
|
+
> **Ordering flip.** `g.stashes_all` returns entries oldest first with a
|
|
1231
|
+
> sequential index of its own (`0` is the oldest). `g.stash_infos` returns entries
|
|
1232
|
+
> newest first, the order `git stash list` uses, and `Git::StashInfo#index` is
|
|
1233
|
+
> git's own `stash@{N}` number (`0` is the newest). `g.stashes_all.first` is
|
|
1234
|
+
> `g.stash_infos.last`. Code that reads an entry by position must reverse the
|
|
1235
|
+
> array or the index.
|
|
1236
|
+
|
|
1237
|
+
> **Message difference.** `g.stashes_all` strips the `WIP on <branch>:` or
|
|
1238
|
+
> `On <branch>:` prefix from each message. `Git::StashInfo#message` keeps the full
|
|
1239
|
+
> message git stores, and `Git::StashInfo#branch` holds the branch name. A stash
|
|
1240
|
+
> created from a detached HEAD has the branch `"(no branch)"`, the label git writes
|
|
1241
|
+
> in its message. `branch` is `nil` only when the message has no branch prefix at
|
|
1242
|
+
> all, as for a `stash_store` entry with a custom message.
|
|
1243
|
+
|
|
1244
|
+
`g.stash_save(message)` returned `true` when it created a stash and `false` when
|
|
1245
|
+
there were no local changes to save. `g.stash_push(message: message)` returns the
|
|
1246
|
+
new `Git::StashInfo`, or `nil` when there were no local changes, so a truthiness
|
|
1247
|
+
check such as `if g.stash_push(message: 'WIP')` still works.
|
|
1248
|
+
|
|
1249
|
+
`g.stash_list` returned the `git stash list` text as a String. Build that text from
|
|
1250
|
+
`g.stash_infos` if you need it. In v6.0.0 `stash_list` returns what `stash_infos`
|
|
1251
|
+
returns (see [`stash_list` returns an Array of
|
|
1252
|
+
`Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)), so move String
|
|
1253
|
+
callers of `stash_list` to `stash_infos` before upgrading so the return type change
|
|
1254
|
+
cannot go unnoticed.
|
|
1255
|
+
|
|
1256
|
+
> **`stash_store` in v6.0.0.** On v5.x, `g.stash_store` returns the top entry of
|
|
1257
|
+
> the stash list after the store, which is `nil` when the list is empty. v6.0.0
|
|
1258
|
+
> changes that; see [`stash_store` raises when the stored entry is
|
|
1259
|
+
> missing](#stash_store-raises-when-the-stored-entry-is-missing).
|
|
1260
|
+
|
|
1261
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1262
|
+
|-----------------------------------------------------|-------------|
|
|
1263
|
+
| `g.stashes_all` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
|
|
1264
|
+
| `g.stashes_all.each { \|index, message\| ... }` | `g.stash_infos.reverse_each.with_index { \|info, index\| ... info.message }` |
|
|
1265
|
+
| `g.stashes_all[i]` (`0` = oldest) | `g.stash_infos.reverse[i]` |
|
|
1266
|
+
| `g.stashes_all.last` | `g.stash_infos.first` |
|
|
1267
|
+
| `g.stash_save(message)` | `g.stash_push(message: message)`. Returns `Git::StashInfo` or `nil` |
|
|
1268
|
+
| `g.stash_list` (String) | `g.stash_infos.map { \|s\| "#{s.name}: #{s.message}" }.join("\n")` |
|
|
1269
|
+
| `Git::Stash.new(g, message)` | `info = g.stash_push(message: message)` |
|
|
1270
|
+
| `Git::Stash.new(g, message, existing: true)` | `message`. `existing: true` only wrapped the String and never looked an entry up; code that needs a real entry picks one from `g.stash_infos` by index or name |
|
|
1271
|
+
| `stash.save` | `info = g.stash_push(message: message)` |
|
|
1272
|
+
| `stash.saved?` | `!info.nil?`. Check the value `stash_push` returned rather than pushing again |
|
|
1273
|
+
| `stash.message` / `stash.to_s` | `info.message`. Keeps the branch prefix; see the note above |
|
|
1274
|
+
| `Git::Stashes.new(g)` | `g.stash_infos` |
|
|
1275
|
+
| `stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse`. See the ordering note above |
|
|
1276
|
+
| `stashes.each { \|s\| ... }` (newest first) | `g.stash_infos.each { \|info\| ... }` |
|
|
1277
|
+
| `stashes[i]` (`0` = newest, `i` coerced with `to_i`) | `g.stash_infos[i.to_i]` |
|
|
1278
|
+
| `stashes.size` | `g.stash_infos.size` |
|
|
1279
|
+
| `stashes.save(message)` | `g.stash_push(message: message)` |
|
|
1280
|
+
| `stashes.apply` / `stashes.apply(i)` | `g.stash_apply` / `g.stash_apply(i)` |
|
|
1281
|
+
| `stashes.clear` | `g.stash_clear`. Returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
|
|
1282
|
+
|
|
1283
|
+
#### `Git::Repository#remotes` deprecated
|
|
1284
|
+
|
|
1285
|
+
`Git::Repository#remotes` is deprecated in favor of `Git::Repository#remote_list`
|
|
1286
|
+
and is removed in v6.0.0. Its return value is unchanged. Calling `remotes` emits
|
|
1287
|
+
one deprecation warning for itself plus one `Git::Remote` constructor warning for
|
|
1288
|
+
each remote it returns (see the `Git::Remote` deprecation below), so a repository
|
|
1289
|
+
with N remotes produces N + 1 warnings per call.
|
|
1290
|
+
|
|
1291
|
+
> **Return type change.** `remotes` returns `Array<Git::Remote>`, mutable
|
|
1292
|
+
> objects with `name`, `url`, and `fetch_opts` accessors and `fetch`, `merge`,
|
|
1293
|
+
> `branch`, and `remove` operations. `remote_list` returns
|
|
1294
|
+
> `Array<Git::RemoteInfo>`, immutable value objects read from the repository's
|
|
1295
|
+
> git config, with fields such as `name`, `url`, `push_url`, `fetch`, and `push`.
|
|
1296
|
+
> Because a remote may carry more than one URL or refspec, `url`, `push_url`,
|
|
1297
|
+
> `fetch`, and `push` are always frozen `Array<String>`. When a remote has more
|
|
1298
|
+
> than one URL, git fetches from the first; the legacy `Git::Remote#url` returned
|
|
1299
|
+
> the last one configured, so use `r.url.last` to reproduce that exact value.
|
|
1300
|
+
> Likewise, `Git::Remote#fetch_opts` returned only the last configured fetch
|
|
1301
|
+
> refspec, while `fetch` holds all of them. Operations that lived on
|
|
1302
|
+
> `Git::Remote` are called on the repository instead; the table below shows
|
|
1303
|
+
> the argument each one takes.
|
|
1304
|
+
>
|
|
1305
|
+
> **Order change.** `remotes` lists remotes in the order `git remote` prints
|
|
1306
|
+
> them, while `remote_list` keeps the order in which remotes first appear in the
|
|
1307
|
+
> config. When the legacy order matters, iterate `g.remote_names` (the same
|
|
1308
|
+
> `git remote` order) or sort `g.remote_list` explicitly.
|
|
1309
|
+
|
|
1310
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1311
|
+
|-----------------------------------------------------|-------------|
|
|
1312
|
+
| `g.remotes` | `g.remote_list`. Returns `Array<Git::RemoteInfo>` |
|
|
1313
|
+
| `g.remotes.map(&:name)` | `g.remote_list.map(&:name)` or `g.remote_names` |
|
|
1314
|
+
| `g.remotes.map(&:to_s)` | `g.remote_list.map(&:name)`. `Git::RemoteInfo#to_s` is not the name |
|
|
1315
|
+
| `g.remotes.map(&:url)` | `g.remote_list.map { \|r\| r.url.first }`. `url` is an `Array<String>` |
|
|
1316
|
+
| `g.remotes.map(&:fetch_opts)` | `g.remote_list.map { \|r\| r.fetch.last }`. `fetch` holds every refspec |
|
|
1317
|
+
| `g.remotes.each(&:fetch)` | `g.remote_names.each { \|name\| g.fetch(name) }`. Same order as `remotes` |
|
|
1318
|
+
| `remote.fetch` | `g.fetch(remote.name)` |
|
|
1319
|
+
| `remote.fetch(opts)` | `g.fetch(remote.name, opts)`. Same options hash |
|
|
1320
|
+
| `remote.merge` | `g.merge("#{remote.name}/#{g.current_branch}")` |
|
|
1321
|
+
| `remote.merge(branch)` | `g.merge("#{remote.name}/#{branch}")` |
|
|
1322
|
+
| `remote.branch` | `g.branch_list("#{remote.name}/#{g.current_branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
|
|
1323
|
+
| `remote.branch(name)` | `g.branch_list("#{remote.name}/#{name}").find(&:remote?)`. Returns a `Git::BranchInfo` |
|
|
1324
|
+
| `remote.remove` | `g.remote_remove(remote.name)` |
|
|
1325
|
+
|
|
1326
|
+
#### `Git::Remote` deprecated
|
|
1327
|
+
|
|
1328
|
+
`Git::Remote`, `Git::Repository#remote`, and `Git::Repository#config_remote` are
|
|
1329
|
+
deprecated and are removed in v6.0.0. Read a remote's configuration through
|
|
1330
|
+
`Git::Repository#remote_list`, which returns one `Git::RemoteInfo` value object per
|
|
1331
|
+
remote; the table below shows the replacement for each operation. Return values
|
|
1332
|
+
are unchanged. Constructing a `Git::Remote` directly emits one deprecation warning,
|
|
1333
|
+
and so does calling `g.config_remote`. Calling `g.remote` emits two: one for
|
|
1334
|
+
`Git::Repository#remote` and one for the `Git::Remote` it constructs. Likewise
|
|
1335
|
+
`g.remotes` emits one warning for itself plus one per `Git::Remote` it returns
|
|
1336
|
+
(N + 1 for N remotes). The extra warnings from `g.remote` and `g.remotes` are
|
|
1337
|
+
expected, not a bug.
|
|
1338
|
+
|
|
1339
|
+
> **Return type changes.** `Git::RemoteInfo#url` and `Git::RemoteInfo#fetch` are
|
|
1340
|
+
> frozen `Array<String>` because a remote may carry more than one URL or fetch
|
|
1341
|
+
> refspec. The legacy `Git::Remote#url` and `Git::Remote#fetch_opts` returned only
|
|
1342
|
+
> the last configured value, so `r.url.last` and `r.fetch.last` reproduce them
|
|
1343
|
+
> exactly; `r.url.first` is the URL git actually fetches from.
|
|
1344
|
+
> `config_remote` returned a flat `Hash{String => String}` in which a repeated
|
|
1345
|
+
> `url` or `fetch` key overwrote the earlier value, so it could not report every
|
|
1346
|
+
> configured URL or refspec; `remote_list` keeps all of them. In the other
|
|
1347
|
+
> direction, `Git::RemoteInfo` models only the remote variables git defines and
|
|
1348
|
+
> drops any other `remote.<name>.*` key, while `config_remote` returned every key.
|
|
1349
|
+
> Code that reads custom keys should filter `g.config_list` instead (see the
|
|
1350
|
+
> table); that yields the same `Hash{String => String}` as `config_remote`.
|
|
1351
|
+
> `Git::Remote#branch` returned a `Git::Branch`. Its replacement,
|
|
1352
|
+
> `g.branch_list("#{name}/#{branch}").find(&:remote?)`, returns a
|
|
1353
|
+
> `Git::BranchInfo` value object, or `nil` when the remote-tracking branch does
|
|
1354
|
+
> not exist.
|
|
1355
|
+
|
|
1356
|
+
In the table, `name` is the remote name (`g.remote` defaults it to `'origin'`).
|
|
1357
|
+
|
|
1358
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1359
|
+
|-----------------------------------------------------|-------------|
|
|
1360
|
+
| `g.remote` | `g.remote_list.find { \|r\| r.name == 'origin' }`. Returns a `Git::RemoteInfo`; the deprecated call emits two warnings |
|
|
1361
|
+
| `g.remote(name)` | `g.remote_list.find { \|r\| r.name == name }`. Returns a `Git::RemoteInfo`; the deprecated call emits two warnings |
|
|
1362
|
+
| `g.config_remote(name)` for `url`, `fetch`, and the other modeled fields | `g.remote_list.find { \|r\| r.name == name }`. A `Git::RemoteInfo`, not a `Hash` |
|
|
1363
|
+
| `g.config_remote(name)` for every key, including custom ones | `g.config_list.select { \|e\| e.key.start_with?("remote.#{name}.") }.to_h { \|e\| [e.key.delete_prefix("remote.#{name}."), e.value] }`. The same `Hash{String => String}` |
|
|
1364
|
+
| `remote.name`, `remote.to_s` | `g.remote_list.find { \|r\| r.name == name }.name` or `g.remote_names` |
|
|
1365
|
+
| `remote.url` | `g.remote_list.find { \|r\| r.name == name }.url`. `Array<String>`; `.first` for the single-URL case |
|
|
1366
|
+
| `remote.fetch_opts` | `g.remote_list.find { \|r\| r.name == name }.fetch`. `Array<String>` of refspecs |
|
|
1367
|
+
| `remote.fetch` | `g.fetch(name)` |
|
|
1368
|
+
| `remote.fetch(opts)` | `g.fetch(name, opts)`. Same option keys |
|
|
1369
|
+
| `remote.merge` | `g.merge("#{name}/#{g.current_branch}")` |
|
|
1370
|
+
| `remote.merge(branch)` | `g.merge("#{name}/#{branch}")` |
|
|
1371
|
+
| `remote.branch` | `g.branch_list("#{name}/#{g.current_branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
|
|
1372
|
+
| `remote.branch(branch)` | `g.branch_list("#{name}/#{branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
|
|
1373
|
+
| `remote.remove` | `g.remote_remove(name)` |
|
|
1374
|
+
|
|
1375
|
+
#### `Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated
|
|
1376
|
+
|
|
1377
|
+
The `allow_unknown_type:` option of `Git::Commands::CatFile::Raw` is deprecated
|
|
1378
|
+
and is removed in v6.0.0. Passing it emits a deprecation warning; the
|
|
1379
|
+
`--allow-unknown-type` flag still reaches git unchanged until the option is
|
|
1380
|
+
removed.
|
|
1381
|
+
|
|
1382
|
+
There is no replacement. Git 2.50 removed the unknown-type feature, so on git
|
|
1383
|
+
2.50 and later `--allow-unknown-type` is an accepted no-op and the option has no
|
|
1384
|
+
effect. On git 2.28 through 2.49 the flag still lets `t: true` and `s: true`
|
|
1385
|
+
report the type and size of an object whose type git does not recognize, but
|
|
1386
|
+
that behavior is dropped together with the option. The class is internal
|
|
1387
|
+
(`@api private`) and no `Git::Repository` method passes the option, so only code
|
|
1388
|
+
that constructs the command class directly is affected.
|
|
1389
|
+
|
|
1390
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1391
|
+
|-----------------------------------------------------|-------------|
|
|
1392
|
+
| `Git::Commands::CatFile::Raw.new(ctx).call(sha, t: true, allow_unknown_type: true)` | `Git::Commands::CatFile::Raw.new(ctx).call(sha, t: true)` |
|
|
1393
|
+
| `Git::Commands::CatFile::Raw.new(ctx).call(sha, s: true, allow_unknown_type: true)` | `Git::Commands::CatFile::Raw.new(ctx).call(sha, s: true)` |
|
|
1394
|
+
|
|
1395
|
+
#### `Git::Branch` and `Git::Branches` deprecated
|
|
1396
|
+
|
|
1397
|
+
`Git::Branch`, `Git::Branches`, `Git::Repository#branch`, and
|
|
1398
|
+
`Git::Repository#branches` are deprecated and are removed in v6.0.0. Read branch
|
|
1399
|
+
data through `Git::Repository#branch_list`, which returns one `Git::BranchInfo`
|
|
1400
|
+
value object per local and remote-tracking branch, and call the repository-level
|
|
1401
|
+
operations (`checkout`, `branch_new`, `branch_delete`, `merge`, `merge_into`,
|
|
1402
|
+
`in_branch`, and so on) with the branch name. For a remote-tracking branch the
|
|
1403
|
+
argument differs by operation; the table below shows the form each one takes.
|
|
1404
|
+
Calling `g.branch` or `g.branches`, constructing a `Git::Branches`, and calling
|
|
1405
|
+
any operation on a `Git::Branch` each emit a deprecation warning; their return
|
|
1406
|
+
values are unchanged. The `full`, `name`, `remote`, `to_s`, and `to_a` readers
|
|
1407
|
+
on `Git::Branch` do not warn.
|
|
1408
|
+
|
|
1409
|
+
> **Return shape change.** `Git::Branch` exposes `full` (`main` or
|
|
1410
|
+
> `remotes/origin/main`), `name`, and `remote` (a `Git::Remote`, or `nil`).
|
|
1411
|
+
> `Git::BranchInfo` exposes `refname` (always the full ref: `refs/heads/main` or
|
|
1412
|
+
> `refs/remotes/origin/main`), `short_name` (`main` for both), `remote_name` (a
|
|
1413
|
+
> `String`, or `nil`), `remote?`, `current?`, `target_oid`, `upstream`,
|
|
1414
|
+
> `worktree_path`, and `symref`. `Git::BranchInfo#to_s` is the full ref, not the
|
|
1415
|
+
> `remotes/origin/main` form `Git::Branch#to_s` returned. `branch_list` takes
|
|
1416
|
+
> `git branch --list` patterns: `'main'` matches the local branch and
|
|
1417
|
+
> `'origin/main'` matches the remote-tracking branch. The `remotes/origin/main`
|
|
1418
|
+
> and `refs/...` forms that `g.branches[...]` accepted match nothing.
|
|
1419
|
+
>
|
|
1420
|
+
> **`checkout` no longer creates the branch.** `g.branch('x').checkout` created
|
|
1421
|
+
> `x` when it did not exist, ignoring any error from that attempt, and then
|
|
1422
|
+
> checked it out. `g.checkout('x')` does not create a missing local branch,
|
|
1423
|
+
> with one exception that is git's own: when exactly one remote has a branch
|
|
1424
|
+
> named `x`, git creates a local tracking branch from it (its default guess
|
|
1425
|
+
> behavior). Otherwise the checkout fails. To reproduce create-or-checkout,
|
|
1426
|
+
> call `g.branch_new('x') unless g.local_branch?('x')` and then
|
|
1427
|
+
> `g.checkout('x')`. Use `g.checkout('x', new_branch: true)` only when `x` is
|
|
1428
|
+
> known not to exist; like `g.branch_new('x')`, it fails when `x` already
|
|
1429
|
+
> exists. Likewise `g.branch('x').create` ignored every error, while
|
|
1430
|
+
> `g.branch_new('x')` raises `Git::FailedError` when `x` already exists.
|
|
1431
|
+
>
|
|
1432
|
+
> **`in_branch` and `merge_into` differences:**
|
|
1433
|
+
>
|
|
1434
|
+
> 1. **Branch creation.** `g.branch('x').in_branch { ... }` created `x` if it did
|
|
1435
|
+
> not exist. `g.in_branch('x') { ... }` raises `ArgumentError` unless `x` is an
|
|
1436
|
+
> existing local branch, so call `g.branch_new('x')` first. A commit SHA, tag,
|
|
1437
|
+
> or remote-tracking name is also rejected before any checkout.
|
|
1438
|
+
> 2. **Detached HEAD.** `Git::Branch#in_branch` recorded the literal `HEAD` and
|
|
1439
|
+
> could not restore a detached HEAD to its original commit. `g.in_branch` and
|
|
1440
|
+
> `g.merge_into` record the SHA and restore it.
|
|
1441
|
+
> 3. **Unborn HEAD.** Both new methods raise `Git::Error` before checking anything
|
|
1442
|
+
> out when HEAD is on a branch with no commits. The old methods failed later,
|
|
1443
|
+
> mid-flow.
|
|
1444
|
+
> 4. **Merge overload.** `g.branch('main').merge('feature')` returned stdout from
|
|
1445
|
+
> the final restore checkout and ran a hard reset after the merge.
|
|
1446
|
+
> `g.merge_into('main', 'feature')` returns the merge's stdout and does no
|
|
1447
|
+
> reset. It also rejects the `:no_commit` option; callers who need
|
|
1448
|
+
> `--no-commit` use `checkout` and `merge` directly.
|
|
1449
|
+
> 5. **Remote-tracking receivers.** Called on a remote-tracking `Git::Branch`,
|
|
1450
|
+
> `in_branch` and `merge(branch)` checked out the remote-tracking ref,
|
|
1451
|
+
> detaching HEAD, and any commit made there was left dangling. `g.in_branch`
|
|
1452
|
+
> and `g.merge_into` take an existing local branch only. Create one from the
|
|
1453
|
+
> remote-tracking ref first, with
|
|
1454
|
+
> `g.branch_new(name, "remotes/#{remote}/#{name}")`, and pass that branch.
|
|
1455
|
+
|
|
1456
|
+
In the table, `name` is the branch name (`g.branch` defaults it to the current
|
|
1457
|
+
branch), `remote` is the remote name of a remote-tracking branch, `b` is a
|
|
1458
|
+
`Git::Branch`, and `info` is the `Git::BranchInfo` that replaces it. Where a
|
|
1459
|
+
row says to pass `info.refname` for a remote-tracking branch, `b.full` (the
|
|
1460
|
+
`remotes/<remote>/<name>` form) works too; the shorter `"#{remote}/#{name}"`
|
|
1461
|
+
can resolve a local branch of that name and is only used where git expects it
|
|
1462
|
+
(`branch_delete` with `remotes: true`).
|
|
1463
|
+
|
|
1464
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1465
|
+
|-----------------------------------------------------|-------------|
|
|
1466
|
+
| `g.branch(name)` | `g.branch_list(name).first` for a local branch, or `g.branch_list("#{remote}/#{name}").find(&:remote?)` for a remote-tracking one. A `Git::BranchInfo`, or `nil` when the branch does not exist; the `remotes/` and `refs/` forms match nothing |
|
|
1467
|
+
| `g.branch` | `g.branch_list(g.current_branch).first`. `nil` when HEAD is detached or unborn; use `g.current_branch_state` there |
|
|
1468
|
+
| `g.branches` | `g.branch_list`. Returns `Array<Git::BranchInfo>` |
|
|
1469
|
+
| `g.branches[name]` | `g.branch_list(name).first`, or `g.branch_list("#{remote}/#{name}").find(&:remote?)` for a remote-tracking branch |
|
|
1470
|
+
| `g.branches.local` | `g.branch_list.reject(&:remote?)` |
|
|
1471
|
+
| `g.branches.remote` | `g.branch_list.select(&:remote?)` |
|
|
1472
|
+
| `g.branches.size` | `g.branch_list.size` |
|
|
1473
|
+
| `g.branches.each { \|b\| ... }` | `g.branch_list.each { \|info\| ... }` |
|
|
1474
|
+
| `g.branches.to_s` | `g.branch_list.map { \|i\| "#{i.current? ? '* ' : ' '}#{i.refname}\n" }.join`. Full refs, not `remotes/...` |
|
|
1475
|
+
| `b.full`, `b.to_s` | `info.refname`. `refs/remotes/origin/main` rather than `remotes/origin/main` |
|
|
1476
|
+
| `b.to_a` | `[info.refname]` |
|
|
1477
|
+
| `b.name` | `info.short_name` |
|
|
1478
|
+
| `b.remote` | `info.remote_name`. A `String`, or `nil` for a local branch |
|
|
1479
|
+
| `b.gcommit` | `g.gcommit(name)`. Pass `info.refname` for a remote-tracking branch |
|
|
1480
|
+
| `b.checkout` | `g.checkout(name)`. Does not create the branch (see above); pass `info.refname` for a remote-tracking branch |
|
|
1481
|
+
| `b.create` | `g.branch_new(name)`. Raises when the branch already exists |
|
|
1482
|
+
| `b.delete` (local) | `g.branch_delete(name)` |
|
|
1483
|
+
| `b.delete` (remote-tracking) | `g.branch_delete("#{remote}/#{name}", remotes: true)` |
|
|
1484
|
+
| `b.current` | `g.current_branch == name` |
|
|
1485
|
+
| `b.contains?(commit)` | `!g.branch_contains(commit, name).empty?` |
|
|
1486
|
+
| `b.merge` | `g.merge(name)` |
|
|
1487
|
+
| `b.merge(branch, message)` | `g.merge_into(name, branch, message)`. Local `b` only; see the differences above |
|
|
1488
|
+
| `b.update_ref(commit)` (local) | `g.update_ref(name, commit)` |
|
|
1489
|
+
| `b.update_ref(commit)` (remote-tracking) | `g.update_ref("remotes/#{remote}/#{name}", commit)` |
|
|
1490
|
+
| `b.archive(file, opts)` | `g.archive(name, file, opts)`. Pass `info.refname` for a remote-tracking branch |
|
|
1491
|
+
| `b.in_branch(message) { ... }` | `g.in_branch(name, message) { ... }`. Local `b` only; see the differences above |
|
|
1492
|
+
| `b.stashes` | `g.stash_infos`. See [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
|
|
1493
|
+
|
|
1494
|
+
#### `Git::Object::Tag` deprecated
|
|
1495
|
+
|
|
1496
|
+
`Git::Object::Tag`, `Git::Repository#tag`, `Git::Repository#tags`, and
|
|
1497
|
+
`Git::Repository#tag_add` are deprecated and are removed in v6.0.0. Read tag data
|
|
1498
|
+
through `Git::Repository#tag_list`, which returns one `Git::TagInfo` value object per
|
|
1499
|
+
tag, create tags with `Git::Repository#tag_create`, which returns the new tag's
|
|
1500
|
+
`Git::TagInfo`, and call the repository-level operations (`archive`, `log`, `diff`,
|
|
1501
|
+
`cat_file_contents`, and so on) with the tag's object ID,
|
|
1502
|
+
`info.oid || info.target_oid`, which is the object a `Git::Object::Tag` pinned when
|
|
1503
|
+
it was constructed. Calling `g.tag`, `g.tags`, or
|
|
1504
|
+
`g.tag_add`, and constructing a `Git::Object::Tag`, each emit one deprecation
|
|
1505
|
+
warning; their return values are unchanged. `g.add_tag` already warned, pointing at
|
|
1506
|
+
`g.tag_add`, and now emits two warnings for a creation call, one for itself and one
|
|
1507
|
+
for the `g.tag_add` it calls; `g.add_tag(name, d: true)` emits three, adding the
|
|
1508
|
+
`:d`/`:delete` warning described below. The readers on a `Git::Object::Tag` do not
|
|
1509
|
+
warn.
|
|
1510
|
+
|
|
1511
|
+
> **Return shape change.** `Git::Object::Tag` exposes `name`, `sha`, `objectish`,
|
|
1512
|
+
> `annotated?`, `message`, and `tagger`. `Git::TagInfo` exposes `name`, `oid`,
|
|
1513
|
+
> `target_oid`, `objecttype`, `annotated?`, `lightweight?`, `message`, and
|
|
1514
|
+
> `tagger`. `name` and `annotated?` are unchanged. `tagger` keeps the same `name`
|
|
1515
|
+
> and `email`, but `tagger.date` differs: `t.tagger.date` is a `Time` in the
|
|
1516
|
+
> process's local zone, while `info.tagger.date` keeps the UTC offset recorded in
|
|
1517
|
+
> the tag object. Both name the same instant. `message` differs for an annotated
|
|
1518
|
+
> tag created with an empty message (`message: ''`): `t.message` returns `""` and
|
|
1519
|
+
> `info.message` returns `nil`, the same value a lightweight tag has. `t.sha` and
|
|
1520
|
+
> `t.objectish` are the tag object's ID for an annotated tag and
|
|
1521
|
+
> the tagged object's ID for a lightweight tag. `Git::TagInfo` separates the two:
|
|
1522
|
+
> `oid` is the tag object's ID (`nil` for a lightweight tag) and `target_oid` is
|
|
1523
|
+
> the ID of the object the tag points to (set for both kinds), so
|
|
1524
|
+
> `info.oid || info.target_oid` reproduces `t.sha`. The target is usually a
|
|
1525
|
+
> commit, but a tag can point at any git object, and `info.objecttype` reports
|
|
1526
|
+
> which kind (`tag` for an annotated tag, or the target's own type such as
|
|
1527
|
+
> `commit` or `blob` for a lightweight one).
|
|
1528
|
+
>
|
|
1529
|
+
> **Missing tags.** `g.tag(name)` raises `Git::UnexpectedResultError` when no tag
|
|
1530
|
+
> has that name. `g.tag_list(name).first` returns `nil`.
|
|
1531
|
+
>
|
|
1532
|
+
> **`tag_create` in v6.0.0.** On v5.x, `g.tag_create` returns `nil` when the tag it
|
|
1533
|
+
> has just created is missing from the tag list. v6.0.0 raises instead; see
|
|
1534
|
+
> [`tag_create` raises when the created tag is
|
|
1535
|
+
> missing](#tag_create-raises-when-the-created-tag-is-missing).
|
|
1536
|
+
>
|
|
1537
|
+
> **Deleting through `tag_add`.** `g.tag_add(name, d: true)`, which was already
|
|
1538
|
+
> deprecated, deletes the tag and emits a second warning pointing at
|
|
1539
|
+
> `g.tag_delete`. `g.tag_create` rejects `:d` and `:delete` with `ArgumentError`.
|
|
1540
|
+
>
|
|
1541
|
+
> **Extra positional arguments.** `g.tag_add(name, target, extra)` ignores
|
|
1542
|
+
> `extra` and tags `target`. `g.tag_create` raises `ArgumentError` when more than
|
|
1543
|
+
> one positional argument follows the name.
|
|
1544
|
+
>
|
|
1545
|
+
> **Object identity.** Every `Git::Object::Tag` resolves its tag to an object ID
|
|
1546
|
+
> when it is constructed and runs `size`, `contents`, `grep`, `diff`, `log`, and
|
|
1547
|
+
> `archive` against that ID, so moving or deleting the tag afterwards does not
|
|
1548
|
+
> redirect an existing object. `Git::Object::Tag.new(g, sha, name)` uses the
|
|
1549
|
+
> supplied `sha` as that ID; the other forms look it up from the ref. `annotated?`,
|
|
1550
|
+
> `message`, and `tagger` always read the ref `name`. `Git::TagInfo` describes the
|
|
1551
|
+
> ref only: `g.tag_list(name).first` returns whatever `name` points at now, or
|
|
1552
|
+
> `nil` once the tag is deleted. Keep the same identity by passing `id` (see the
|
|
1553
|
+
> table) rather than `name` to the operation replacements; they accept any object.
|
|
1554
|
+
> To read an annotated tag object by ID without going through its ref, use
|
|
1555
|
+
> `g.cat_file_tag(id)`, which returns the tag object's `object`, `type`, `tag`,
|
|
1556
|
+
> `tagger`, and `message`.
|
|
1557
|
+
|
|
1558
|
+
In the table, `name` is the tag name, `t` is a `Git::Object::Tag`, `info` is the
|
|
1559
|
+
`Git::TagInfo` that replaces it, and `id` is `info.oid || info.target_oid` (or the
|
|
1560
|
+
`sha` given to the three-argument constructor), the object `t` pinned.
|
|
1561
|
+
|
|
1562
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1563
|
+
|-----------------------------------------------------|-------------|
|
|
1564
|
+
| `g.tag(name)` | `g.tag_list(name).first`. A `Git::TagInfo`, or `nil` when the tag does not exist |
|
|
1565
|
+
| `g.tags` | `g.tag_list`. Returns `Array<Git::TagInfo>` |
|
|
1566
|
+
| `g.tags.map(&:name)` | `g.tag_list.map(&:name)` |
|
|
1567
|
+
| `g.tag_add(name, opts)` | `g.tag_create(name, opts)`. Returns a `Git::TagInfo` |
|
|
1568
|
+
| `g.tag_add(name, target, opts)` | `g.tag_create(name, target, opts)` |
|
|
1569
|
+
| `g.tag_add(name, d: true)` | `g.tag_delete(name)` |
|
|
1570
|
+
| `g.add_tag(name, opts)`, `g.add_tag(name, target, opts)` | `g.tag_create(name, ...)`. Its warning names `g.tag_add`, which is deprecated too; go straight to `g.tag_create` |
|
|
1571
|
+
| `g.add_tag(name, d: true)` | `g.tag_delete(name)`. `g.tag_create` rejects `:d`; see the deletion note above |
|
|
1572
|
+
| `Git::Object::Tag.new(g, name)` | `g.tag_list(name).first` |
|
|
1573
|
+
| `Git::Object::Tag.new(g, sha, name)` | `g.tag_list(name).first`. Reads the ref rather than `sha`; use `sha` as `id` for the operations below, or read the object with `g.cat_file_tag(sha)`; see the object identity note above |
|
|
1574
|
+
| `Git::Object.new(g, name, nil, true)` | `g.tag_list(name).first`. Its warning names `Git::Object::Tag.new`, which is deprecated too |
|
|
1575
|
+
| `t.name` | `info.name` |
|
|
1576
|
+
| `t.sha`, `t.objectish`, `t.to_s` | `info.oid \|\| info.target_oid`. See the return shape change above |
|
|
1577
|
+
| `t.annotated?` | `info.annotated?` |
|
|
1578
|
+
| `t.message` | `info.message`. `nil` rather than `""` for an annotated tag with an empty message |
|
|
1579
|
+
| `t.tagger` | `info.tagger`. `date` keeps the recorded UTC offset; see the return shape change above |
|
|
1580
|
+
| `t.tag?` | not needed; every `Git::TagInfo` is a tag |
|
|
1581
|
+
| `t.size` | `g.cat_file_size(id)`. `id` rather than `name` keeps this and the operations below on the object `t` pinned; see the object identity note above |
|
|
1582
|
+
| `t.contents` | `g.cat_file_contents(id)` |
|
|
1583
|
+
| `t.contents { \|file\| ... }` | `g.cat_file_contents(id) { \|file\| ... }`. Streams to a temporary file instead of buffering the object |
|
|
1584
|
+
| `t.contents_array` | `g.cat_file_contents(id).split("\n")` |
|
|
1585
|
+
| `t.grep(string, path, opts)` | `g.grep(string, path, opts.merge(object: id))` |
|
|
1586
|
+
| `t.diff(other)` | `g.diff(id, other)` |
|
|
1587
|
+
| `t.log(count)` | `g.log(count).object(id)` |
|
|
1588
|
+
| `t.archive(file, opts)` | `g.archive(id, file, opts)` |
|
|
1589
|
+
|
|
1590
|
+
#### `Git::Status` deprecated
|
|
1591
|
+
|
|
1592
|
+
Starting in v5.4.0, `Git::Status`, `Git::Status::StatusFile`, and
|
|
1593
|
+
`Git::Repository#status` are deprecated and are removed in v6.0.0. Read the
|
|
1594
|
+
index and working tree state through `Git::Repository#status_info`, which
|
|
1595
|
+
returns an immutable `Git::StatusInfo` holding one `Git::StatusFileInfo` per
|
|
1596
|
+
path that `git status --porcelain=v2` reports. Calling `g.status` emits one
|
|
1597
|
+
deprecation warning, and so does constructing a `Git::Status` directly.
|
|
1598
|
+
|
|
1599
|
+
`Git::StatusInfo` keeps the `changed`, `added`, `deleted`, and `untracked`
|
|
1600
|
+
readers and the `changed?`, `added?`, `deleted?`, and `untracked?` predicates,
|
|
1601
|
+
so code that only uses those can change `status` to `status_info` and needs
|
|
1602
|
+
no other edit, subject to the category differences below. The readers now
|
|
1603
|
+
return `Hash{String => Git::StatusFileInfo}`, and a new `unmerged` reader
|
|
1604
|
+
lists conflicted paths, which `Git::Status` did not report. The predicates
|
|
1605
|
+
still compare paths case-insensitively when `core.ignoreCase` is `true`.
|
|
1606
|
+
`Git::StatusInfo` is not `Enumerable`; iterate `status_info.files`, an
|
|
1607
|
+
`Array<Git::StatusFileInfo>` in git's output order.
|
|
1608
|
+
|
|
1609
|
+
The categories are derived differently. `Git::Status` gave each file one
|
|
1610
|
+
`type`, and `changed` held only files whose type was `M`, so `changed`,
|
|
1611
|
+
`added`, and `deleted` were disjoint: a file staged as new and then modified
|
|
1612
|
+
in the working tree was only `added`. `Git::StatusInfo` derives the
|
|
1613
|
+
categories from both status characters, so `changed` also includes type
|
|
1614
|
+
changes (`T`), and one path can be in more than one category: that same file
|
|
1615
|
+
(`AM`) is in both `added` and `changed`, and a file modified in the index and
|
|
1616
|
+
then deleted from the working tree (`MD`) is in both `changed` and `deleted`.
|
|
1617
|
+
Code that relied on the sets being disjoint should test `index_status` and
|
|
1618
|
+
`worktree_status` directly.
|
|
1619
|
+
|
|
1620
|
+
`Git::StatusInfo` holds only the paths `git status` reports. `Git::Status`
|
|
1621
|
+
also held an entry for every clean tracked file, seeded from `git ls-files`,
|
|
1622
|
+
so `status[path]` returned a `Git::Status::StatusFile` with a `nil` type for an
|
|
1623
|
+
unchanged path and `status.each` yielded one. `status_info[path]` returns `nil`
|
|
1624
|
+
for a clean path and `status_info.files` omits it. Code that inspected clean
|
|
1625
|
+
files should read `g.ls_files`, which still returns the index mode and SHA of
|
|
1626
|
+
every tracked path.
|
|
1627
|
+
|
|
1628
|
+
`Git::StatusFileInfo` replaces the single `type` character with the two status
|
|
1629
|
+
characters of the porcelain v2 format, `index_status` (HEAD versus index) and
|
|
1630
|
+
`worktree_status` (index versus working tree), plus the `changed?`, `added?`,
|
|
1631
|
+
`deleted?`, `renamed?`, `unmerged?`, `untracked?`, and `ignored?` predicates:
|
|
1632
|
+
`added?` is true when `index_status` is `A`, `deleted?` when either status is
|
|
1633
|
+
`D`, and `changed?` when either status is `M` or `T`. It holds no repository
|
|
1634
|
+
reference, so `blob` is gone; fetch the object through the repository instead.
|
|
1635
|
+
`stage` is gone too: an unmerged entry carries its stage 1, 2, and 3 modes and
|
|
1636
|
+
SHAs in `unmerged_stages`, and every other entry is at stage 0.
|
|
1637
|
+
|
|
1638
|
+
> **Field renames.** The legacy mode and SHA readers were named for the wrong
|
|
1639
|
+
> sides. `sha_index` and `mode_index` held the working-tree side of the diff:
|
|
1640
|
+
> the index blob when the working tree matched the index, and an all-zero SHA
|
|
1641
|
+
> when it did not. `sha_repo` and `mode_repo` held the side git compared the
|
|
1642
|
+
> working tree against: the index in a repository with no commits, and HEAD
|
|
1643
|
+
> once a commit exists (the factory applied `git diff-index HEAD` last). The
|
|
1644
|
+
> new names follow git: `sha_head` and `mode_head` are the HEAD side,
|
|
1645
|
+
> `sha_index` and `mode_index` are the index (staged) side, and
|
|
1646
|
+
> `mode_worktree` is the working-tree mode. There is no working-tree SHA
|
|
1647
|
+
> because `git status` does not compute one; `worktree_status` says whether
|
|
1648
|
+
> the working tree differs from the index.
|
|
1649
|
+
|
|
1650
|
+
In the table, `g` is a `Git::Repository`, `status` is the `Git::Status` from
|
|
1651
|
+
`g.status`, `file` is a `Git::Status::StatusFile`, and `info` is the
|
|
1652
|
+
`Git::StatusFileInfo` that replaces it.
|
|
1653
|
+
|
|
1654
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1655
|
+
|-----------------------------------------------------|-------------|
|
|
1656
|
+
| `g.status` | `g.status_info`. Returns a `Git::StatusInfo` |
|
|
1657
|
+
| `Git::Status.new(g)` | `g.status_info` |
|
|
1658
|
+
| `status.changed`, `status.added`, `status.deleted`, `status.untracked` | same names on `g.status_info`. Now `Hash{String => Git::StatusFileInfo}` keyed by path |
|
|
1659
|
+
| `status.changed?(path)`, `status.added?(path)`, `status.deleted?(path)`, `status.untracked?(path)` | same names on `g.status_info` |
|
|
1660
|
+
| `status[path]` | `g.status_info[path]`. A `Git::StatusFileInfo`, or `nil`; `nil` for a clean tracked path, which `status[path]` reported (see above) |
|
|
1661
|
+
| `status.each { \|file\| ... }` | `g.status_info.files.each { \|info\| ... }`. Does not yield clean tracked paths (see above) |
|
|
1662
|
+
| `status.pretty` | no replacement; format `g.status_info.files` yourself |
|
|
1663
|
+
| `file.path` | `info.path` |
|
|
1664
|
+
| `file.type` | `info.index_status` and `info.worktree_status`, or the `info.changed?`, `info.added?`, and `info.deleted?` predicates |
|
|
1665
|
+
| `file.untracked` | `info.untracked?` |
|
|
1666
|
+
| `file.stage` | gone; `info.unmerged?` and `info.unmerged_stages` describe conflicted entries |
|
|
1667
|
+
| `file.sha_repo` | `info.sha_head`, or `info.sha_index` in a repository with no commits |
|
|
1668
|
+
| `file.mode_repo` | `info.mode_head`, or `info.mode_index` in a repository with no commits |
|
|
1669
|
+
| `file.sha_index` | `info.sha_index` for the staged blob; `info.worktree_status` says whether the working tree differs from it |
|
|
1670
|
+
| `file.mode_index` | `info.mode_worktree` |
|
|
1671
|
+
| `file.blob` | `g.object(info.sha_index)` when `info.sha_index` is set and not all zeros. It is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in the index; legacy `blob` returned `nil` without a lookup when no SHA was available and fell back to `sha_repo` when `sha_index` was `nil`. For an unmerged entry read a stage instead: `g.object(info.unmerged_stages[2][:sha])` |
|
|
1672
|
+
| `file.blob(:repo)` | `g.object(info.sha_head)` when `info.sha_head` is set and not all zeros. It is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in HEAD |
|
|
1673
|
+
|
|
1674
|
+
#### `Git::Worktree` and `Git::Worktrees` deprecated
|
|
1675
|
+
|
|
1676
|
+
`Git::Worktree`, `Git::Worktrees`, `Git::Repository#worktree`,
|
|
1677
|
+
`Git::Repository#worktrees`, and `Git::Repository#worktrees_all` are deprecated
|
|
1678
|
+
and are removed in v6.0.0. Read worktree data through
|
|
1679
|
+
`Git::Repository#worktree_list`, which returns one `Git::WorktreeInfo` value
|
|
1680
|
+
object per worktree, and call the repository-level operations (`worktree_add`,
|
|
1681
|
+
`worktree_remove`, `worktree_move`, `worktree_lock`, `worktree_unlock`,
|
|
1682
|
+
`worktree_repair`, and `worktree_prune`) with the worktree path or its
|
|
1683
|
+
`Git::WorktreeInfo`. Return values are unchanged on v5.x. Calling `g.worktree`,
|
|
1684
|
+
`g.worktrees`, or `g.worktrees_all`, constructing a `Git::Worktrees`, and calling
|
|
1685
|
+
`gcommit`, `add`, or `remove` on a `Git::Worktree` each emit a deprecation
|
|
1686
|
+
warning; the `dir`, `full`, `to_s`, and `to_a` readers on `Git::Worktree` do not.
|
|
1687
|
+
`g.worktrees` emits two warnings, one for itself and one for the `Git::Worktrees`
|
|
1688
|
+
it constructs, and `g.worktree(dir).add` emits one for `g.worktree` and one for
|
|
1689
|
+
`add`.
|
|
1690
|
+
|
|
1691
|
+
> **Return shape change.** `worktrees_all` returns `[directory, sha]` pairs and
|
|
1692
|
+
> omits the main worktree of a bare repository, which has no checked-out commit.
|
|
1693
|
+
> `worktree_list` returns `Git::WorktreeInfo` objects with `path`, `head`,
|
|
1694
|
+
> `branch` (the full refname, such as `refs/heads/main`, or `nil` when detached
|
|
1695
|
+
> or bare), `bare?`, `detached?`, `locked?` with `lock_reason`, and `prunable?`
|
|
1696
|
+
> with `prune_reason`. It includes the bare main worktree, with `head` and
|
|
1697
|
+
> `branch` set to `nil`. `Git::WorktreeInfo#to_s` is the path, so an entry can be
|
|
1698
|
+
> passed to any method that takes a worktree path.
|
|
1699
|
+
>
|
|
1700
|
+
> **`gcommit` return type.** `Git::Worktree#gcommit` returned a
|
|
1701
|
+
> `Git::Object::Commit` for a worktree obtained from `g.worktree(dir)` and a raw
|
|
1702
|
+
> SHA `String` for one obtained from `g.worktrees`. `info.head` is always a
|
|
1703
|
+
> `String` (or `nil` for a bare main worktree); call `g.gcommit(info.head)` for
|
|
1704
|
+
> the commit object.
|
|
1705
|
+
>
|
|
1706
|
+
> **`full` and `to_s`.** `Git::Worktree#full` and `#to_s` append the commitish
|
|
1707
|
+
> given at construction to the path, so entries from `g.worktrees` read
|
|
1708
|
+
> `"/path/to/wt <sha>"`. `Git::WorktreeInfo#to_s` is the path alone.
|
|
1709
|
+
>
|
|
1710
|
+
> **`worktree_add` in v6.0.0.** On v5.x, `worktree_add` returns the
|
|
1711
|
+
> `git worktree add` output (`"HEAD is now at …"`). In v6.0.0 it returns the new
|
|
1712
|
+
> `Git::WorktreeInfo` instead (see [`worktree_add` returns `Git::WorktreeInfo` and
|
|
1713
|
+
> raises when the worktree is
|
|
1714
|
+
> missing](#worktree_add-returns-gitworktreeinfo-and-raises-when-the-worktree-is-missing)).
|
|
1715
|
+
> To get the entry today, look it up after the add:
|
|
1716
|
+
> `g.worktree_list.find { |w| File.identical?(w.path, dir) }`. Compare with
|
|
1717
|
+
> `File.identical?`, not string equality: git stores worktree paths with
|
|
1718
|
+
> symlinks resolved, so `/tmp/...` on macOS is listed as `/private/tmp/...`,
|
|
1719
|
+
> and on case-insensitive filesystems the listed casing may differ from `dir`.
|
|
1720
|
+
|
|
1721
|
+
In the table, `dir` is the worktree path, `wt` is a `Git::Worktree`, and `info`
|
|
1722
|
+
is the `Git::WorktreeInfo` that replaces it.
|
|
1723
|
+
|
|
1724
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1725
|
+
|-----------------------------------------------------|-------------|
|
|
1726
|
+
| `g.worktrees_all` | `g.worktree_list.map { \|w\| [w.path, w.head] }`. Includes a bare main worktree as `[path, nil]`; add `.reject(&:bare?)` before `map` to omit it as `worktrees_all` did |
|
|
1727
|
+
| `g.worktrees` | `g.worktree_list`. Returns `Array<Git::WorktreeInfo>`; the deprecated call emits two warnings |
|
|
1728
|
+
| `g.worktrees[dir]` | `g.worktree_list.find { \|w\| w.path == dir }`. `nil` when not found; `dir` is the path as git reports it (absolute, with symlinks resolved), as before |
|
|
1729
|
+
| `g.worktrees.size` | `g.worktree_list.size` |
|
|
1730
|
+
| `g.worktrees.each { \|wt\| ... }` | `g.worktree_list.each { \|info\| ... }` |
|
|
1731
|
+
| `g.worktrees.to_s` | `g.worktree_list.map { \|w\| "#{w.path} #{w.head}\n" }.join` |
|
|
1732
|
+
| `g.worktrees.prune` | `g.worktree_prune` |
|
|
1733
|
+
| `g.worktree(dir).add` | `g.worktree_add(dir)` |
|
|
1734
|
+
| `g.worktree(dir, commitish).add` | `g.worktree_add(dir, commitish)` |
|
|
1735
|
+
| `g.worktree(dir).remove` | `g.worktree_remove(dir)` or `g.worktree_remove(info)` |
|
|
1736
|
+
| `wt.gcommit` | `info.head`. Always a `String`, or `nil` for a bare main worktree; `g.gcommit(info.head)` for the commit object |
|
|
1737
|
+
| `wt.dir` | `info.path` |
|
|
1738
|
+
| `wt.full`, `wt.to_s` | `info.path` or `"#{info.path} #{info.head}"` for the descriptor that entries from `g.worktrees` produced |
|
|
1739
|
+
| `wt.to_a` | `[info.path]` |
|
|
1740
|
+
|
|
1741
|
+
#### `Git.clone` option renames
|
|
1742
|
+
|
|
1743
|
+
Three `Git.clone` options were renamed in v5.x. The v4.x names still work in
|
|
1744
|
+
v5.x. Each deprecated option present on a call emits its own deprecation
|
|
1745
|
+
warning, so a call that uses two of them warns twice. Each value is passed
|
|
1746
|
+
through to the replacement option, except that `:path` is dropped when `:chdir`
|
|
1747
|
+
is also given.
|
|
1748
|
+
|
|
1749
|
+
> **Precedence and value notes:**
|
|
1750
|
+
> - `:path` and `:chdir` both run `git clone` from inside the given directory.
|
|
1751
|
+
> When both are given, `:chdir` wins and `:path` is dropped.
|
|
1752
|
+
> - `:recursive` carries its value over to `:recurse_submodules` unchanged.
|
|
1753
|
+
> `:recurse_submodules` also accepts a pathspec `String` or `Array<String>`
|
|
1754
|
+
> to initialize only a subset of submodules, which `:recursive` never did.
|
|
1755
|
+
> - `:remote` and `:origin` have the same effect (`git clone --origin name`).
|
|
1756
|
+
|
|
1757
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1758
|
+
|-----------------------------------------------------|-------------|
|
|
1759
|
+
| `Git.clone(url, dir, path: p)` | `Git.clone(url, dir, chdir: p)` |
|
|
1760
|
+
| `Git.clone(url, dir, recursive: true)` | `Git.clone(url, dir, recurse_submodules: true)` or a pathspec `String` or `Array<String>` for a subset of submodules |
|
|
1761
|
+
| `Git.clone(url, dir, remote: name)` | `Git.clone(url, dir, origin: name)` |
|
|
1762
|
+
|
|
1763
|
+
#### `Git::Log` Enumerable interface deprecated
|
|
1764
|
+
|
|
1765
|
+
`Git::Log` is a query builder. Calling `each`, `size`, `to_s`, `first`, `last`, or
|
|
1766
|
+
`[]` directly on it runs the query and emits a deprecation warning; those methods
|
|
1767
|
+
are removed in v6.0.0. Call `Git::Log#execute` instead. It runs the query and
|
|
1768
|
+
returns a `Git::Log::Result`, which includes `Enumerable` and provides the same
|
|
1769
|
+
six methods. The chainable query methods on `Git::Log` (`since`, `author`,
|
|
1770
|
+
`between`, `path`, `max_count`, and so on) are unchanged.
|
|
1771
|
+
|
|
1772
|
+
`Git::Log` includes `Enumerable`, so every `Enumerable` method called on the
|
|
1773
|
+
builder (`map`, `select`, `count`, `to_a`, `include?`, and so on) goes through the
|
|
1774
|
+
deprecated `each` and emits its warning. Move those calls to the result as well,
|
|
1775
|
+
not only the six named methods.
|
|
1776
|
+
|
|
1777
|
+
> **Snapshot results.** `execute` returns a snapshot. The builder re-runs
|
|
1778
|
+
> `git log` only when a query method (`since`, `max_count`, and so on) has been
|
|
1779
|
+
> called since the last run, even with the same value as before, so calling
|
|
1780
|
+
> `execute` twice on an untouched builder returns equal results without a second
|
|
1781
|
+
> `git log`. Keep the result object when a chain of operations needs the same
|
|
1782
|
+
> commits rather than calling `g.log` again, which builds a new query.
|
|
1783
|
+
|
|
1784
|
+
In the table, `g` is a `Git::Repository`.
|
|
1785
|
+
|
|
1786
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1787
|
+
|-----------------------------------------------------|-------------|
|
|
1788
|
+
| `g.log.each { \|c\| ... }` | `g.log.execute.each { \|c\| ... }` |
|
|
1789
|
+
| `g.log.size` | `g.log.execute.size` |
|
|
1790
|
+
| `g.log.to_s` | `g.log.execute.to_s`. Commits joined with newlines, as before |
|
|
1791
|
+
| `g.log.first`, `g.log.last` | `g.log.execute.first`, `g.log.execute.last` |
|
|
1792
|
+
| `g.log[i]`, `g.log[range]` | `g.log.execute[i]`, `g.log.execute[range]` |
|
|
1793
|
+
| any other `Enumerable` method on the log (`map`, `select`, `count`, `to_a`, `include?`, ...) | the same method on `g.log.execute` |
|
|
1794
|
+
|
|
1795
|
+
#### `Git::Object::Commit#set_commit` deprecated
|
|
1796
|
+
|
|
1797
|
+
`Git::Object::Commit#set_commit` is deprecated and is removed in v6.0.0. Call
|
|
1798
|
+
`from_data` instead; it takes the same parsed commit data hash and has the same
|
|
1799
|
+
effect.
|
|
1800
|
+
|
|
1801
|
+
| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
|
|
1802
|
+
|-----------------------------------------------------|-------------|
|
|
1803
|
+
| `commit.set_commit(data)` | `commit.from_data(data)` |
|
|
1804
|
+
|
|
1805
|
+
#### `Git.export` `:remote` option deprecated
|
|
1806
|
+
|
|
1807
|
+
`Git.export` has always dropped a `:remote` option before calling `Git.clone`
|
|
1808
|
+
without telling the caller. Passing it now emits a deprecation warning. The option
|
|
1809
|
+
is still dropped, so the export itself is unchanged, and it will be removed in a
|
|
1810
|
+
future major release. Once it is removed, passing `:remote` raises `ArgumentError`
|
|
1811
|
+
like any other unsupported option (see [Unsupported options raise
|
|
1812
|
+
`ArgumentError`](#unsupported-options-raise-argumenterror)).
|
|
1813
|
+
|
|
1814
|
+
There is no replacement option. `:remote` renamed the clone's remote, and
|
|
1815
|
+
`Git.export` deletes the `.git` directory before returning, so the name was never
|
|
1816
|
+
observable in the result. Delete the option from the call.
|
|
1817
|
+
|
|
1818
|
+
| Deprecated call (works in v5.x, removed in a future major release) | Replacement |
|
|
1819
|
+
|--------------------------------------------------------------------|-------------|
|
|
1820
|
+
| `Git.export(url, dir, remote: name)` | `Git.export(url, dir)` |
|
|
1821
|
+
|
|
1822
|
+
---
|