Module: Git::Repository::StatusOperations

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

Overview

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

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

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:



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

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

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

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



91
92
93
 
# File 'lib/git/repository/status_operations.rb', line 91

def status
  Git::Status.new(self)
end

#untracked_files ⇒ Array<String>

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:



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

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