Module: Git

Defined in:
lib/git.rb,
lib/git.rb,
lib/git/lib.rb,
lib/git/log.rb,
lib/git/url.rb,
lib/git/base.rb,
lib/git/diff.rb,
lib/git/stash.rb,
lib/git/author.rb,
lib/git/branch.rb,
lib/git/config.rb,
lib/git/errors.rb,
lib/git/object.rb,
lib/git/remote.rb,
lib/git/status.rb,
lib/git/status.rb,
lib/git/status.rb,
lib/git/stashes.rb,
lib/git/version.rb,
lib/git/branches.rb,
lib/git/commands.rb,
lib/git/file_ref.rb,
lib/git/tag_info.rb,
lib/git/worktree.rb,
lib/git/diff_info.rb,
lib/git/worktrees.rb,
lib/git/diff_stats.rb,
lib/git/repository.rb,
lib/git/stash_info.rb,
lib/git/branch_info.rb,
lib/git/commands/am.rb,
lib/git/commands/gc.rb,
lib/git/commands/mv.rb,
lib/git/commands/rm.rb,
lib/git/diff_result.rb,
lib/git/fsck_object.rb,
lib/git/fsck_result.rb,
lib/git/parsers/tag.rb,
lib/git/args_builder.rb,
lib/git/command_line.rb,
lib/git/commands/add.rb,
lib/git/commands/log.rb,
lib/git/commands/tag.rb,
lib/git/dirstat_info.rb,
lib/git/escaped_path.rb,
lib/git/parsers/diff.rb,
lib/git/parsers/fsck.rb,
lib/git/parsers/grep.rb,
lib/git/commands/base.rb,
lib/git/commands/diff.rb,
lib/git/commands/fsck.rb,
lib/git/commands/grep.rb,
lib/git/commands/init.rb,
lib/git/commands/pull.rb,
lib/git/commands/push.rb,
lib/git/commands/show.rb,
lib/git/parsers/stash.rb,
lib/git/commands/apply.rb,
lib/git/commands/clean.rb,
lib/git/commands/clone.rb,
lib/git/commands/fetch.rb,
lib/git/commands/merge.rb,
lib/git/commands/reset.rb,
lib/git/commands/stash.rb,
lib/git/encoding_utils.rb,
lib/git/parsers/branch.rb,
lib/git/commands/branch.rb,
lib/git/commands/commit.rb,
lib/git/commands/remote.rb,
lib/git/commands/repack.rb,
lib/git/commands/revert.rb,
lib/git/commands/status.rb,
lib/git/parsers/ls_tree.rb,
lib/git/commands/am/quit.rb,
lib/git/commands/am/skip.rb,
lib/git/commands/archive.rb,
lib/git/commands/ls_tree.rb,
lib/git/commands/version.rb,
lib/git/diff_path_status.rb,
lib/git/parsers/cat_file.rb,
lib/git/command_line/base.rb,
lib/git/commands/am/abort.rb,
lib/git/commands/am/apply.rb,
lib/git/commands/am/retry.rb,
lib/git/commands/cat_file.rb,
lib/git/commands/checkout.rb,
lib/git/commands/describe.rb,
lib/git/commands/ls_files.rb,
lib/git/commands/name_rev.rb,
lib/git/commands/show_ref.rb,
lib/git/commands/tag/list.rb,
lib/git/commands/worktree.rb,
lib/git/execution_context.rb,
lib/git/tag_delete_result.rb,
lib/git/commands/arguments.rb,
lib/git/commands/ls_remote.rb,
lib/git/commands/read_tree.rb,
lib/git/commands/rev_parse.rb,
lib/git/commands/stash/pop.rb,
lib/git/detached_head_info.rb,
lib/git/diff_file_raw_info.rb,
lib/git/repository/diffing.rb,
lib/git/repository/logging.rb,
lib/git/repository/merging.rb,
lib/git/repository/staging.rb,
lib/git/tag_delete_failure.rb,
lib/git/version_constraint.rb,
lib/git/command_line/result.rb,
lib/git/command_line_result.rb,
lib/git/commands/diff_files.rb,
lib/git/commands/diff_index.rb,
lib/git/commands/merge/quit.rb,
lib/git/commands/merge_base.rb,
lib/git/commands/remote/add.rb,
lib/git/commands/stash/drop.rb,
lib/git/commands/stash/list.rb,
lib/git/commands/stash/push.rb,
lib/git/commands/stash/show.rb,
lib/git/commands/tag/create.rb,
lib/git/commands/tag/delete.rb,
lib/git/commands/tag/verify.rb,
lib/git/commands/update_ref.rb,
lib/git/commands/write_tree.rb,
lib/git/repository/stashing.rb,
lib/git/branch_delete_result.rb,
lib/git/commands/am/continue.rb,
lib/git/commands/branch/copy.rb,
lib/git/commands/branch/list.rb,
lib/git/commands/branch/move.rb,
lib/git/commands/commit_tree.rb,
lib/git/commands/maintenance.rb,
lib/git/commands/merge/abort.rb,
lib/git/commands/merge/start.rb,
lib/git/commands/remote/list.rb,
lib/git/commands/remote/show.rb,
lib/git/commands/revert/quit.rb,
lib/git/commands/revert/skip.rb,
lib/git/commands/stash/apply.rb,
lib/git/commands/stash/clear.rb,
lib/git/commands/stash/store.rb,
lib/git/diff_file_patch_info.rb,
lib/git/repository/branching.rb,
lib/git/branch_delete_failure.rb,
lib/git/commands/cat_file/raw.rb,
lib/git/commands/remote/prune.rb,
lib/git/commands/revert/abort.rb,
lib/git/commands/revert/start.rb,
lib/git/commands/stash/branch.rb,
lib/git/commands/stash/create.rb,
lib/git/commands/symbolic_ref.rb,
lib/git/commands/worktree/add.rb,
lib/git/repository/committing.rb,
lib/git/repository/inspecting.rb,
lib/git/command_line/capturing.rb,
lib/git/command_line/streaming.rb,
lib/git/commands/branch/create.rb,
lib/git/commands/branch/delete.rb,
lib/git/commands/remote/remove.rb,
lib/git/commands/remote/rename.rb,
lib/git/commands/remote/update.rb,
lib/git/commands/show_ref/list.rb,
lib/git/commands/worktree/list.rb,
lib/git/commands/worktree/lock.rb,
lib/git/commands/worktree/move.rb,
lib/git/diff_file_numstat_info.rb,
lib/git/repository/configuring.rb,
lib/git/commands/cat_file/batch.rb,
lib/git/commands/checkout/files.rb,
lib/git/commands/checkout_index.rb,
lib/git/commands/merge/continue.rb,
lib/git/commands/remote/get_url.rb,
lib/git/commands/remote/set_url.rb,
lib/git/commands/worktree/prune.rb,
lib/git/commands/checkout/branch.rb,
lib/git/commands/maintenance/run.rb,
lib/git/commands/remote/set_head.rb,
lib/git/commands/revert/continue.rb,
lib/git/commands/show_ref/exists.rb,
lib/git/commands/show_ref/verify.rb,
lib/git/commands/worktree/remove.rb,
lib/git/commands/worktree/repair.rb,
lib/git/commands/worktree/unlock.rb,
lib/git/execution_context/global.rb,
lib/git/repository/path_resolver.rb,
lib/git/commands/maintenance/stop.rb,
lib/git/commands/update_ref/batch.rb,
lib/git/repository/shared_private.rb,
lib/git/commands/cat_file/filtered.rb,
lib/git/commands/maintenance/start.rb,
lib/git/commands/symbolic_ref/read.rb,
lib/git/commands/update_ref/delete.rb,
lib/git/commands/update_ref/update.rb,
lib/git/commands/remote/set_url_add.rb,
lib/git/commands/branch/set_upstream.rb,
lib/git/commands/branch/show_current.rb,
lib/git/commands/remote/set_branches.rb,
lib/git/commands/symbolic_ref/delete.rb,
lib/git/commands/symbolic_ref/update.rb,
lib/git/execution_context/repository.rb,
lib/git/repository/object_operations.rb,
lib/git/repository/remote_operations.rb,
lib/git/repository/status_operations.rb,
lib/git/commands/archive/list_formats.rb,
lib/git/commands/config_option_syntax.rb,
lib/git/commands/maintenance/register.rb,
lib/git/commands/am/show_current_patch.rb,
lib/git/commands/branch/unset_upstream.rb,
lib/git/commands/remote/set_url_delete.rb,
lib/git/repository/worktree_operations.rb,
lib/git/commands/maintenance/unregister.rb,
lib/git/commands/config_option_syntax/add.rb,
lib/git/commands/config_option_syntax/get.rb,
lib/git/commands/config_option_syntax/set.rb,
lib/git/commands/worktree/management_base.rb,
lib/git/commands/config_option_syntax/list.rb,
lib/git/commands/show_ref/exclude_existing.rb,
lib/git/commands/config_option_syntax/unset.rb,
lib/git/commands/config_option_syntax/get_all.rb,
lib/git/commands/config_option_syntax/get_color.rb,
lib/git/commands/config_option_syntax/unset_all.rb,
lib/git/commands/config_option_syntax/get_regexp.rb,
lib/git/commands/config_option_syntax/replace_all.rb,
lib/git/commands/config_option_syntax/get_urlmatch.rb,
lib/git/commands/config_option_syntax/get_color_bool.rb,
lib/git/commands/config_option_syntax/remove_section.rb,
lib/git/commands/config_option_syntax/rename_section.rb

