Skip to content

Commit 7e99b17

Browse files
jcouballjcouball
committed
Update documentation for new timeout functionality
Signed-off-by: James Couball <jcouball@yahoo.com>
1 parent 705e983 commit 7e99b17

File tree

4 files changed

+72
-34
lines changed

4 files changed

+72
-34
lines changed

‎README.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -158,22 +158,25 @@ rescue Git::Error => e
158158

159159
The timeout feature was added in git gem version `2.0.0`.
160160

161-
A timeout for git operations can be set either globally or for specific method calls
162-
that accept a `:timeout` parameter.
161+
A timeout for git command line operations can be set either globally or for specific
162+
method calls that accept a `:timeout` parameter.
163163

164164
The timeout value must be a real, non-negative `Numeric` value that specifies a
165165
number of seconds a `git` command will be given to complete before being sent a KILL
166166
signal. This library may hang if the `git` command does not terminate after receiving
167167
the KILL signal.
168168

169-
When a command times out, a `Git::TimeoutError` is raised.
169+
When a command times out, it is killed by sending it the `SIGKILL` signal and a
170+
`Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
171+
`Git::Error`.
170172

171173
If the timeout value is `0` or `nil`, no timeout will be enforced.
172174

173-
If a method accepts a `:timeout` parameter and a receives a non-nil value, it will
174-
override the global timeout value. In this context, a value of `nil` (which is
175-
usually the default) will use the global timeout value and a value of `0` will turn
176-
off timeout enforcement for that method call no matter what the global value is.
175+
If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
176+
of this parameter will override the global timeout value. In this context, a value of
177+
`nil` (which is usually the default) will use the global timeout value and a value of
178+
`0` will turn off timeout enforcement for that method call no matter what the global
179+
value is.
177180

178181
To set a global timeout, use the `Git.config` object:
179182

@@ -193,19 +196,20 @@ Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
193196
Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::SignaledError
194197
```
195198

196-
If the command takes too long, a `Git::SignaledError` will be raised:
199+
If the command takes too long, a `Git::TimeoutError` will be raised:
197200

198201
```ruby
199202
begin
200203
Git.clone(repo_url, timeout: 10)
201204
rescue Git::TimeoutError => e
202-
result = e.result
203-
result.class #=> Git::CommandLineResult
204-
result.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
205-
result.status.timeout? #=> true
206-
result.git_cmd # The git command ran as an array of strings
207-
result.stdout # The command's output to stdout until it was terminated
208-
result.stderr # The command's output to stderr until it was terminated
205+
e.result.tap do |r|
206+
r.class #=> Git::CommandLineResult
207+
r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
208+
r.status.timeout? #=> true
209+
r.git_cmd # The git command ran as an array of strings
210+
r.stdout # The command's output to stdout until it was terminated
211+
r.stderr # The command's output to stderr until it was terminated
212+
end
209213
end
210214
```
211215

‎bin/command_line_test

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ require 'optparse'
1212
# --stderr: string to output to stderr
1313
# --exitstatus: exit status to return (default is zero)
1414
# --signal: uncaught signal to raise (default is not to signal)
15+
# --duration: number of seconds to sleep before exiting (default is zero)
1516
#
1617
# Both --stdout and --stderr can be given.
1718
#
@@ -31,7 +32,13 @@ require 'optparse'
3132
# $ bin/command_line_test --stdout="Hello, world!" --stderr="ERROR: timeout"
3233
#
3334

34-
35+
# The command line parser for this script
36+
#
37+
# @example
38+
# parser = CommandLineParser.new
39+
# options = parser.parse(['--exitstatus', '1', '--stderr', 'ERROR: timeout', '--duration', '5'])
40+
#
41+
# @api private
3542
class CommandLineParser
3643
def initialize
3744
@option_parser = OptionParser.new

