Class: Git::Log

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/git/log.rb

Overview

Builds and executes a git log query

This class provides a fluent interface for building complex git log queries.

Queries default to returning 30 commits; call #max_count with :all to return every matching commit. Calling #all adds the --all flag to include all refs in the search but does not change the number of commits returned.

The query is lazily executed when results are requested either via the modern #execute method or the deprecated Enumerable methods.

Examples:

Using the modern execute API

log = git.log.max_count(50).between('v1.0', 'v1.1').author('Scott')
results = log.execute
puts "Found #{results.size} commits."
results.each { |commit| puts commit.sha }

Defined Under Namespace

Classes: Result

Deprecated Enumerable Interface collapse

Instance Method Summary collapse

Constructor Details

#initialize(base, max_count = 30) ⇒ Log

Create a new Git::Log object

Examples:

git = Git.open('.')
Git::Log.new(git)

Parameters:

  • base (Git::Repository) —

    the git repository object

  • max_count (Integer, Symbol, nil) (defaults to: 30) —

    the number of commits to return, or :all or nil to return all

    Passing max_count to #initialize is equivalent to calling #max_count on the object.



96
97
98
99
100
101
 
# File 'lib/git/log.rb', line 96

def initialize(base, max_count = 30)
  @base = base
  @options = {}
  @dirty = true
  self.max_count(max_count)
end

Instance Method Details

#[](index) ⇒ Git::Object::Commit, ...

Deprecated.

Use #execute and call the method on the result.

Returns the selected commit or commits.

Parameters:

  • index (Integer, Range) —

    the commit index or range to retrieve

Returns:



298
299
300
301
302
303
304
305
 
# File 'lib/git/log.rb', line 298

def [](index)
  Git::Deprecation.warn(
    'Calling Git::Log#[] is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #[] on the result object.'
  )
  run_log_if_dirty
  @commits[index]
end

#all ⇒ Git::Log

Includes commits reachable from all refs

Returns:

  • (Git::Log) —

    the current query builder



119
 
# File 'lib/git/log.rb', line 119

def all                 = set_option(:all, true)

#author(regex) ⇒ Git::Log

Filters commits by author pattern

Parameters:

  • regex (String) —

    a pattern matched against author names

Returns:

  • (Git::Log) —

    the current query builder



135
 
# File 'lib/git/log.rb', line 135

def author(regex)       = set_option(:author, regex)

#between(val1, val2 = nil) ⇒ Git::Log

Limits commits to the given revision range

Parameters:

  • val1 (String) —

    the first revision

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

    the second revision; when nil, validation fails at execution time

Returns:

  • (Git::Log) —

    the current query builder



205
 
# File 'lib/git/log.rb', line 205

def between(val1, val2 = nil) = set_option(:between, [val1, val2])

#cherry ⇒ Git::Log

Omits commits equivalent to cherry-picked commits

Returns:

  • (Git::Log) —

    the current query builder



211
 
# File 'lib/git/log.rb', line 211

def cherry              = set_option(:cherry, true)

#each

Deprecated.

Use #execute and call each on the result.



242
243
244
245
246
247
248
249
 
# File 'lib/git/log.rb', line 242

def each(&)
  Git::Deprecation.warn(
    'Calling Git::Log#each is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #each on the result object.'
  )
  run_log_if_dirty
  @commits.each(&)
end

#execute ⇒ Git::Log::Result

Executes the git log command and returns an immutable result object

This is the preferred way to get log data. It separates the query building from the execution, making the API more predictable.

Examples:

query = g.log.since('2 weeks ago').author('Scott')
results = query.execute
puts "Found #{results.size} commits"
results.each do |commit|
  # ...
end

Returns:



234
235
236
237
 
# File 'lib/git/log.rb', line 234

def execute
  run_log_if_dirty
  Result.new(@commits)
end

#first

Deprecated.

Use #execute and call the method on the result.



272
273
274
275
276
277
278
279
 
# File 'lib/git/log.rb', line 272

def first
  Git::Deprecation.warn(
    'Calling Git::Log#first is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #first on the result object.'
  )
  run_log_if_dirty
  @commits.first
end

#grep(regex) ⇒ Git::Log

Filters commits by commit message pattern

Parameters:

  • regex (String) —

    a pattern matched against commit messages

