|
11 | 11 | [](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) |
12 | 12 | [](https://codeclimate.com/github/ruby-git/ruby-git) |
13 | 13 |
|
| 14 | +* [Summary](#summary) |
| 15 | +* [v2.0.0 pre-release](#v200-pre-release) |
| 16 | +* [Install](#install) |
| 17 | +* [Major Objects](#major-objects) |
| 18 | +* [Specifying and Handling Timeouts](#specifying-and-handling-timeouts) |
| 19 | +* [Examples](#examples) |
| 20 | +* [Ruby version support policy](#ruby-version-support-policy) |
| 21 | +* [License](#license) |
| 22 | + |
| 23 | +## Summary |
| 24 | + |
14 | 25 | The [git gem](https://rubygems.org/gems/git) provides an API that can be used to |
15 | 26 | create, read, and manipulate Git repositories by wrapping system calls to the `git` |
16 | 27 | command line. The API can be used for working with Git in complex interactions |
@@ -90,6 +101,60 @@ Pass the `--all` option to `git log` as follows: |
90 | 101 |
|
91 | 102 | **Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`. |
92 | 103 |
|
| 104 | +## Specifying and Handling Timeouts |
| 105 | + |
| 106 | +The timeout feature was added in git gem version `2.0.0`. |
| 107 | + |
| 108 | +A timeout for git operations can be set either globally or for specific method calls |
| 109 | +that accept a `:timeout` parameter. |
| 110 | + |
| 111 | +The timeout value must be a real, non-negative `Numeric` value that specifies a |
| 112 | +number of seconds a `git` command will be given to complete before being sent a KILL |
| 113 | +signal. This library may hang if the `git` command does not terminate after receiving |
| 114 | +the KILL signal. |
| 115 | + |
| 116 | +When a command times out, a `Git::SignaledError` is raised. |
| 117 | + |
| 118 | +If the timeout value is `0` or `nil`, no timeout will be enforced. |
| 119 | + |
| 120 | +If a method accepts a `:timeout` parameter and a receives a non-nil value, it will |
| 121 | +override the global timeout value. In this context, a value of `nil` (which is |
| 122 | +usually the default) will use the global timeout value and a value of `0` will |
| 123 | +turn off timeout enforcement no matter what the global value is. |
| 124 | + |
| 125 | +To set a global timeout, use the `Git.config` object: |
| 126 | + |
| 127 | +```ruby |
| 128 | +Git.config.timeout = nil # a value of nil or 0 means no timeout is enforced |
| 129 | +Git.config.timeout = 1.5 # can be any real, non-negative Numeric interpreted as number of seconds |
| 130 | +``` |
| 131 | + |
| 132 | +The global timeout can be overridden for a specific method if the method accepts a |
| 133 | +`:timeout` parameter: |
| 134 | + |
| 135 | +```ruby |
| 136 | +repo_url = 'https://github.com/ruby-git/ruby-git.git' |
| 137 | +Git.clone(repo_url) # Use the global timeout value |
| 138 | +Git.clone(repo_url, timeout: nil) # Also uses the global timeout value |
| 139 | +Git.clone(repo_url, timeout: 0) # Do not enforce a timeout |
| 140 | +Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::SignaledError |
| 141 | +``` |
| 142 | + |
| 143 | +If the command takes too long, a `Git::SignaledError` will be raised: |
| 144 | + |
| 145 | +```ruby |
| 146 | +begin |
| 147 | + Git.clone(repo_url, timeout: 10) |
| 148 | +rescue Git::SignaledError => e |
| 149 | + result = e.result |
| 150 | + result.class #=> Git::CommandLineResult |
| 151 | + result.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)> |
| 152 | + result.git_cmd # The git command ran as an array of strings |
| 153 | + result.stdout # The command's output to stdout until it was terminated |
| 154 | + result.stderr # The command's output to stderr until it was terminated |
| 155 | +end |
| 156 | +``` |
| 157 | + |
93 | 158 | ## Examples |
94 | 159 |
|
95 | 160 | Here are a bunch of examples of how to use the Ruby/Git package. |
|
0 commit comments