Overview

These would be required by the main git.rb file

Defined Under Namespace

Modules: CommandLine, Commands, EncodingUtils, Parsers Classes: ArgsBuilder, Author, Base, Branch, BranchDeleteFailure, BranchDeleteResult, BranchInfo, Branches, CommandLineError, Config, DetachedHeadInfo, Diff, DiffFileNumstatInfo, DiffFilePatchInfo, DiffFileRawInfo, DiffInfo, DiffPathStatus, DiffResult, DiffStats, DirstatEntry, DirstatInfo, Error, EscapedPath, ExecutionContext, FailedError, FileDiffInfo, FileRef, FsckObject, FsckResult, GitAltURI, Lib, Log, Object, ProcessIOError, Remote, Repository, SignaledError, Stash, StashInfo, Stashes, Status, TagDeleteFailure, TagDeleteResult, TagInfo, TimeoutError, URL, UnexpectedResultError, Version, VersionConstraint, VersionError, Worktree, Worktrees

Constant Summary collapse

Deprecation = 
ActiveSupport::Deprecation.new('5.0.0', 'Git')
MINIMUM_GIT_VERSION =

Minimum git version required by this gem

Commands and features may require newer versions, but this is the absolute minimum supported version for the gem as a whole.

Returns:

Version.parse('2.28.0')
GitExecuteError =
Deprecated.

Use Git::Error instead

An alias for Git::Error

Git::GitExecuteError error class is an alias for Git::Error for backwards compatibility. It is recommended to use Git::Error directly.

ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
VERSION =

The current gem version

Returns:

  • (String) —

    the current gem version

'5.0.0.beta.1'
BRANCH_REFNAME_REGEXP =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Note:

This regex is similar to Git::Branch::BRANCH_NAME_REGEXP but uses \A/\z anchors instead of ^/$ for stricter matching. As part of the architectural redesign, Git::Branch will eventually be refactored to use BranchInfo internally, at which point this will become the single source of truth for branch name parsing.

Note:

This regex assumes remote names do not contain '/'. If a remote name contains '/', parsing will be incorrect. For example, 'remotes/team/upstream/main' would parse as remote_name='team' instead of 'team/upstream'. This is an inherent ambiguity in git refnames that can only be resolved with knowledge of configured remotes. See: https://github.com/ruby-git/ruby-git/issues/919

Regular expression for parsing branch refnames

Captures:

  • remote_name: the remote name (e.g., 'origin') for remote branches, nil for local
  • branch_name: the branch name without the remote prefix

Examples:

'main' => { remote_name: nil, branch_name: 'main' }
'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
%r{
  \A                              # start of string
  (?:(?:refs/)?remotes/(?<remote_name>[^/]+)/)? # optional 'refs?/remotes/<remote_name>/'
  (?<branch_name>.+)                   # branch name (everything else)
  \z                              # end of string
}x
CommandLineResult =

Backward-compatible alias for Git::CommandLine::Result

Git::CommandLine::Result

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#author_date ⇒ String (readonly)

Returns the author date in ISO 8601 format.

Returns:

  • (String) —

    the author date in ISO 8601 format



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#author_email ⇒ String (readonly)

Returns the email of the stash author.

Returns:

  • (String) —

    the email of the stash author



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#author_name ⇒ String (readonly)

Returns the name of the stash author.

Returns:

  • (String) —

    the name of the stash author



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#binary ⇒ Boolean (readonly)

Returns whether this is a binary file.

Returns:

  • (Boolean) —

    whether this is a binary file



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/git/diff_info.rb', line 45

FileDiffInfo = Data.define(
  :path,
  :patch,
  :mode,
  :src,
  :dst,
  :type,
  :binary
) do
  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end
end

#branch ⇒ String? (readonly)

Returns the branch name where the stash was created, or nil for custom stash messages.

Returns:

  • (String, nil) —

    the branch name where the stash was created, or nil for custom stash messages



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#committer_date ⇒ String (readonly)

Returns the committer date in ISO 8601 format.

Returns:

  • (String) —

    the committer date in ISO 8601 format



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#committer_email ⇒ String (readonly)

Returns the email of the stash committer.

Returns:

  • (String) —

    the email of the stash committer



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#committer_name ⇒ String (readonly)

Returns the name of the stash committer.

Returns:

  • (String) —

    the name of the stash committer



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#current ⇒ Boolean (readonly)

Whether this branch is currently checked out in the current worktree

Returns:

  • (Boolean) —

    true if this is the current branch



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/git/branch_info.rb', line 133

BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
  # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
  def detached? = false

  # @return [Boolean] true if this is an unborn branch (no commits yet)
  def unborn? = target_oid.nil?

  # @return [Boolean] true if this is the currently checked out branch
  def current? = current

  # @return [Boolean] true if this branch is checked out in another worktree
  def worktree? = worktree

  # @return [Boolean] true if this is a symbolic reference
  def symref? = !symref.nil?

  # @return [Boolean] true if this is a remote-tracking branch
  def remote? = !remote_name.nil?

  # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
  def remote_name
    parse_refname[:remote_name]
  end

  # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
  def short_name
    parse_refname[:branch_name]
  end

  # @return [String] string representation (the full refname)
  def to_s = refname

  private

  # Parse the refname and return match data
  #
  # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
  # so we don't need nil checking. If refname is empty/nil, this would fail at
  # object creation time since refname is a required attribute.
  #
  # @return [MatchData] the match result
  def parse_refname
    refname.match(Git::BRANCH_REFNAME_REGEXP)
  end
