README.md in git-2.0.0.pre3 vs README.md in git-2.1.0
- old
+ new
@@ -10,56 +10,54 @@
[](https://rubydoc.info/gems/git/file/CHANGELOG.md)
[](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
[](https://codeclimate.com/github/ruby-git/ruby-git)
* [Summary](#summary)
-* [v2.0.0 pre-release](#v200-pre-release)
+* [v2.x Release](#v2x-release)
* [Install](#install)
* [Major Objects](#major-objects)
* [Errors Raised By This Gem](#errors-raised-by-this-gem)
* [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
* [Examples](#examples)
* [Ruby version support policy](#ruby-version-support-policy)
* [License](#license)
## Summary
-The [git gem](https://rubygems.org/gems/git) provides an API that can be used to
-create, read, and manipulate Git repositories by wrapping system calls to the `git`
-command line. The API can be used for working with Git in complex interactions
-including branching and merging, object inspection and manipulation, history, patch
-generation and more.
+The [git gem](https://rubygems.org/gems/git) provides a Ruby interface to the `git`
+command line.
Get started by obtaining a repository object by:
* opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
* initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
* cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
-## v2.0.0 pre-release
+## v2.x Release
-git 2.0.0 is available as a pre-release version for testing! Please give it a try.
+git 2.0.0 has recently been released. Please give it a try.
+**If you have problems with the 2.x release, open an issue and use the 1.x version
+instead.** We will do our best to fix your issues in a timely fashion.
+
**JRuby on Windows is not yet supported by the 2.x release line. Users running JRuby
on Windows should continue to use the 1.x release line.**
-The changes coming in this major release include:
+The changes in this major release include:
+* Added a dependency on the activesupport gem to use the deprecation functionality
* Create a policy of supported Ruby versions to support only non-EOL Ruby versions
* Create a policy of supported Git CLI versions (released 2020-12-25)
* Update the required Ruby version to at least 3.0 (released 2020-07-27)
* Update the required Git command line version to at least 2.28
* Update how CLI commands are called to use the [process_executer](https://github.com/main-branch/process_executer)
gem which is built on top of [Kernel.spawn](https://ruby-doc.org/3.3.0/Kernel.html#method-i-spawn).
See [PR #684](https://github.com/ruby-git/ruby-git/pull/684) for more details
on the motivation for this implementation.
-The tentative plan is to release `2.0.0` near the end of March 2024 depending on
-the feedback received during the pre-release period.
-
The `master` branch will be used for `2.x` development. If needed, fixes for `1.x`
version will be done on the `v1` branch.
## Install
@@ -67,16 +65,28 @@
```shell
bundle add git
```
+to install version 1.x:
+
+```shell
+bundle add git --version "~> 1.19"
+```
+
If bundler is not being used to manage dependencies, install the gem by executing:
```shell
gem install git
```
+to install version 1.x:
+
+```shell
+gem install git --version "~> 1.19"
+```
+
## Major Objects
**Git::Base** - The object returned from a `Git.open` or `Git.clone`. Most major actions are called from this object.
**Git::Object** - The base object for your tree, blob and commit objects, returned from `@git.gtree` or `@git.object` calls. the `Git::AbstractObject` will have most of the calls in common for all those objects.
@@ -89,93 +99,74 @@
**Git::Branches** - Enumerable object that holds `Git::Branch objects`. You can call .local or .remote on it to filter to just your local or remote branches.
**Git::Remote**- A reference to a remote repository that is tracked by this repository.
-**Git::Log** - An Enumerable object that references all the `Git::Object::Commit` objects that encompass your log query, which can be constructed through methods on the `Git::Log object`,
-like:
+**Git::Log** - An Enumerable object that references all the `Git::Object::Commit`
+objects that encompass your log query, which can be constructed through methods on
+the `Git::Log object`, like:
- `@git.log(20).object("some_file").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }`
+```ruby
+git.log
+ .max_count(:all)
+ .object('README.md')
+ .since('10 years ago')
+ .between('v1.0.7', 'HEAD')
+ .map { |commit| commit.sha }
+```
-Pass the `--all` option to `git log` as follows:
+A maximum of 30 commits are returned if `max_count` is not called. To get all commits
+that match the log query, call `max_count(:all)`.
- `@git.log.all.each { |commit| [block] }`
+Note that `git.log.all` adds the `--all` option to the underlying `git log` command.
+This asks for the logs of all refs (basically all commits reachable by HEAD,
+branches, and tags). This does not control the maximum number of commits returned. To
+control how many commits are returned, you should call `max_count`.
- **Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
+**Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
## Errors Raised By This Gem
-This gem raises custom errors that derive from `Git::Error`. These errors are
-arranged in the following class heirarchy:
+The git gem will only raise an `ArgumentError` or an error that is a subclass of
+`Git::Error`. It does not explicitly raise any other types of errors.
-Error heirarchy:
+It is recommended to rescue `Git::Error` to catch any runtime error raised by
+this gem unless you need more specific error handling.
-```text
-Error
-└── CommandLineError
- ├── FailedError
- └── SignaledError
- └── TimeoutError
-```
-
-Other standard errors may also be raised like `ArgumentError`. Each method should
-document the errors it may raise.
-
-Description of each Error class:
-
-* `Error`: This catch-all error serves as the base class for other custom errors in this
- gem. Errors of this class are raised when no more approriate specific error to
- raise.
-* `CommandLineError`: This error is raised when there's a problem executing the git
- command line. This gem will raise a more specific error depending on how the
- command line failed.
-* `FailedError`: This error is raised when the git command line exits with a non-zero
- status code that is not expected by the git gem.
-* `SignaledError`: This error is raised when the git command line is terminated as a
- result of receiving a signal. This could happen if the process is forcibly
- terminated or if there is a serious system error.
-* `TimeoutError`: This is a specific type of `SignaledError` that is raised when the
- git command line operation times out and is killed via the SIGKILL signal. This
- happens if the operation takes longer than the timeout duration configured in
- `Git.config.timeout` or via the `:timeout` parameter given in git methods that
- support this parameter.
-
-`Git::GitExecuteError` remains as an alias for `Git::Error`. It is considered
-deprecated as of git-2.0.0.
-
-Here is an example of catching errors when using the git gem:
-
```ruby
begin
- timeout_duration = 0.001 # seconds
- repo = Git.clone('https://github.com/ruby-git/ruby-git', 'ruby-git-temp', timeout: timeout_duration)
-rescue Git::TimeoutError => e # Catch the more specific error first!
- puts "Git clone took too long and timed out #{e}"
+ # some git operation
rescue Git::Error => e
- puts "Received the following error: #{e}"
+ puts "An error occurred: #{e.message}"
+end
```
+See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
+
## Specifying And Handling Timeouts
The timeout feature was added in git gem version `2.0.0`.
-A timeout for git operations can be set either globally or for specific method calls
-that accept a `:timeout` parameter.
+A timeout for git command line operations can be set either globally or for specific
+method calls that accept a `:timeout` parameter.
The timeout value must be a real, non-negative `Numeric` value that specifies a
number of seconds a `git` command will be given to complete before being sent a KILL
signal. This library may hang if the `git` command does not terminate after receiving
the KILL signal.
-When a command times out, a `Git::TimeoutError` is raised.
+When a command times out, it is killed by sending it the `SIGKILL` signal and a
+`Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
+`Git::Error`.
If the timeout value is `0` or `nil`, no timeout will be enforced.
-If a method accepts a `:timeout` parameter and a receives a non-nil value, it will
-override the global timeout value. In this context, a value of `nil` (which is
-usually the default) will use the global timeout value and a value of `0` will turn
-off timeout enforcement for that method call no matter what the global value is.
+If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
+of this parameter will override the global timeout value. In this context, a value of
+`nil` (which is usually the default) will use the global timeout value and a value of
+`0` will turn off timeout enforcement for that method call no matter what the global
+value is.
To set a global timeout, use the `Git.config` object:
```ruby
Git.config.timeout = nil # a value of nil or 0 means no timeout is enforced
@@ -191,23 +182,24 @@
Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::SignaledError
```
-If the command takes too long, a `Git::SignaledError` will be raised:
+If the command takes too long, a `Git::TimeoutError` will be raised:
```ruby
begin
Git.clone(repo_url, timeout: 10)
rescue Git::TimeoutError => e
- result = e.result
- result.class #=> Git::CommandLineResult
- result.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
- result.status.timeout? #=> true
- result.git_cmd # The git command ran as an array of strings
- result.stdout # The command's output to stdout until it was terminated
- result.stderr # The command's output to stderr until it was terminated
+ e.result.tap do |r|
+ r.class #=> Git::CommandLineResult
+ r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
+ r.status.timeout? #=> true
+ r.git_cmd # The git command ran as an array of strings
+ r.stdout # The command's output to stdout until it was terminated
+ r.stderr # The command's output to stderr until it was terminated
+ end
end
```
## Examples
@@ -242,13 +234,16 @@
g.index.readable?
g.index.writable?
g.repo
g.dir
-g.log # returns a Git::Log object, which is an Enumerator of Git::Commit objects
-g.log(200)
-g.log.since('2 weeks ago')
+# log - returns a Git::Log object, which is an Enumerator of Git::Commit objects
+# default configuration returns a max of 30 commits
+g.log
+g.log(200) # 200 most recent commits
+g.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
+g.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
g.log.between('v2.5', 'v2.6')
g.log.each {|l| puts l.sha }
g.gblob('v2.5:Makefile').log.since('2 weeks ago')
g.object('HEAD^').to_s # git show / git rev-parse
@@ -530,11 +525,17 @@
## Ruby version support policy
This gem will be expected to function correctly on:
* All non-EOL versions of the MRI Ruby on Mac, Linux, and Windows
-* The latest version of JRuby on Linux and Windows
+* The latest version of JRuby on Linux
* The latest version of Truffle Ruby on Linus
+It is this project's intent to support the latest version of JRuby on Windows
+once the following JRuby bug is fixed:
+
+jruby/jruby#7515
+
## License
-licensed under MIT License Copyright (c) 2008 Scott Chacon. See LICENSE for further details.
+Licensed under MIT License Copyright (c) 2008 Scott Chacon. See LICENSE for further
+details.