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



59
60
61
62
63
64
65
 
# File 'lib/git/repository/status_operations.rb', line 59

def empty?
  Git::Deprecation.warn(
    'Git::Repository#empty? is deprecated and will be removed in a future version. ' \
    '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:



143
144
145
146
147
148
149
150
151
152
 
# File 'lib/git/repository/status_operations.rb', line 143

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



36
37
38
39
40
41
42
43
44
 
# File 'lib/git/repository/status_operations.rb', line 36

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.

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.

Examples:

Check which files are modified

repo.status.changed #=> { "lib/foo.rb" => <Git::Status::StatusFile ...> }

Check for untracked files

repo.status.untracked #=> { "new_file.rb" => <Git::Status::StatusFile ...> }

Iterate over all status files

repo.status.each { |file| puts "#{file.path}: #{file.type}" }

Returns:

Raises:

  • (Git::FailedError) —

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



112
113
114
 
# File 'lib/git/repository/status_operations.rb', line 112

def status
  Git::Status.new(self)
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:



84
85
86
87
88
 
# File 'lib/git/repository/status_operations.rb', line 84

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