end

#deleted ⇒ Array<Git::BranchInfo> (readonly)

Branches that were successfully deleted

Returns:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/git/tag_delete_result.rb', line 45

TagDeleteResult = Data.define(:deleted, :not_deleted) do
  # Returns true if all requested tags were successfully deleted
  #
  # @return [Boolean] true if no tags failed to delete, false otherwise
  #
  # @example
  #   result = tag_delete.call('v1.0.0')
  #   if result.success?
  #     puts "All tags deleted successfully"
  #   else
  #     puts "Some tags could not be deleted:"
  #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
  #   end
  #
  def success?
    not_deleted.empty?
  end
end

#deletions ⇒ Integer (readonly)

Returns number of lines deleted.

Returns:

  • (Integer) —

    number of lines deleted



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/git/diff_file_raw_info.rb', line 67

DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
  # Get the primary file path
  #
  # Returns the destination path if it exists, otherwise the source path.
  # This is the "current" or "canonical" path for the file.
  #
  # @return [String] the file path
  #
  def path
    dst&.path || src&.path
  end

  # Get the source path (for renames/copies)
  #
  # @return [String, nil] the source path, or nil if file was added
  #
  def src_path
    src&.path
  end

  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end

  # Check if this file was renamed
  #
  # @return [Boolean]
  #
  def renamed?
    status == :renamed
  end

  # Check if this file was copied
  #
  # @return [Boolean]
  #
  def copied?
    status == :copied
  end

  # Check if this file was added
  #
  # @return [Boolean]
  #
  def added?
    status == :added
  end

  # Check if this file was deleted
  #
  # @return [Boolean]
  #
  def deleted?
    status == :deleted
  end
end

#directory ⇒ String (readonly)

Returns the directory path (always ends with '/').

Returns:

  • (String) —

    the directory path (always ends with '/')



19
 
# File 'lib/git/dirstat_info.rb', line 19

DirstatEntry = Data.define(:directory, :percentage)

#dirstat ⇒ DirstatInfo? (readonly)

Returns directory statistics if requested, nil otherwise.

Returns:

  • (DirstatInfo, nil) —

    directory statistics if requested, nil otherwise



31
 
# File 'lib/git/diff_result.rb', line 31

DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)

#dst ⇒ FileRef? (readonly)

Returns the destination file reference, or nil for deleted files.

Returns:

  • (FileRef, nil) —

    the destination file reference, or nil for deleted files



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/git/diff_info.rb', line 45

FileDiffInfo = Data.define(
  :path,
  :patch,
  :mode,
  :src,
  :dst,
  :type,
  :binary
) do
  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end
end

#entries ⇒ Array<DirstatEntry> (readonly)

Returns directory statistics in order from git output.

Returns:

  • (Array<DirstatEntry>) —

    directory statistics in order from git output



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/git/dirstat_info.rb', line 41

DirstatInfo = Data.define(:entries) do
  # Look up percentage by directory path
  #
  # @param directory [String] the directory path
  # @return [Float, nil] the percentage or nil if not found
  #
  def [](directory)
    entries.find { |e| e.directory == directory }&.percentage
  end

  # Convert to a Hash mapping directory to percentage
  #
  # @return [Hash<String, Float>]
  #
  def to_h
    entries.to_h { |e| [e.directory, e.percentage] }
  end

  # Number of directories in the dirstat
  #
  # @return [Integer]
  #
  def size
    entries.size
  end

  # Check if dirstat is empty
  #
  # @return [Boolean]
  #
  def empty?
    entries.empty?
  end

  # Iterate over entries
  #
  # @yield [DirstatEntry] each entry
  # @return [Enumerator] if no block given
  #
  def each(&block)
    entries.each(&block)
  end

  include Enumerable
end

#error_message ⇒ String (readonly)

The error message from git explaining why the branch could not be deleted

Returns:

  • (String) 


30
 
# File 'lib/git/tag_delete_failure.rb', line 30

TagDeleteFailure = Data.define(:name, :error_message)

#file_patches ⇒ Array<FileDiffInfo> (readonly)

Returns array of file diff info objects (empty if patch not requested).

Returns:

  • (Array<FileDiffInfo>) —

    array of file diff info objects (empty if patch not requested)



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/git/diff_info.rb', line 99

DiffInfo = Data.define(:stats, :file_patches) do
  # @!method insertions
  #   @return [Integer] total number of lines inserted

  # @!method deletions
  #   @return [Integer] total number of lines deleted

  # @!method lines
  #   @return [Integer] total number of lines changed (insertions + deletions)

  # @!method file_count
  #   @return [Integer] number of files changed

  # Total number of lines inserted
  #
  # @return [Integer]
  #
  def insertions
    stats[:total][:insertions]
  end

  # Total number of lines deleted
  #
  # @return [Integer]
  #
  def deletions
    stats[:total][:deletions]
  end

  # Total number of lines changed (insertions + deletions)
  #
  # @return [Integer]
  #
  def lines
    stats[:total][:lines]
  end

  # Number of files changed
  #
  # @return [Integer]
  #
  def file_count
    stats[:total][:files]
  end

  # Per-file statistics hash
  #
  # @return [Hash<String, Hash>] mapping file paths to `{ insertions:, deletions: }` hashes
  #
  def file_stats
    stats[:files]
  end

  # Check if patch information is available
  #
  # @return [Boolean] true if file_patches were loaded
  #
  def patches?
    !file_patches.empty?
  end

  # Get patch info for a specific file
  #
  # @param path [String] the file path
  # @return [FileDiffInfo, nil] the diff info or nil if not found
  #
  def patch_for(path)
    file_patches.find { |p| p.path == path }
  end
end

#files ⇒ Array<DiffFileNumstatInfo, DiffFileRawInfo, DiffFilePatchInfo> (readonly)

Returns per-file information.

Returns:



31
 
# File 'lib/git/diff_result.rb', line 31

DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)

#files_changed ⇒ Integer (readonly)

Returns number of files changed (from --shortstat).

Returns:

  • (Integer) —

    number of files changed (from --shortstat)



31
 
# File 'lib/git/diff_result.rb', line 31

DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)

#index ⇒ Integer (readonly)

Returns the stash index (0, 1, 2, ...).

Returns:

  • (Integer) —

    the stash index (0, 1, 2, ...)



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#insertions ⇒ Integer (readonly)

Returns number of lines inserted.

Returns:

  • (Integer) —

    number of lines inserted



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/git/diff_file_raw_info.rb', line 67

DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
  # Get the primary file path
  #
  # Returns the destination path if it exists, otherwise the source path.
  # This is the "current" or "canonical" path for the file.
  #
  # @return [String] the file path
  #
  def path
    dst&.path || src&.path
  end

  # Get the source path (for renames/copies)
  #
  # @return [String, nil] the source path, or nil if file was added
  #
  def src_path
    src&.path
  end

  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end

  # Check if this file was renamed
  #
  # @return [Boolean]
  #
  def renamed?
    status == :renamed
  end

  # Check if this file was copied
  #
  # @return [Boolean]
  #
  def copied?
    status == :copied
  end

  # Check if this file was added
  #
  # @return [Boolean]
  #
  def added?
    status == :added
  end

  # Check if this file was deleted
  #
  # @return [Boolean]
  #
  def deleted?
    status == :deleted
  end
