Module: Git::Repository::Staging Private

Included in:: Git::Repository

Defined in:: lib/git/repository/staging.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 staging-area operations: adding, resetting, moving, removing, and cleaning files

Included by Git::Repository.

Instance Method Summary collapse

#add(paths = '.', **options) ⇒ String private
Update the index with the current content found in the working tree.
#apply(file) ⇒ String^? private
Apply a patch file to the working tree.
#apply_mail(file) ⇒ String^? private
Apply a series of patches from a mailbox file to the current branch.
#clean(opts = {}) ⇒ String private
Remove untracked files from the working tree.
#ignored_files ⇒ Array<String> private
List the files in the working tree that are ignored by git.
#mv(source, destination, options = {}) ⇒ String private
Move or rename a file, directory, or symlink in the working tree.
#read_tree(treeish, opts = {}) ⇒ String private
Read tree information into the index.
#reset(commitish = nil, opts = {}) ⇒ String private
Reset the current HEAD to a specified state.
#reset_hard(commitish = nil, opts = {}) ⇒ String deprecated private Deprecated.
Use #reset with hard: true instead
#rm(path = '.', opts = {}) ⇒ String (also: #remove) private
Remove file(s) from the working tree and the index.

Instance Method Details

#add(paths = '.', **options) ⇒ `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.

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

# 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`^?

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.

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:

(Git::FailedError) —
when git exits with a non-zero exit status

# File 'lib/git/repository/staging.rb', line 144

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`^?

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.

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:

(Git::FailedError) —
when git exits with a non-zero exit status

# File 'lib/git/repository/staging.rb', line 167

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`

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.

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

# File 'lib/git/repository/staging.rb', line 385

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>`

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

(Git::FailedError) —
when git exits with a non-zero exit status

# File 'lib/git/repository/staging.rb', line 407

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`

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.

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

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

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`

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.

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

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

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`

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.

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

# 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`

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 #reset with hard: true instead

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

Examples:

Hard reset to HEAD

repo.reset_hard

Hard reset to a specific commit

repo.reset_hard('HEAD~1')

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

Options Hash (opts):

:hard (Boolean, nil) — default: nil —
ignored; this method always forces hard: true

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

# File 'lib/git/repository/staging.rb', line 119

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

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.

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

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

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

Module: Git::Repository::Staging Private

Overview

Instance Method Summary collapse

Instance Method Details

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

Examples:

Stage all changed files

Stage a specific file

Stage all changes including deletions

#apply(file) ⇒ String?

Examples:

Apply a patch to the working tree

#apply_mail(file) ⇒ String?

Examples:

Apply patches from a mailbox

#clean(opts = {}) ⇒ String

Examples:

Remove untracked files

Remove untracked files and directories

Remove untracked and ignored files

#ignored_files ⇒ Array<String>

Examples:

List ignored files

No ignored files

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

Examples:

Move a single file

Move multiple files to a directory

Force overwrite if destination exists

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

Examples:

Read HEAD into the index

Read a tree under a prefix directory

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

Examples:

Reset the index and working tree to HEAD

Hard reset to a specific commit

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

Examples:

Hard reset to HEAD

Hard reset to a specific commit

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

Examples:

Remove a single file

Remove a directory recursively

Remove from the index only, keeping the working tree copy

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

#apply(file) ⇒ `String`^?

#apply_mail(file) ⇒ `String`^?

#clean(opts = {}) ⇒ `String`

#ignored_files ⇒ `Array<String>`

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

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

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

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

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