Module: Git::Repository::Staging

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

Overview

Facade methods for staging-area operations: adding, resetting, moving, 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



59
60
61
62
 
# File 'lib/git/repository/staging.rb', line 59

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

#apply(file) ⇒ String?

Apply a patch file to the working tree

Reads the unified diff in file and applies it to the working tree via git apply. If file does not exist, the method returns nil without calling git — preserving the 4.x Git::Base#apply no-op contract.

Examples:

Apply a patch to the working tree

repo.apply('fix.patch')

Parameters:

  • file (String) —

    path to the patch file to apply

Returns:

  • (String) —

    git's stdout (usually empty on success)

  • (nil) —

    when file does not exist

Raises:



141
142
143
144
145
 
# File 'lib/git/repository/staging.rb', line 141

def apply(file)
  return unless File.exist?(file)

  Git::Commands::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).stdout
end

#apply_mail(file) ⇒ String?

Apply a series of patches from a mailbox file to the current branch

Reads the mbox-format file in file and applies the patches via git am. If file does not exist, the method returns nil without calling git — preserving the 4.x Git::Base#apply_mail no-op contract.

Examples:

Apply patches from a mailbox

repo.apply_mail('patches.mbox')

Parameters:

  • file (String) —

    path to the mbox patch file to apply

Returns:

  • (String) —

    git's stdout (usually empty on success)

  • (nil) —

    when file does not exist

Raises:



164
165
166
167
168
 
# File 'lib/git/repository/staging.rb', line 164

def apply_mail(file)
  return unless File.exist?(file)

  Git::Commands::Am::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).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



382
383
384
385
386
 
# File 'lib/git/repository/staging.rb', line 382

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:



404
405
406
407
408
 
# File 'lib/git/repository/staging.rb', line 404

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

#mv(source, destination, options = {}) ⇒ String

Move or rename a file, directory, or symlink in the working tree

Updates the index after successful completion, but the change must still be committed.

Examples:

Move a single file

repo.mv('old.rb', 'new.rb')

Move multiple files to a directory

repo.mv(['file1.rb', 'file2.rb'], 'destination_dir/')

Force overwrite if destination exists

repo.mv('source.rb', 'dest.rb', force: true)

Parameters:

  • source (String, Array<String>) —

    one or more source file(s), directory(ies), or symlink(s) to move (relative to the worktree root)

  • destination (String) —

    the destination file or directory

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

    options for the mv command

Options Hash (options):

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

    force renaming or moving even if the destination exists (alias: :f)

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

    alias for :force

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

    do not actually move any files; only show what would happen (alias: :n)

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

    alias for :dry_run

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

    skip move or rename actions which would lead to an error

Returns:

  • (String) —

    git's stdout from the mv command

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



319
320
321
322
 
# File 'lib/git/repository/staging.rb', line 319

def mv(source, destination, options = {})
  SharedPrivate.assert_valid_opts!(MV_ALLOWED_OPTS, **options)
  Git::Commands::Mv.new(@execution_context).call(*Array(source), destination, verbose: true, **options).stdout
end

#read_tree(treeish, opts = {}) ⇒ String

Read tree information into the index

Reads the named tree object into the index. This is a low-level plumbing operation used to stage the contents of a tree without updating the working tree. Typically called before Branching#checkout_index or as part of custom merge flows.

Examples:

Read HEAD into the index

repo.read_tree('HEAD')

Read a tree under a prefix directory

repo.read_tree('HEAD', { prefix: 'subdir/' })

Parameters:

  • treeish (String) —

    the tree-ish to read into the index

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

    options for the read-tree command

Options Hash (opts):

  • :prefix (String) — default: nil —

    keep the current index contents and read the named tree-ish under the directory at the given prefix (--prefix=<prefix>)

Returns:

  • (String) —

    git's stdout (usually empty on success)

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



201
202
203
204
 
# File 'lib/git/repository/staging.rb', line 201

def read_tree(treeish, opts = {})
  SharedPrivate.assert_valid_opts!(READ_TREE_ALLOWED_OPTS, **opts)
  Git::Commands::ReadTree.new(@execution_context).call(treeish, **opts).stdout
end

#reset(commitish = nil, opts = {}) ⇒ String

Reset the current HEAD to a specified state

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

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

    options for the reset command

Options Hash (opts):

  • :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



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

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

#reset_hard(commitish = nil, opts = {}) ⇒ String

Deprecated.

Use #reset with hard: true instead.

@example Hard reset to HEAD repo.reset_hard

@example Hard reset to a specific commit repo.reset_hard('HEAD~1')

Reset the current HEAD to a specified state with --hard

Parameters:

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

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

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

    options passed through to #reset

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



116
117
118
119
120
121
122
 
# File 'lib/git/repository/staging.rb', line 116

def reset_hard(commitish = nil, opts = {})
  Git::Deprecation.warn(
    'Git::Repository::Staging#reset_hard is deprecated and will be removed in a future version. ' \
    'Use #reset(commitish, hard: true) instead.'
  )
  reset(commitish, **opts, hard: true)
end

#rm(path = '.', opts = {}) ⇒ String Also known as: remove

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



268
269
270
271
 
# File 'lib/git/repository/staging.rb', line 268

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