end

#major ⇒ Integer (readonly)

The major version number

Returns:

  • (Integer) 


43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/git/version.rb', line 43

Version = Data.define(:major, :minor, :patch) do
  include Comparable

  # Parse a version string into a Version object
  #
  # Handles git's version output format, stripping platform suffixes
  # (like `.windows.1` or `.vfs.0`) and padding two-segment versions
  # to three segments.
  #
  # @example Parse various version string formats
  #   Git::Version.parse('2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
  #
  # @param string [String] version string to parse
  #
  # @return [Git::Version] the parsed version
  #
  # @raise [Git::UnexpectedResultError] if the string cannot be parsed as a version
  #
  def self.parse(string)
    version_match = string&.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
    raise Git::UnexpectedResultError, "Invalid version: #{string.inspect}" unless version_match

    major = version_match[1].to_i
    minor = version_match[2].to_i
    patch = (version_match[3] || '0').to_i

    new(major, minor, patch)
  end

  # Compare this version to another
  #
  # @param other [Git::Version] the version to compare to
  #
  # @return [Integer] -1, 0, or 1
  #
  def <=>(other)
    [major, minor, patch] <=> [other.major, other.minor, other.patch]
  end

  # Return the version as a dotted string
  #
  # @return [String] the version in "major.minor.patch" format
  #
  def to_s
    "#{major}.#{minor}.#{patch}"
  end

  # Return a readable representation
  #
  # @return [String] inspect string
  #
  def inspect
    "#<Git::Version #{self}>"
  end

  # Return the version as an array of integers
  #
  # Useful when legacy code expects the array shape returned by the
  # deprecated {Git::Lib#current_command_version} method.
  #
  # @return [Array<Integer>] [major, minor, patch]
  #
  # @example
  #   Git.git_version.to_a  #=> [2, 42, 0]
  #
  def to_a
    deconstruct
  end
end

#message ⇒ String (readonly)

Returns the stash message (e.g., 'WIP on main: abc123 commit msg').

Returns:

  • (String) —

    the stash message (e.g., 'WIP on main: abc123 commit msg')



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#minor ⇒ Integer (readonly)

The minor version number

Returns:

  • (Integer) 


43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/git/version.rb', line 43

Version = Data.define(:major, :minor, :patch) do
  include Comparable

  # Parse a version string into a Version object
  #
  # Handles git's version output format, stripping platform suffixes
  # (like `.windows.1` or `.vfs.0`) and padding two-segment versions
  # to three segments.
  #
  # @example Parse various version string formats
  #   Git::Version.parse('2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
  #
  # @param string [String] version string to parse
  #
  # @return [Git::Version] the parsed version
  #
  # @raise [Git::UnexpectedResultError] if the string cannot be parsed as a version
  #
  def self.parse(string)
    version_match = string&.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
    raise Git::UnexpectedResultError, "Invalid version: #{string.inspect}" unless version_match

    major = version_match[1].to_i
    minor = version_match[2].to_i
    patch = (version_match[3] || '0').to_i

    new(major, minor, patch)
  end

  # Compare this version to another
  #
  # @param other [Git::Version] the version to compare to
  #
  # @return [Integer] -1, 0, or 1
  #
  def <=>(other)
    [major, minor, patch] <=> [other.major, other.minor, other.patch]
  end

  # Return the version as a dotted string
  #
  # @return [String] the version in "major.minor.patch" format
  #
  def to_s
    "#{major}.#{minor}.#{patch}"
  end

  # Return a readable representation
  #
  # @return [String] inspect string
  #
  def inspect
    "#<Git::Version #{self}>"
  end

  # Return the version as an array of integers
  #
  # Useful when legacy code expects the array shape returned by the
  # deprecated {Git::Lib#current_command_version} method.
  #
  # @return [Array<Integer>] [major, minor, patch]
  #
  # @example
  #   Git.git_version.to_a  #=> [2, 42, 0]
  #
  def to_a
    deconstruct
  end
end

#mode ⇒ String (readonly)

Returns the file mode (e.g., '100644' for regular files).

Returns:

  • (String) —

    the file mode (e.g., '100644' for regular files)



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/git/file_ref.rb', line 33

FileRef = Data.define(:mode, :sha, :path) do
  # Check if this is a regular file (not executable, symlink, etc.)
  #
  # @return [Boolean] true if mode is 100644
  #
  def regular_file?
    mode == '100644'
  end

  # Check if this is an executable file
  #
  # @return [Boolean] true if mode is 100755
  #
  def executable?
    mode == '100755'
  end

  # Check if this is a symbolic link
  #
  # @return [Boolean] true if mode is 120000
  #
  def symlink?
    mode == '120000'
  end

  # Return the mode as an integer (parsed as octal)
  #
  # Useful for bit operations on file permissions.
  #
  # @return [Integer] the mode as an integer
  #
  # @example Check file permissions
  #   ref.mode_bits & 0o777  # => 0o644 (420 decimal)
  #
  # @example Check if group writable
  #   (ref.mode_bits & 0o020) != 0
  #
  def mode_bits
    mode.to_i(8)
  end
end

#name ⇒ String (readonly)

The name of the branch that failed to be deleted

Returns:

  • (String) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#not_deleted ⇒ Array<Git::BranchDeleteFailure> (readonly)

Branches that could not be deleted, with the reason for each failure

Returns:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/git/tag_delete_result.rb', line 45

TagDeleteResult = Data.define(:deleted, :not_deleted) do
  # Returns true if all requested tags were successfully deleted
  #
  # @return [Boolean] true if no tags failed to delete, false otherwise
  #
  # @example
  #   result = tag_delete.call('v1.0.0')
  #   if result.success?
  #     puts "All tags deleted successfully"
  #   else
  #     puts "Some tags could not be deleted:"
  #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
  #   end
  #
  def success?
    not_deleted.empty?
  end
end

#objecttype ⇒ String (readonly)

Returns 'tag' for annotated tags, 'commit' for lightweight tags.

Returns:

  • (String) —

    'tag' for annotated tags, 'commit' for lightweight tags



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#oid ⇒ String (readonly)

Returns the full 40-character object identifier of the stash.

Returns:

  • (String) —

    the full 40-character object identifier of the stash



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#patch ⇒ String (readonly)

Returns the full unified diff patch text for this file.

Returns:

  • (String) —

    the full unified diff patch text for this file



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/git/version.rb', line 43