‎lib/git/command_line.rb

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,6 @@ def initialize(env, binary_path, global_opts, logger)
114114
# the normalize option will be ignored.
115115
#
116116
# @example Run a command and return the output
117-
#
118117
# cli.run('version') #=> "git version 2.39.1\n"
119118
#
120119
# @example The args array should be splatted into the parameter list
@@ -162,14 +161,18 @@ def initialize(env, binary_path, global_opts, logger)
162161
# `stderr_writer.string` will be merged into the output returned by this method.
163162
#
164163
# @param normalize [Boolean] whether to normalize the output to a valid encoding
164+
#
165165
# @param chomp [Boolean] whether to chomp the output
166+
#
166167
# @param merge [Boolean] whether to merge stdout and stderr in the string returned
168+
#
167169
# @param chdir [String] the directory to run the command in
168170
#
169171
# @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
170172
#
171-
# If timeout is zero or nil, the command will not time out. If the command
172-
# times out, it is killed via a SIGKILL signal and `Git::TimeoutError` is raised.
173+
# If timeout is zero, the timeout will not be enforced.
174+
#
175+
# If the command times out, it is killed via a `SIGKILL` signal and `Git::TimeoutError` is raised.
173176
#
174177
# If the command does not respond to SIGKILL, it will hang this method.
175178
#
@@ -178,9 +181,13 @@ def initialize(env, binary_path, global_opts, logger)
178181
# This result of running the command.
179182
#
180183
# @raise [ArgumentError] if `args` is not an array of strings
184+
#
181185
# @raise [Git::SignaledError] if the command was terminated because of an uncaught signal
186+
#
182187
# @raise [Git::FailedError] if the command returned a non-zero exitstatus
188+
#
183189
# @raise [Git::GitExecuteError] if an exception was raised while collecting subprocess output
190+
#
184191
# @raise [Git::TimeoutError] if the command times out
185192
#
186193
def run(*args, out:, err:, normalize:, chomp:, merge:, chdir: nil, timeout: nil)
@@ -267,7 +274,7 @@ def raise_pipe_error(git_cmd, pipe_name, pipe)
267274
#
268275
# @param cmd [Array<String>] the git command to execute
269276
# @param chdir [String] the directory to run the command in
270-
# @param timeout [Float, Integer, nil] the maximum seconds to wait for the command to complete
277+
# @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
271278
#
272279
# If timeout is zero of nil, the command will not time out. If the command
273280
# times out, it is killed via a SIGKILL signal and `Git::TimeoutError` is raised.
@@ -321,6 +328,7 @@ def writers(out, err)
321328
# @param err [#write] the object that stderr was written to
322329
# @param normalize [Boolean] whether to normalize the output of each writer
323330
# @param chomp [Boolean] whether to chomp the output of each writer
331+
# @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
324332
#
325333
# @return [Git::CommandLineResult] the result of the command to return to the caller
326334
#
@@ -346,7 +354,7 @@ def process_result(git_cmd, status, out, err, normalize, chomp, timeout)
346354
# @param out [#write] the object to write stdout to
347355
# @param err [#write] the object to write stderr to
348356
# @param chdir [String] the directory to run the command in
349-
# @param timeout [Float, Integer, nil] the maximum seconds to wait for the command to complete
357+
# @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
350358
#
351359
# If timeout is zero of nil, the command will not time out. If the command
352360
# times out, it is killed via a SIGKILL signal and `Git::TimeoutError` is raised.

‎lib/git/lib.rb

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -80,22 +80,34 @@ def init(opts={})
8080
command('init', *arr_opts)
8181
end
8282

83-
# tries to clone the given repo
83+
# Clones a repository into a newly created directory
8484
#
85-
# accepts options:
86-
# :bare:: no working directory
87-
# :branch:: name of branch to track (rather than 'master')
88-
# :depth:: the number of commits back to pull
89-
# :filter:: specify partial clone
90-
# :origin:: name of remote (same as remote)
91-
# :path:: directory where the repo will be cloned
92-
# :remote:: name of remote (rather than 'origin')
93-
# :recursive:: after the clone is created, initialize all submodules within, using their default settings.
85+
# @param [String] repository_url the URL of the repository to clone
86+
# @param [String, nil] directory the directory to clone into
87+
#
88+
# If nil, the repository is cloned into a directory with the same name as
89+
# the repository.
90+
#
91+
# @param [Hash] opts the options for this command
9492
#
95-
# TODO - make this work with SSH password or auth_key
93+
# @option opts [Boolean] :bare (false) if true, clone as a bare repository
94+
# @option opts [String] :branch the branch to checkout
95+
# @option opts [String, Array] :config one or more configuration options to set
96+
# @option opts [Integer] :depth the number of commits back to pull
97+
# @option opts [String] :filter specify partial clone
98+
# @option opts [String] :mirror set up a mirror of the source repository
99+
# @option opts [String] :origin the name of the remote
100+
# @option opts [String] :path an optional prefix for the directory parameter
101+
# @option opts [String] :remote the name of the remote
102+
# @option opts [Boolean] :recursive after the clone is created, initialize all submodules within, using their default settings
103+
# @option opts [Numeric, nil] :timeout the number of seconds to wait for the command to complete
104+
#
105+
# See {Git::Lib#command} for more information about :timeout
96106
#
97107
# @return [Hash] the options to pass to {Git::Base.new}
98108
#
109+
# @todo make this work with SSH password or auth_key
110+
#
99111
def clone(repository_url, directory, opts = {})
100112
@path = opts[:path] || '.'
101113
clone_dir = opts[:path] ? File.join(@path, directory) : directory
@@ -1215,8 +1227,15 @@ def command_line
12151227
#
12161228
# @param chdir [String, nil] the directory to run the command in
12171229
#
1218-
# @param timeout [Numeric, nil] the maximum time to wait for the command to
1219-
# complete
1230+
# @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
1231+
#
1232+
# If timeout is nil, the global timeout from {Git::Config} is used.
1233+
#
1234+
# If timeout is zero, the timeout will not be enforced.
1235+
#
1236+
# If the command times out, it is killed via a `SIGKILL` signal and `Git::TimeoutError` is raised.
1237+
#
1238+
# If the command does not respond to SIGKILL, it will hang this method.
12201239
#
12211240
# @see Git::CommandLine#run
12221241
#

0 commit comments

Comments
 (0)