Module: Git::Repository::Staging

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

Overview

Facade methods for staging-area operations: adding, resetting, removing, and cleaning files

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#add(paths = '.', **options) ⇒ String

Update the index with the current content found in the working tree

Returns git's stdout from the add.

Examples:

Stage all changed files

repo.add

Stage a specific file

repo.add('README.md')

Stage all changes including deletions

repo.add(all: true)

Parameters:

  • paths (String, Array<String>) (defaults to: '.') —

    a file or files to add (relative to the worktree root); defaults to '.' (all files)

  • options (Hash) —

    options for the add command

Options Hash (**options):

  • :all (Boolean, nil) — default: nil —

    add, modify, and remove index entries to match the worktree

  • :force (Boolean, nil) — default: nil —

    allow adding otherwise ignored files

Returns:

  • (String) —

    git's stdout from the add

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



55
56
57
58
 
# File 'lib/git/repository/staging.rb', line 55

def add(paths = '.', **)
  SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
  Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
end

#clean(opts = {}) ⇒ String

Remove untracked files from the working tree

Examples:

Remove untracked files

repo.clean(force: true)

Remove untracked files and directories

repo.clean(force: true, d: true)

Remove untracked and ignored files

repo.clean(force: true, x: true)

Parameters:

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

    options for the clean command

Options Hash (opts):

  • :d (Boolean, nil) — default: nil —

    recurse into untracked directories

  • :force (Boolean, Integer, nil) — default: nil —

    force the removal of untracked files; pass 2 to also remove untracked nested git repositories (alias: :f)

  • :f (Boolean, Integer, nil) — default: nil —

    alias for :force

  • :dry_run (Boolean, nil) — default: nil —

    do not actually remove anything, just show what would be done (alias: :n)

  • :n (Boolean, nil) — default: nil —

    alias for :dry_run

  • :quiet (Boolean, nil) — default: nil —

    be quiet, only report errors (alias: :q)

  • :q (Boolean, nil) — default: nil —

    alias for :quiet

  • :exclude (String, Array<String>) — default: nil —

    use the given exclude pattern in addition to the standard ignore rules (alias: :e)

  • :e (String, Array<String>) — default: nil —

    alias for :exclude

  • :x (Boolean, nil) — default: nil —

    don't use the standard ignore rules

  • :X (Boolean, nil) — default: nil —

    remove only files ignored by git

  • :pathspec (String, Array<String>) — default: nil —

    limit cleaning to files matching the given pathspec(s)

Returns:

  • (String) —

    git's stdout from the clean

Raises:

  • (ArgumentError) —

    when unsupported options are provided, or when a deprecated :ff/:force_force value is not true, false, or nil

  • (Git::FailedError) —

    when git exits with a non-zero exit status



218
219
220
221
222
 
# File 'lib/git/repository/staging.rb', line 218

def clean(opts = {})
  opts = Private.migrate_clean_legacy_options(opts)
  SharedPrivate.assert_valid_opts!(CLEAN_ALLOWED_OPTS, **opts)
  Git::Commands::Clean.new(@execution_context).call(**opts).stdout
end

#ignored_files ⇒ Array<String>

List the files in the working tree that are ignored by git

Runs git ls-files --others --ignored --exclude-standard and returns the ignored files as repository-relative paths.

Examples:

List ignored files

repo.ignored_files #=> ["coverage/index.html", "tmp/cache.db"]

No ignored files

repo.ignored_files #=> []

Returns:

  • (Array<String>) —

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

Raises:



240
241
242
243
244
 
# File 'lib/git/repository/staging.rb', line 240

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

#reset(commitish = nil, **options) ⇒ String

Reset the current HEAD to a specified state

Returns git's stdout from the reset.

Examples:

Reset the index and working tree to HEAD

repo.reset

Hard reset to a specific commit

repo.reset('HEAD~1', hard: true)

Parameters:

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

    the commit or tree-ish to reset to; defaults to HEAD when nil

  • options (Hash) —

    options for the reset command

Options Hash (**options):

  • :hard (Boolean, nil) — default: nil —

    reset the index and working tree; discards all tracked changes

Returns:

  • (String) —

    git's stdout from the reset

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



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

def reset(commitish = nil, **)
  SharedPrivate.assert_valid_opts!(RESET_ALLOWED_OPTS, **)
  Git::Commands::Reset.new(@execution_context).call(commitish, **).stdout
end

#rm(path = '.', opts = {}) ⇒ String

Remove file(s) from the working tree and the index

Examples:

Remove a single file

repo.rm('obsolete.txt', force: true)

Remove a directory recursively

repo.rm('build', r: true)

Remove from the index only, keeping the working tree copy

repo.rm('keep_me.txt', cached: true)

Parameters:

  • path (String, Array<String>) (defaults to: '.') —

    a file or files to remove (relative to the worktree root); defaults to '.' (all files)

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

    options for the rm command

Options Hash (opts):

  • :force (Boolean, nil) — default: nil —

    override the up-to-date check and remove files with local modifications (alias: :f)

  • :f (Boolean, nil) — default: nil —

    alias for :force

  • :dry_run (Boolean, nil) — default: nil —

    do not actually remove any files; only show what would be removed (alias: :n)

  • :n (Boolean, nil) — default: nil —

    alias for :dry_run

  • :r (Boolean, nil) — default: nil —

    allow recursive removal when a leading directory name is given

  • :cached (Boolean, nil) — default: nil —

    only remove from the index, keeping the working tree files

  • :ignore_unmatch (Boolean, nil) — default: nil —

    exit with a zero status even if no files matched

  • :sparse (Boolean, nil) — default: nil —

    allow updating index entries outside of the sparse-checkout cone

  • :quiet (Boolean, nil) — default: nil —

    suppress the one-line-per-file output (alias: :q)

  • :q (Boolean, nil) — default: nil —

    alias for :quiet

  • :pathspec_from_file (String) — default: nil —

    read pathspec from the given file, one pathspec element per line; pass - to read from standard input

  • :pathspec_file_nul (Boolean, nil) — default: nil —

    when used with :pathspec_from_file, separate pathspec elements with NUL instead of newlines

Returns:

  • (String) —

    git's stdout from the rm

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



155
156
157
158
 
# File 'lib/git/repository/staging.rb', line 155

def rm(path = '.', opts = {})
  SharedPrivate.assert_valid_opts!(RM_ALLOWED_OPTS, **opts)
  Git::Commands::Rm.new(@execution_context).call(*Array(path), **opts).stdout
end