Version = Data.define(:major, :minor, :patch) do
  include Comparable

  # Parse a version string into a Version object
  #
  # Handles git's version output format, stripping platform suffixes
  # (like `.windows.1` or `.vfs.0`) and padding two-segment versions
  # to three segments.
  #
  # @example Parse various version string formats
  #   Git::Version.parse('2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
  #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
  #
  # @param string [String] version string to parse
  #
  # @return [Git::Version] the parsed version
  #
  # @raise [Git::UnexpectedResultError] if the string cannot be parsed as a version
  #
  def self.parse(string)
    version_match = string&.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
    raise Git::UnexpectedResultError, "Invalid version: #{string.inspect}" unless version_match

    major = version_match[1].to_i
    minor = version_match[2].to_i
    patch = (version_match[3] || '0').to_i

    new(major, minor, patch)
  end

  # Compare this version to another
  #
  # @param other [Git::Version] the version to compare to
  #
  # @return [Integer] -1, 0, or 1
  #
  def <=>(other)
    [major, minor, patch] <=> [other.major, other.minor, other.patch]
  end

  # Return the version as a dotted string
  #
  # @return [String] the version in "major.minor.patch" format
  #
  def to_s
    "#{major}.#{minor}.#{patch}"
  end

  # Return a readable representation
  #
  # @return [String] inspect string
  #
  def inspect
    "#<Git::Version #{self}>"
  end

  # Return the version as an array of integers
  #
  # Useful when legacy code expects the array shape returned by the
  # deprecated {Git::Lib#current_command_version} method.
  #
  # @return [Array<Integer>] [major, minor, patch]
  #
  # @example
  #   Git.git_version.to_a  #=> [2, 42, 0]
  #
  def to_a
    deconstruct
  end
end

#path ⇒ String (readonly)

Returns the file path (destination path for renames).

Returns:

  • (String) —

    the file path (destination path for renames)



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/git/file_ref.rb', line 33

FileRef = Data.define(:mode, :sha, :path) do
  # Check if this is a regular file (not executable, symlink, etc.)
  #
  # @return [Boolean] true if mode is 100644
  #
  def regular_file?
    mode == '100644'
  end

  # Check if this is an executable file
  #
  # @return [Boolean] true if mode is 100755
  #
  def executable?
    mode == '100755'
  end

  # Check if this is a symbolic link
  #
  # @return [Boolean] true if mode is 120000
  #
  def symlink?
    mode == '120000'
  end

  # Return the mode as an integer (parsed as octal)
  #
  # Useful for bit operations on file permissions.
  #
  # @return [Integer] the mode as an integer
  #
  # @example Check file permissions
  #   ref.mode_bits & 0o777  # => 0o644 (420 decimal)
  #
  # @example Check if group writable
  #   (ref.mode_bits & 0o020) != 0
  #
  def mode_bits
    mode.to_i(8)
  end
end

#percentage ⇒ Float (readonly)

Returns the percentage of changes in this directory (0.0-100.0).

Returns:

  • (Float) —

    the percentage of changes in this directory (0.0-100.0)



19
 
# File 'lib/git/dirstat_info.rb', line 19

DirstatEntry = Data.define(:directory, :percentage)

#refname ⇒ String (readonly)

The full reference name of the branch

Returns:

  • (String) —

    the branch refname (e.g., 'main', 'remotes/origin/main')



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/git/branch_info.rb', line 133

BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
  # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
  def detached? = false

  # @return [Boolean] true if this is an unborn branch (no commits yet)
  def unborn? = target_oid.nil?

  # @return [Boolean] true if this is the currently checked out branch
  def current? = current

  # @return [Boolean] true if this branch is checked out in another worktree
  def worktree? = worktree

  # @return [Boolean] true if this is a symbolic reference
  def symref? = !symref.nil?

  # @return [Boolean] true if this is a remote-tracking branch
  def remote? = !remote_name.nil?

  # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
  def remote_name
    parse_refname[:remote_name]
  end

  # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
  def short_name
    parse_refname[:branch_name]
  end

  # @return [String] string representation (the full refname)
  def to_s = refname

  private

  # Parse the refname and return match data
  #
  # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
  # so we don't need nil checking. If refname is empty/nil, this would fail at
  # object creation time since refname is a required attribute.
  #
  # @return [MatchData] the match result
  def parse_refname
    refname.match(Git::BRANCH_REFNAME_REGEXP)
  end
end

#sha ⇒ String (readonly)

Returns the blob SHA (object identifier).

Returns:

  • (String) —

    the blob SHA (object identifier)



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/git/file_ref.rb', line 33

FileRef = Data.define(:mode, :sha, :path) do
  # Check if this is a regular file (not executable, symlink, etc.)
  #
  # @return [Boolean] true if mode is 100644
  #
  def regular_file?
    mode == '100644'
  end

  # Check if this is an executable file
  #
  # @return [Boolean] true if mode is 100755
  #
  def executable?
    mode == '100755'
  end

  # Check if this is a symbolic link
  #
  # @return [Boolean] true if mode is 120000
  #
  def symlink?
    mode == '120000'
  end

  # Return the mode as an integer (parsed as octal)
  #
  # Useful for bit operations on file permissions.
  #
  # @return [Integer] the mode as an integer
  #
  # @example Check file permissions
  #   ref.mode_bits & 0o777  # => 0o644 (420 decimal)
  #
  # @example Check if group writable
  #   (ref.mode_bits & 0o020) != 0
  #
  def mode_bits
    mode.to_i(8)
  end
end

#short_oid ⇒ String (readonly)

Returns the abbreviated object identifier (typically 7 characters).

Returns:

  • (String) —

    the abbreviated object identifier (typically 7 characters)



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/stash_info.rb', line 79

StashInfo = Data.define(
  :index,
  :name,
  :oid,
  :short_oid,
  :branch,
  :message,
  :author_name,
  :author_email,
  :author_date,
  :committer_name,
  :committer_email,
  :committer_date
) do
  # Returns the stash reference name
  #
  # @return [String] the stash name (e.g., 'stash@\\{0}')
  #
  # @example
  #   info.to_s # => 'stash@{0}'
  #
  def to_s
    name
  end
end

#similarity ⇒ Integer? (readonly)

Returns similarity percentage for renames/copies (0-100), nil otherwise.

Returns:

  • (Integer, nil) —

    similarity percentage for renames/copies (0-100), nil otherwise



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/git/diff_file_raw_info.rb', line 67

DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
  # Get the primary file path
  #
  # Returns the destination path if it exists, otherwise the source path.
  # This is the "current" or "canonical" path for the file.
  #
  # @return [String] the file path
  #
  def path
    dst&.path || src&.path
  end

  # Get the source path (for renames/copies)
  #
  # @return [String, nil] the source path, or nil if file was added
  #
  def src_path
    src&.path
  end

  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end

  # Check if this file was renamed
  #
  # @return [Boolean]
  #
  def renamed?
    status == :renamed
  end

  # Check if this file was copied
  #
  # @return [Boolean]
  #
  def copied?
    status == :copied
  end

  # Check if this file was added
  #
  # @return [Boolean]
  #
  def added?
    status == :added
  end

  # Check if this file was deleted
  #
  # @return [Boolean]
  #
  def deleted?
    status == :deleted
  end
end

#src ⇒ FileRef? (readonly)

Returns the source file reference, or nil for new/added files.

Returns:

  • (FileRef, nil) —

    the source file reference, or nil for new/added files



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/git/diff_info.rb', line 45

FileDiffInfo = Data.define(
  :path,
  :patch,
  :mode,
  :src,
  :dst,
  :type,
  :binary
) do
  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end
end

#src_path ⇒ String? (readonly)

Returns the source path for renamed files, nil otherwise.

Returns:

  • (String, nil) —

    the source path for renamed files, nil otherwise



20
21
22
23
24
25
26
27
28
 
# File 'lib/git/diff_file_numstat_info.rb', line 20

DiffFileNumstatInfo = Data.define(:path, :src_path, :insertions, :deletions) do
  # Check if this file was renamed
  #
  # @return [Boolean] true if the file was renamed
  #
  def renamed?
    !src_path.nil?
  end
