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::Base) —

    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.



51
52
53
54
55
56
 
# File 'lib/git/log.rb', line 51

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

Instance Method Details

#[](index)

Deprecated.

Use #execute and call the method on the result.



142
143
144
145
146
147
148
 
# File 'lib/git/log.rb', line 142

def [](index)
  Git::Deprecation.warn(
    'Calling Git::Log#[] is deprecated. Call #execute and then #[] on the result object.'
  )
  run_log_if_dirty
  @commits&.[](index)
end

#all 



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

def all                 = set_option(:all, true)

#author(regex) 



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

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

#between(val1, val2 = nil) 



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

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

#cherry 



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

def cherry              = set_option(:cherry, true)

#each

Deprecated.

Use #execute and call each on the result.



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

def each(&)
  Git::Deprecation.warn(
    'Calling Git::Log#each is deprecated. 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:



89
90
91
92
 
# File 'lib/git/log.rb', line 89

def execute
  run_log_if_dirty
  Result.new(@commits)
end

#first

Deprecated.

Use #execute and call the method on the result.



124
125
126
127
128
129
130
 
# File 'lib/git/log.rb', line 124

def first
  Git::Deprecation.warn(
    'Calling Git::Log#first is deprecated. Call #execute and then #first on the result object.'
  )
  run_log_if_dirty
  @commits&.first
end

#grep(regex) 



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

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

#last

Deprecated.

Use #execute and call the method on the result.



133
134
135
136
137
138
139
 
# File 'lib/git/log.rb', line 133

def last
  Git::Deprecation.warn(
    'Calling Git::Log#last is deprecated. Call #execute and then #last on the result object.'
  )
  run_log_if_dirty
  @commits&.last
end

#max_count(num)

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



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

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

#merges 



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

def merges              = set_option(:merges, true)

#object(objectish) 



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

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

#path(path) 



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

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

#since(date) 



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

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

#size

Deprecated.

Use #execute and call size on the result.



106
107
108
109
110
111
112
 
# File 'lib/git/log.rb', line 106

def size
  Git::Deprecation.warn(
    'Calling Git::Log#size is deprecated. Call #execute and then #size on the result object.'
  )
  run_log_if_dirty
  @commits&.size
end

#skip(num) 



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

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

#to_s

Deprecated.

Use #execute and call to_s on the result.



115
116
117
118
119
120
121
 
# File 'lib/git/log.rb', line 115

def to_s
  Git::Deprecation.warn(
    'Calling Git::Log#to_s is deprecated. Call #execute and then #to_s on the result object.'
  )
  run_log_if_dirty
  @commits&.map(&:to_s)&.join("\n")
end

#until(date) 



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

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