Module: Git::Repository::Committing

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

Overview

Facade methods for committing operations: recording commits, manipulating tree objects, and building commit objects outside the working tree

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#commit(message, opts = {}) ⇒ String

Record staged changes as a new commit

Examples:

Commit with a message

repo.commit('Add README')

Amend the previous commit, reusing its message

repo.commit(nil, amend: true)

Stage all modified files and commit

repo.commit('Cleanup', all: true)

Parameters:

  • message (String, nil) —

    the commit message; pass nil to omit (e.g. when using :amend to reuse the previous message)

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

    options for the commit command

Options Hash (opts):

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

    automatically stage modified and deleted files before committing

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

    replace the tip of the current branch with a new commit

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

    allow committing with no changes

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

    allow committing with an empty message

  • :author (String) — default: nil —

    override the commit author in A U Thor <author@example.com> format

  • :date (String) — default: nil —

    override the author date

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

    GPG-sign the commit

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

    disable GPG signing

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

    bypass the pre-commit and commit-msg hooks

Returns:

  • (String) —

    git's stdout from the commit

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/git/repository/committing.rb', line 75

def commit(message, opts = {})
  opts = opts.dup
  if opts.key?(:add_all)
    Git::Deprecation.warn('The :add_all option for #commit is deprecated, use :all instead')
    opts[:all] = opts.delete(:add_all)
  end

  SharedPrivate.assert_valid_opts!(COMMIT_ALLOWED_OPTS, **opts)

  call_opts = { no_edit: true }
  call_opts[:message] = message if message

  Git::Commands::Commit.new(@execution_context).call(**call_opts, **opts).stdout
end

#commit_all(message, opts = {}) ⇒ String

Commit all modified tracked files without explicitly staging them first

Equivalent to calling #commit with all: true merged into opts.

Examples:

Commit all changes with a message

repo.commit_all('Update everything')

Parameters:

  • message (String) —

    the commit message

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

    additional options forwarded to #commit

Returns:

  • (String) —

    git's stdout from the commit

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



107
108
109
 
# File 'lib/git/repository/committing.rb', line 107

def commit_all(message, opts = {})
  commit(message, opts.merge(all: true))
end

#commit_tree(tree = nil, opts = {}) ⇒ String

Create a commit object from a tree SHA without moving HEAD

Unlike #commit, this does not read the index; it directly wraps git commit-tree.

Examples:

Commit a tree with a parent

repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')

Parameters:

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

    the tree SHA to commit; defaults to nil

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

    options for the commit-tree command

Options Hash (opts):

  • :m (String) — default: nil —

    the commit message (short form)

  • :message (String) — default: nil —

    the commit message (normalized to :m before passing to the command)

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

    parent commit SHA(s)

  • :parent (String) — default: nil —

    a single parent commit SHA (normalized to :p)

  • :parents (Array<String>) — default: nil —

    multiple parent commit SHAs (normalized to :p)

Returns:

  • (String) —

    the SHA of the newly created commit object

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



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

def commit_tree(tree = nil, opts = {}) # rubocop:disable Metrics/AbcSize
  SharedPrivate.assert_valid_opts!(COMMIT_TREE_ALLOWED_OPTS, **opts)

  opts = opts.dup
  opts[:p] = opts.delete(:parents) if opts.key?(:parents)
  opts[:p] = opts.delete(:parent) if opts.key?(:parent)
  opts[:m] = opts.delete(:message) if opts.key?(:message)
  opts[:m] = "commit tree #{tree}" unless opts[:m]

  Git::Commands::CommitTree.new(@execution_context).call(tree, **opts).stdout
end

#write_and_commit_tree(opts = {}) ⇒ String

Write the current index to a tree object and immediately commit it

Combines #write_tree and #commit_tree in a single call.

Examples:

Commit the current index as a snapshot

commit_sha = repo.write_and_commit_tree(message: 'snapshot')

Parameters:

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

    options forwarded to #commit_tree

Returns:

  • (String) —

    the SHA of the newly created commit object

Raises:

  • (ArgumentError) —

    when unsupported options are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



182
183
184
 
# File 'lib/git/repository/committing.rb', line 182

def write_and_commit_tree(opts = {})
  commit_tree(write_tree, opts)
end

#write_tree ⇒ String

Write the current index to a tree object in the object store

Examples:

Get the tree SHA of the current index

tree_sha = repo.write_tree

Returns:

  • (String) —

    the SHA of the tree object written

Raises:



163
164
165
 
# File 'lib/git/repository/committing.rb', line 163

def write_tree
  Git::Commands::WriteTree.new(@execution_context).call.stdout
end