end

#stats ⇒ Hash (readonly)

Returns the statistics hash with :total and :files keys.

Returns:

  • (Hash) —

    the statistics hash with :total and :files keys



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/git/diff_info.rb', line 99

DiffInfo = Data.define(:stats, :file_patches) do
  # @!method insertions
  #   @return [Integer] total number of lines inserted

  # @!method deletions
  #   @return [Integer] total number of lines deleted

  # @!method lines
  #   @return [Integer] total number of lines changed (insertions + deletions)

  # @!method file_count
  #   @return [Integer] number of files changed

  # Total number of lines inserted
  #
  # @return [Integer]
  #
  def insertions
    stats[:total][:insertions]
  end

  # Total number of lines deleted
  #
  # @return [Integer]
  #
  def deletions
    stats[:total][:deletions]
  end

  # Total number of lines changed (insertions + deletions)
  #
  # @return [Integer]
  #
  def lines
    stats[:total][:lines]
  end

  # Number of files changed
  #
  # @return [Integer]
  #
  def file_count
    stats[:total][:files]
  end

  # Per-file statistics hash
  #
  # @return [Hash<String, Hash>] mapping file paths to `{ insertions:, deletions: }` hashes
  #
  def file_stats
    stats[:files]
  end

  # Check if patch information is available
  #
  # @return [Boolean] true if file_patches were loaded
  #
  def patches?
    !file_patches.empty?
  end

  # Get patch info for a specific file
  #
  # @param path [String] the file path
  # @return [FileDiffInfo, nil] the diff info or nil if not found
  #
  def patch_for(path)
    file_patches.find { |p| p.path == path }
  end
end

#status ⇒ Symbol (readonly)

Returns the change status (:added, :modified, :deleted, :renamed, :copied, :type_changed).

Returns:

  • (Symbol) —

    the change status (:added, :modified, :deleted, :renamed, :copied, :type_changed)



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/git/diff_file_raw_info.rb', line 67

DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
  # Get the primary file path
  #
  # Returns the destination path if it exists, otherwise the source path.
  # This is the "current" or "canonical" path for the file.
  #
  # @return [String] the file path
  #
  def path
    dst&.path || src&.path
  end

  # Get the source path (for renames/copies)
  #
  # @return [String, nil] the source path, or nil if file was added
  #
  def src_path
    src&.path
  end

  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end

  # Check if this file was renamed
  #
  # @return [Boolean]
  #
  def renamed?
    status == :renamed
  end

  # Check if this file was copied
  #
  # @return [Boolean]
  #
  def copied?
    status == :copied
  end

  # Check if this file was added
  #
  # @return [Boolean]
  #
  def added?
    status == :added
  end

  # Check if this file was deleted
  #
  # @return [Boolean]
  #
  def deleted?
    status == :deleted
  end
end

#symref ⇒ String? (readonly)

The target reference if this is a symbolic reference

Returns:

  • (String, nil) —

    the target ref (e.g., 'refs/heads/main'), or nil if not a symref



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/git/branch_info.rb', line 133

BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
  # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
  def detached? = false

  # @return [Boolean] true if this is an unborn branch (no commits yet)
  def unborn? = target_oid.nil?

  # @return [Boolean] true if this is the currently checked out branch
  def current? = current

  # @return [Boolean] true if this branch is checked out in another worktree
  def worktree? = worktree

  # @return [Boolean] true if this is a symbolic reference
  def symref? = !symref.nil?

  # @return [Boolean] true if this is a remote-tracking branch
  def remote? = !remote_name.nil?

  # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
  def remote_name
    parse_refname[:remote_name]
  end

  # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
  def short_name
    parse_refname[:branch_name]
  end

  # @return [String] string representation (the full refname)
  def to_s = refname

  private

  # Parse the refname and return match data
  #
  # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
  # so we don't need nil checking. If refname is empty/nil, this would fail at
  # object creation time since refname is a required attribute.
  #
  # @return [MatchData] the match result
  def parse_refname
    refname.match(Git::BRANCH_REFNAME_REGEXP)
  end
end

#tagger_date ⇒ String? (readonly)

Returns the tag date in ISO 8601 format, or nil for lightweight tags.

Returns:

  • (String, nil) —

    the tag date in ISO 8601 format, or nil for lightweight tags



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#tagger_email ⇒ String? (readonly)

Returns the tagger's email, or nil for lightweight tags.

Returns:

  • (String, nil) —

    the tagger's email, or nil for lightweight tags



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#tagger_name ⇒ String? (readonly)

Returns the tagger's name, or nil for lightweight tags.

Returns:

  • (String, nil) —

    the tagger's name, or nil for lightweight tags



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#target_oid ⇒ String (readonly)

The commit object ID (SHA) that HEAD points to

Returns:

  • (String) —

    the full 40-character object ID



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/git/tag_info.rb', line 79

TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
  # @return [Boolean] true if this is an annotated tag (oid is present)
  def annotated?
    !oid.nil?
  end

  # @return [Boolean] true if this is a lightweight tag (oid is nil)
  def lightweight?
    oid.nil?
  end

  # Return the tagger as an Author object
  #
  # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
  def tagger
    return nil unless annotated? && tagger_name && tagger_email

    # Git::Author expects format "Name <email> timestamp timezone"
    # We construct a minimal format that will parse correctly
    author = Git::Author.new('')
    author.name = tagger_name
    # Remove angle brackets if present
    author.email = tagger_email.gsub(/\A<|>\z/, '')
    author
  end
end

#total_deletions ⇒ Integer (readonly)

Returns total lines deleted across all files (from --shortstat).

Returns:

  • (Integer) —

    total lines deleted across all files (from --shortstat)



31
 
# File 'lib/git/diff_result.rb', line 31

DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)

#total_insertions ⇒ Integer (readonly)

Returns total lines inserted across all files (from --shortstat).

Returns:

  • (Integer) —

    total lines inserted across all files (from --shortstat)



31
 
# File 'lib/git/diff_result.rb', line 31

DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)

#type ⇒ String (readonly)

Returns the type of change: 'modified', 'new', 'deleted', 'renamed'.

Returns:

  • (String) —

    the type of change: 'modified', 'new', 'deleted', 'renamed'



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/git/diff_info.rb', line 45

FileDiffInfo = Data.define(
  :path,
  :patch,
  :mode,
  :src,
  :dst,
  :type,
  :binary
) do
  # Check if this is a binary file
  #
  # @return [Boolean] true if the file is binary
  #
  def binary?
    binary
  end
end

#upstream ⇒ Git::BranchInfo? (readonly)

Note:

Remote-tracking branches (e.g., 'origin/main') have upstream: nil

Note:

When upstream exists but the remote-tracking branch hasn't been fetched, the upstream's target_oid may be nil

The configured upstream/tracking branch

Returns:

  • (Git::BranchInfo, nil) —

    the upstream branch info, or nil if no upstream is configured



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/git/branch_info.rb', line 133

BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
  # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
  def detached? = false

  # @return [Boolean] true if this is an unborn branch (no commits yet)
  def unborn? = target_oid.nil?

  # @return [Boolean] true if this is the currently checked out branch
  def current? = current

  # @return [Boolean] true if this branch is checked out in another worktree
  def worktree? = worktree

  # @return [Boolean] true if this is a symbolic reference
  def symref? = !symref.nil?

  # @return [Boolean] true if this is a remote-tracking branch
  def remote? = !remote_name.nil?

  # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
  def remote_name
    parse_refname[:remote_name]
  end

  # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
  def short_name
    parse_refname[:branch_name]
  end

  # @return [String] string representation (the full refname)
  def to_s = refname

  private

  # Parse the refname and return match data
  #
  # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
  # so we don't need nil checking. If refname is empty/nil, this would fail at
  # object creation time since refname is a required attribute.
  #
  # @return [MatchData] the match result
  def parse_refname
    refname.match(Git::BRANCH_REFNAME_REGEXP)
  end
end

#worktree ⇒ Boolean (readonly)

Whether this branch is checked out in another linked worktree

Returns:

  • (Boolean) —

    true if checked out in a different worktree



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/git/branch_info.rb', line 133

BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
  # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
  def detached? = false

  # @return [Boolean] true if this is an unborn branch (no commits yet)
  def unborn? = target_oid.nil?

  # @return [Boolean] true if this is the currently checked out branch
  def current? = current

  # @return [Boolean] true if this branch is checked out in another worktree
  def worktree? = worktree

  # @return [Boolean] true if this is a symbolic reference
  def symref? = !symref.nil?

  # @return [Boolean] true if this is a remote-tracking branch
  def remote? = !remote_name.nil?

  # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
  def remote_name
    parse_refname[:remote_name]
  end

  # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
  def short_name
    parse_refname[:branch_name]
  end

  # @return [String] string representation (the full refname)
  def to_s = refname

  private

  # Parse the refname and return match data
  #
  # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
  # so we don't need nil checking. If refname is empty/nil, this would fail at
  # object creation time since refname is a required attribute.
  #
  # @return [MatchData] the match result
  def parse_refname
    refname.match(Git::BRANCH_REFNAME_REGEXP)
  end
end

Class Method Details

.bare(git_dir, options = {}) ⇒ Git::Base

Open a bare repository

Opens a bare repository located in the git_dir directory. Since there is no working copy, you can not checkout or commit but you can do most read operations.

Examples:

Open a bare repository and retrieve the first commit SHA

repository = Git.bare('ruby-git.git')
puts repository.log[0].sha #=> "64c6fa011d3287bab9158049c85f3e85718854a0"

Parameters:

  • git_dir (Pathname) —

    The path to the bare repository directory containing an initialized Git repository. If a relative path is given, it is converted to an absolute path using File.expand_path.

  • options (Hash) (defaults to: {}) —

    The options for this command (see list of valid options below)

Options Hash (options):

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Base) —

    an object that can execute git commands in the context of the bare repository.

See Also:



136
137
138
 
# File 'lib/git.rb', line 136

def self.bare(git_dir, options = {})
  Base.bare(git_dir, options)
end

.binary_version(binary_path = Git::Base.config.binary_path) ⇒ Array<Integer>

Deprecated.

Use git_version instead, which returns a Version (not an Array). For the legacy array shape, call: Git.git_version.to_a. The optional binary_path argument is preserved: Git.git_version(binary_path).

Return the version of the git binary

Examples:

Git.binary_version # => [2, 46, 0]

Returns:

  • (Array<Integer>) —

    the version of the git binary



526
527
528
529
530
531
532
533
534
 
# File 'lib/git.rb', line 526

def self.binary_version(binary_path = Git::Base.config.binary_path)
  Git::Deprecation.warn(
    'Git.binary_version is deprecated and will be removed in 6.0. ' \
    'Use Git.git_version instead, which returns a Git::Version ' \
    '(not an Array). For the legacy array shape, call: Git.git_version.to_a. ' \
    'The optional binary_path argument is preserved: Git.git_version(binary_path).'
  )
  git_version(binary_path).to_a
end

.clone(repository_url, directory = nil, options = {}) ⇒ Git::Base

Clone a repository into an empty or newly created directory

Examples:

Clone into the default directory ruby-git

git = Git.clone('https://github.com/ruby-git/ruby-git.git')

Clone and then checkout the development branch

git = Git.clone('https://github.com/ruby-git/ruby-git.git', branch: 'development')

Clone into a different directory my-ruby-git

git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')

Clone into a specific parent directory

git = Git.clone('https://github.com/ruby-git/ruby-git.git', chdir: '/path/to/projects')
# clones into /path/to/projects/ruby-git

Create a bare repository in the directory ruby-git.git

git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)

Clone a repository and set a single config option

git = Git.clone(
  'https://github.com/ruby-git/ruby-git.git',
  config: 'submodule.recurse=true'
)

Clone a repository and set multiple config options

git = Git.clone(
  'https://github.com/ruby-git/ruby-git.git',
  config: ['user.name=John Doe', 'user.email=john@doe.com']
)

Clone using a specific SSH key

git = Git.clone(
  'git@github.com:ruby-git/ruby-git.git',
  'local-dir',
  git_ssh: 'ssh -i /path/to/private_key'
)

Parameters:

  • repository_url (URI, Pathname) —

    The (possibly remote) repository url to clone from. See GIT URLS for more information.

  • directory (Pathname, nil) (defaults to: nil) —

    The directory to clone into

    If directory is a relative path it is relative to the :chdir option if given. If :chdir is not given, directory is relative to the current working directory.

    If nil, directory will be set to the basename of the last component of the path from the repository_url. For example, for the URL: https://github.com/org/repo.git, directory will be set to repo.

    If the last component of the path is .git, the next-to-last component of the path is used. For example, for the URL /Users/me/foo/.git, directory will be set to foo.

  • options (Hash) (defaults to: {}) —

    The options for this command (see list of valid options below)

Options Hash (options):

  • :bare (Boolean) —

    Make a bare Git repository. See what is a bare repository?.

  • :branch (String) —

    The name of a branch or tag to checkout instead of the default branch.

  • :config (Array, String) —

    A list of configuration options to set on the newly created repository.

  • :depth (Integer) —

    Create a shallow clone with a history truncated to the specified number of commits.

  • :filter (String) —

    Request that the server send a partial clone according to the given filter

  • :single_branch (Boolean, nil) —

    Control whether the clone limits fetch refspecs to a single branch.

    • If nil (default), no flag is passed and the Git default is used.
    • If true, --single-branch is passed to limit the refspec to the checkout branch.
    • If false, --no-single-branch is passed to broaden the refspec (useful for shallow clones that should include all branches).
  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

  • :mirror (Boolean) —

    Set up a mirror of the source repository.

  • :origin (String) —

    Use the value instead origin to track the upstream repository.

  • :chdir (Pathname) —

    Run git clone from within this directory.

    The directory parameter (or the repository basename when directory is nil) is resolved relative to :chdir, just as if you had cd'd into it before running git clone. The returned path is the join of :chdir and the cloned directory path.

  • :path (Pathname) —

    Deprecated — use :chdir instead.

  • :recursive (Boolean) —

    After the clone is created, initialize all submodules within, using their default settings.

Returns:

  • (Git::Base) —

    an object that can execute git commands in the context of the cloned local working copy or cloned repository.

See Also:



254
255
256
 
# File 'lib/git.rb', line 254

def self.clone(repository_url, directory = nil, options = {})
  Base.clone(repository_url, directory, options)
end

.config 



94
95
96
 
# File 'lib/git.rb', line 94

def self.config
  Base.config
end

.configure {|Base.config| ... }

