Module: Git::Repository::StatusOperations Private

Included in:
Git::Repository
Defined in:
lib/git/repository/status_operations.rb

Overview

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

Facade methods for repository-status operations

Provides methods for querying the state of the repository: checking whether any commits exist, listing untracked working-tree files, and listing files tracked in the index.

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#empty? ⇒ Boolean

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

Deprecated.

Use #no_commits? instead

Returns true if the repository has no commits yet

Examples:

Check whether a repository is empty

repo.empty? #=> true   # freshly initialized, no commits yet
repo.empty? #=> false  # at least one commit exists

Returns:

  • (Boolean) —

    true when the repository has no commits, false otherwise

Raises:

  • (Git::FailedError) —

    if git exits with a non-zero exit status other than when the repository has no commits



62
63
64
65
66
67
68
 
# File 'lib/git/repository/status_operations.rb', line 62

def empty?
  Git::Deprecation.warn(
    'Git::Repository#empty? is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#no_commits? instead.'
  )
  no_commits?
end

#ls_files(location = nil) ⇒ Hash{String => Hash}

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

List all files tracked in the index

Runs git ls-files --stage under the given location and returns a hash keyed by file path with per-file index metadata.

Examples:

List all indexed files in the working tree

repo.ls_files
#=> { "README.md" => { path: "README.md", mode_index: "100644",
#=>                    sha_index: "abc123...", stage: "0" }, ... }

List indexed files under a specific directory

repo.ls_files('lib/')
#=> { "lib/git.rb" => { path: "lib/git.rb", ... }, ... }

Parameters:

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

    the path to restrict the listing to; defaults to '.' (all tracked files) when nil

Returns:

  • (Hash{String => Hash}) —

    a hash of index entries keyed by file path

    Each value is a Hash with the following keys:

    • :path [String] the file path
    • :mode_index [String] the file's index mode (e.g. "100644")
    • :sha_index [String] the file's index SHA
    • :stage [String] the merge stage ("0" for normal entries)

Raises:



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/git/repository/status_operations.rb', line 191

def ls_files(location = nil)
  location ||= '.'
  {}.tap do |files|
    Git::Commands::LsFiles.new(@execution_context).call(location, stage: true).stdout.split("\n").each do |line|
      info, file = Private.split_status_line(line)
      mode, sha, stage = info.split
      files[file] = { path: file, mode_index: mode, sha_index: sha, stage: stage }
    end
  end
end

#no_commits? ⇒ Boolean

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

Returns true if the repository has no commits yet

Checks whether HEAD can be resolved to a commit object. A brand-new repository (or one created with git checkout --orphan) where no commit has been made yet will have no commits.

Examples:

Check whether a repository is empty

repo.no_commits? #=> true   # freshly initialized, no commits yet
repo.no_commits? #=> false  # at least one commit exists

Returns:

  • (Boolean) —

    true when the repository has no commits, false otherwise

Raises:

  • (Git::FailedError) —

    if git exits with a non-zero exit status other than when the repository has no commits



39
40
41
42
43
44
45
46
47
 
# File 'lib/git/repository/status_operations.rb', line 39

def no_commits?
  Git::Commands::RevParse.new(@execution_context).call('HEAD', verify: true)
  false
rescue Git::FailedError => e
  raise unless e.result.status.exitstatus == 128 &&
               e.result.stderr == 'fatal: Needed a single revision'

  true
end

#status ⇒ Git::Status

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

Deprecated.

Use #status_info instead

Returns a Status object describing the working tree and index state

Constructs a Status for this repository by collecting information from git ls-files --stage, git ls-files --others, git diff-files, and git diff-index HEAD (the last only when at least one commit exists). The result identifies which files have been modified, added, deleted, or are untracked.

Emits one deprecation warning per call. The Status it constructs is built with warnings silenced so the caller does not see a second one.

Examples:

Check which files are modified (deprecated; use status_info)

repo.status.changed.keys      #=> ["lib/foo.rb"]
repo.status_info.changed.keys #=> ["lib/foo.rb"]

Returns:

Raises:

  • (Git::FailedError) —

    if any underlying git command exits with a non-zero exit status



156
157
158
159
160
161
162
 
# File 'lib/git/repository/status_operations.rb', line 156

def status
  Git::Deprecation.warn(
    'Git::Repository#status is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#status_info instead.'
  )
  Git::Deprecation.silence { Git::Status.new(self) }
end

#status_info ⇒ Git::StatusInfo

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

Returns a StatusInfo describing the index and working tree state

Runs git status in porcelain v2 format with NUL-separated entries and every untracked file listed individually, then reads core.ignoreCase as a boolean so that the path predicates on the result compare paths the way git does in this repository. Every entry type git reports is represented, including renames, copies, and merge conflicts. Clean tracked paths are not reported by git status, so they are absent from the result; the deprecated #status listed them, and #ls_files still does.

Examples:

Check which files are modified

repo.status_info.changed
#=> { "lib/foo.rb" => #<data Git::StatusFileInfo path="lib/foo.rb", ...> }

Check for untracked files

repo.status_info.untracked.keys #=> ["new_file.rb"]

Check one path

repo.status_info.changed?('lib/foo.rb') #=> true

Iterate over every entry

repo.status_info.files.each do |file|
  puts "#{file.index_status}#{file.worktree_status} #{file.path}"
end

Returns:

Raises:

See Also:



125
126
127
128
129
130
131
132
 
# File 'lib/git/repository/status_operations.rb', line 125

def status_info
  result = Git::Commands::Status.new(@execution_context).call(
    porcelain: 'v2', z: true, untracked_files: 'all'
  )
  files = Git::Parsers::Status.parse(result.stdout)
  ignore_case = config_get('core.ignoreCase', type: 'bool')&.value == 'true'
  Git::StatusInfo.new(files: files, ignore_case: ignore_case)
end

#untracked_files ⇒ Array<String>

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

List all files in the working tree that are not tracked by git

Runs git ls-files --others --exclude-standard from the working tree root and returns an array of repository-relative file paths. Files that match .gitignore or other standard exclusion rules are omitted.

Examples:

Get untracked files

repo.untracked_files #=> ["new_feature.rb", "tmp/debug.log"]

No untracked files

repo.untracked_files #=> []

Returns:

  • (Array<String>) —

    repository-relative paths of untracked, non-ignored files; empty when there are none

Raises:



87
88
89
90
91
 
# File 'lib/git/repository/status_operations.rb', line 87

def untracked_files
  Git::Commands::LsFiles.new(@execution_context).call(
    others: true, exclude_standard: true, chdir: @execution_context.git_work_dir
  ).stdout.split("\n").map { |f| Private.unescape_quoted_path(f) }
end