Returns:

  • (Git::Log) —

    the current query builder



143
 
# File 'lib/git/log.rb', line 143

def grep(regex)         = set_option(:grep, regex)

#last

Deprecated.

Use #execute and call the method on the result.



282
283
284
285
286
287
288
289
 
# File 'lib/git/log.rb', line 282

def last
  Git::Deprecation.warn(
    'Calling Git::Log#last is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #last on the result object.'
  )
  run_log_if_dirty
  @commits.last
end

#max_count(num) ⇒ Git::Log

Set query options using a fluent interface. Each method returns self to allow for chaining.

Sets the maximum number of commits to return

Parameters:

  • num (Integer, Symbol, nil) —

    the maximum commit count, or :all / nil for no limit

Returns:

  • (Git::Log) —

    the current query builder



113
 
# File 'lib/git/log.rb', line 113

def max_count(num)      = set_option(:count, num == :all ? nil : num)

#merges ⇒ Git::Log

Includes only merge commits

Returns:

  • (Git::Log) —

    the current query builder



217
 
# File 'lib/git/log.rb', line 217

def merges              = set_option(:merges, true)

#object(objectish) ⇒ Git::Log

Sets the revision range expression for the log query

Parameters:

  • objectish (String) —

    a git revision expression to pass to git log

Returns:

  • (Git::Log) —

    the current query builder



127
 
# File 'lib/git/log.rb', line 127

def object(objectish)   = set_option(:object, objectish)

#path(path) ⇒ Git::Log

Limits commits to those that touch the given path or paths

Parameters:

  • path (String, Pathname, Array<String, Pathname>) —

    path limiter input

Returns:

  • (Git::Log) —

    the current query builder



170
 
# File 'lib/git/log.rb', line 170

def path(path)          = set_option(:path_limiter, path)

#perl_regexp ⇒ Git::Log

Note:

On Git for Windows, git's default regex engine matches bytes rather than characters, so a metacharacter such as . or a POSIX class such as [[:alpha:]] never matches a whole multi-byte character. The match fails silently: git exits zero and the result is empty. PCRE does match characters on that platform, but it is a different dialect than git's default, so selecting it is a deliberate choice by the caller.

Interprets #grep and #author patterns as Perl-compatible regular expressions

Selects PCRE instead of git's default POSIX basic regular expressions for every pattern in the query. Requires a git built with PCRE support.

Examples:

Match a metacharacter against a non-ASCII character on Git for Windows

repo.log.perl_regexp.grep('^.PFEL').execute

Returns:

  • (Git::Log) —

    the current query builder



162
 
# File 'lib/git/log.rb', line 162

def perl_regexp         = set_option(:perl_regexp, true)

#since(date) ⇒ Git::Log

Includes only commits newer than the given date expression

Parameters:

  • date (String) —

    a git-compatible date expression

Returns:

  • (Git::Log) —

    the current query builder



186
 
# File 'lib/git/log.rb', line 186

def since(date)         = set_option(:since, date)

#size

Deprecated.

Use #execute and call size on the result.



252
253
254
255
256
257
258
259
 
# File 'lib/git/log.rb', line 252

def size
  Git::Deprecation.warn(
    'Calling Git::Log#size is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #size on the result object.'
  )
  run_log_if_dirty
  @commits.size
end

#skip(num) ⇒ Git::Log

Skips a number of commits before returning results

Parameters:

  • num (Integer) —

    the number of commits to skip

Returns:

  • (Git::Log) —

    the current query builder



178
 
# File 'lib/git/log.rb', line 178

def skip(num)           = set_option(:skip, num)

#to_s

Deprecated.

Use #execute and call to_s on the result.



262
263
264
265
266
267
268
269
 
# File 'lib/git/log.rb', line 262

def to_s
  Git::Deprecation.warn(
    'Calling Git::Log#to_s is deprecated and will be removed in v6.0.0. ' \
    'Call #execute and then #to_s on the result object.'
  )
  run_log_if_dirty
  @commits.join("\n")
end

#until(date) ⇒ Git::Log

Includes only commits older than the given date expression

Parameters:

  • date (String) —

    a git-compatible date expression

Returns:

  • (Git::Log) —

    the current query builder



194
 
# File 'lib/git/log.rb', line 194

def until(date)         = set_option(:until, date)