Yields:



90
91
92
 
# File 'lib/git.rb', line 90

def self.configure
  yield Base.config
end

.default_branch(repository, options = {}) ⇒ String

Returns the name of the default branch of the given repository

Examples:

with a URI string

Git.default_branch('https://github.com/ruby-git/ruby-git') # => 'master'
Git.default_branch('https://github.com/rspec/rspec-core') # => 'main'

with a URI object

repository_uri = URI('https://github.com/ruby-git/ruby-git')
Git.default_branch(repository_uri) # => 'master'

with a local repository

Git.default_branch('.') # => 'master'

with a local repository Pathname

repository_path = Pathname('.')
Git.default_branch(repository_path) # => 'master'

with the logging option

logger = Logger.new(STDOUT, level: Logger::INFO)
Git.default_branch('.', log: logger) # => 'master'
I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true'
  '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1

Parameters:

  • repository (URI, Pathname, String) —

    The (possibly remote) repository to get the default branch name for

    See GIT URLS for more information.

  • options (Hash) (defaults to: {}) —

    The options for this command (see list of valid options below)

Options Hash (options):

  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (String) —

    the name of the default branch



295
296
297
 
# File 'lib/git.rb', line 295

def self.default_branch(repository, options = {})
  Base.repository_default_branch(repository, options)
end

.export(repository, name, options = {})

Export the current HEAD (or a branch, if options[:branch] is specified) into the +name+ directory, then remove all traces of git from the directory.

See +clone+ for options. Does not obey the :remote option, since the .git info will be deleted anyway; always uses the default remote, 'origin.'



306
307
308
309
310
311
 
# File 'lib/git.rb', line 306

def self.export(repository, name, options = {})
  options.delete(:remote)
  repo = clone(repository, name, { depth: 1 }.merge(options))
  repo.checkout("origin/#{options[:branch]}") if options[:branch]
  FileUtils.rm_r File.join(repo.dir.to_s, '.git')
end

.git_version(binary_path = nil) ⇒ Git::Version

Return the version of a git binary as a Version

Examples:

Default binary

Git.git_version #=> #<Git::Version 2.42.0>

Explicit binary path

Git.git_version('/opt/homebrew/bin/git') #=> #<Git::Version 2.42.0>

Parameters:

  • binary_path (String, nil) (defaults to: nil) —

    path to the git binary; defaults to Git::Base.config.binary_path

Returns:

Raises:



503
504
505
506
 
# File 'lib/git.rb', line 503

def self.git_version(binary_path = nil)
  path = binary_path || Git::Base.config.binary_path
  Git::Lib.cached_git_version(path) { run_git_version(path) }
end

.global_config(name = nil, value = nil)

Same as g.config, but forces it to be at the global level

g.config('user.name', 'Scott Chacon') # sets value g.config('user.email', 'email@email.com') # sets value g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/git.rb', line 319

def self.global_config(name = nil, value = nil)
  lib = Git::Lib.new(nil, nil)
  if name && value
    # set value
    lib.global_config_set(name, value)
  elsif name
    # return value
    lib.global_config_get(name)
  else
    # return hash
    lib.global_config_list
  end
end

.init(directory = '.', options = {}) ⇒ Git::Base

Create an empty Git repository or reinitialize an existing Git repository

Examples:

Initialize a repository in the current directory

git = Git.init

Initialize a repository in some other directory

git = Git.init '~/code/ruby-git'

Initialize a bare repository

git = Git.init '~/code/ruby-git.git', bare: true

Initialize a repository in a non-default location (outside of the working copy)

git = Git.init '~/code/ruby-git', repository: '~/code/ruby-git.git'

Parameters:

  • directory (Pathname) (defaults to: '.') —

    If the :bare option is NOT given or is not true, the repository will be created in "#{directory}/.git". Otherwise, the repository is created in "#{directory}".

    All directories along the path to directory are created if they do not exist.

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

  • options (Hash) (defaults to: {}) —

    The options for this command (see list of valid options below)

Options Hash (options):

  • :bare (Boolean) —

    Instead of creating a repository at "#{directory}/.git", create a bare repository at "#{directory}". See what is a bare repository?.

  • :initial_branch (String) —

    Use the specified name for the initial branch in the newly created repository.

  • :repository (Pathname) —

    the path to put the newly initialized Git repository. The default for non-bare repository is "#{directory}/.git".

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

  • :separate_git_dir (Pathname) —

    Alias for :repository.

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Base) —

    an object that can execute git commands in the context of the newly initialized repository

See Also:



391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/git.rb', line 391

def self.init(directory = '.', options = {})
  require_relative 'git/commands/init'

  options = options.dup
  options[:repository] ||= options.delete(:separate_git_dir)
  init_opts = options.slice(:bare, :initial_branch)
  init_opts[:separate_git_dir] = options[:repository] if options.key?(:repository)
  Git::Commands::Init.new(Git::Lib.new(nil, options[:log])).call(directory, **init_opts)

  open_initialized_repository(directory, options)
end

.ls_remote(location = nil, options = {}) ⇒ {String=>Hash}

returns a Hash containing information about the references of the target repository

options :refs

Parameters:

  • location (String|NilClass) (defaults to: nil) —

    the target repository location or nil for '.'

Returns:

  • ({String=>Hash}) —

    the available references of the target repo.



426
427
428
 
# File 'lib/git.rb', line 426

def self.ls_remote(location = nil, options = {})
  Git::Lib.new.ls_remote(location, options)
end

.open(working_dir, options = {}) ⇒ Git::Base

Open a an existing Git working directory

Git.open will most likely be the most common way to create a git reference, referring to an existing working directory.

If not provided in the options, the library will assume the repository and index are in the default places (.git/, .git/index).

Examples:

Open the Git working directory in the current directory

git = Git.open

Open a Git working directory in some other directory

git = Git.open('~/Projects/ruby-git')

Use a logger to see what is going on

logger = Logger.new(STDOUT)
git = Git.open('~/Projects/ruby-git', log: logger)

Open a working copy whose repository is in a non-standard directory

git = Git.open('~/Projects/ruby-git', repository: '~/Project/ruby-git.git')

Parameters:

  • working_dir (Pathname) —

    the path to the working directory to use for git commands.

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

  • options (Hash) (defaults to: {}) —

    The options for this command (see list of valid options below)

Options Hash (options):

  • :repository (Pathname) —

    used to specify a non-standard path to the repository directory. The default is "#{working_dir}/.git".

  • :index (Pathname) —

    used to specify a non-standard path to an index file. The default is "#{working_dir}/.git/index"

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Base) —

    an object that can execute git commands in the context of the opened working copy



480
481
482
 
# File 'lib/git.rb', line 480

def self.open(working_dir, options = {})
  Base.open(working_dir, options)
end

Instance Method Details

#config(name = nil, value = nil)

g.config('user.name', 'Scott Chacon') # sets value g.config('user.email', 'email@email.com') # sets value g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/git.rb', line 76

def config(name = nil, value = nil)
  lib = Git::Lib.new
  if name && value
    # set value
    lib.config_set(name, value)
  elsif name
    # return value
    lib.config_get(name)
  else
    # return hash
    lib.config_list
  end
end

#global_config(name = nil, value = nil) 



98
99
100
 
# File 'lib/git.rb', line 98

def global_config(name = nil, value = nil)
  self.class.global_config(name, value)
end