README.md in bundler-download-1.2.0 vs README.md in bundler-download-1.3.0
- old
+ new
@@ -1,9 +1,9 @@
-# bundler-download - Bundler Plugin
+# bundler-download - Bundler Plugin - v1.3.0
[](http://badge.fury.io/rb/bundler-download)
-Bundler plugin for auto-downloading extra gem files (e.g. large file downloads) specified in [`Downloadfile`](#downloadfile) after `bundle install`.
+Bundler plugin for auto-downloading extra gem files (e.g. large file downloads) specified in [`Downloadfile`](#downloadfile) after `bundle install`
## Background
The RubyGem ecosystem, famous for gems like Rails for web development, Devise for authentication, and Pundit for authorization, enables productivity via code reuse. As such, it is great for quickly adding libraries to your project to automate part of the work or reuse other people's solutions to solved problems.
@@ -22,11 +22,11 @@
## Gem Instructions
Add [bundler-download](https://rubygems.org/gems/bundler-download) as a standard .gemspec dependency:
```ruby
-s.add_dependency('bundler-download', [">= 1.1.0"])
+s.add_dependency('bundler-download', ["~> 1.3"])
```
Afterwards, ensure there is a [`Downloadfile`](#downloadfile) at the root directory of the gem, including in .gemspec `files`:
```ruby
@@ -66,10 +66,12 @@
2. `to:` keyword arg: mentions a local download path relative to the gem installation directory (e.g. 'vendor' or 'lib/ai/data'). It automatically creates the path with all its subdirectories if it does not already exist. If left empty, then the file is downloaded to the gem directory root path.
3. `os:` keyword arg (value: `mac` / `windows` / `linux`): limits the operating system under which the download is made. It is `nil` by default, allowing the download to occur in all operating systems.
## App Bundler Plugin Instructions
+In plugin mode, all gems declared in Gemfile are inspected for presence of Downloadfile regardless of what group they belong to.
+
An app can depend on a gem that has a `Downloadfile` by adding the `bundler-download` plugin first (or manually installing via `bundle plugin install bundler-download`) and then including the gem in `Gemfile` like it normally would:
```
plugin 'bundler-download'
@@ -98,11 +100,11 @@
Using strings-ansi 0.1.0
Using tty-cursor 0.7.1
Using tty-screen 0.8.1
Using unicode-display_width 1.7.0
Using tty-progressbar 0.17.0
-Using bundler-download 1.1.0
+Using bundler-download 1.3.0
Using facets 3.1.0
Using glimmer 1.0.0
bundle-download plugin gem-after-install-all hook:
Processing /Users/User/.rvm/gems/ruby-2.7.1@tmp/gems/glimmer-1.0.0/Downloadfile
Download URL: https://equo-chromium-cef.ams3.digitaloceanspaces.com/rls/repository/plugins/com.make.chromium.cef.gtk.linux.x86_64_0.4.0.202005172227.jar
@@ -161,20 +163,23 @@
```
Prints:
```
-== bundler-download - Bundler Plugin - v1.1.0 ==
-Commands/Subcommands:
- bundle download help # Provide help by printing usage instructions
- bundle download usage # (alias for help)
- bundle download start # Start download
- bundle download # (alias for start)
- bundle download clear # Clear downloads by deleting them under all gems
- bundle download clean # (alias for clear)
- bundle download list # List downloads by printing Downloadfile content for all gems
- bundle download show # Show downloaded files for all gems
+== bundler-download - Bundler Plugin - v1.3.0 ==
+
+Commands/Subcommands/Options:
+ bundle download help # Provide help by printing usage instructions
+ bundle download usage # (alias for help)
+ bundle download start # Start downloads for current operating system
+ bundle download # (alias for start)
+ bundle download --all-operating-systems # Download files for all operating systems
+ bundle download --keep-existing # Do not redownload already downloaded files
+ bundle download clear # Clear downloads by deleting them under all gems
+ bundle download clean # (alias for clear)
+ bundle download list # List downloads by printing Downloadfile content for all gems
+ bundle download show # Show downloaded files for all gems
```
##### clear (alias: clean)
Run the `clear` subcommand to clear downloads by deleting them under all gems:
@@ -224,17 +229,26 @@
54070695 /Users/User/.rvm/gems/ruby-2.7.1@bundler-download/gems/glimmer-cw-browser-chromium-1.0.0/vendor/jars/mac/com.make.chromium.cef.cocoa.macosx.x86_64_0.4.0.202005172227.jar
```
### API
+In API mode, only gems belonging to the default group in Gemfile are inspected for presence of Downloadfile by default. An app may change that though by loading other Bundler groups (e.g. `Bundler.setup(:default, :developemnt)`)
+
Apps may choose to integrate with the [bundler-download](https://rubygems.org/gems/bundler-download) gem directly to trigger downloads instead of relying on the plugin.
This can be useful when wanting to trigger downloads only on first use while staying transparent should the gem features not be used.
To do so, simply include this Ruby code to trigger downloads:
```ruby
require 'bundler-download'
Bundler::Download.new.exec('download', [])
+```
+
+You can also use the `--keep-existing` option to avoid redownload if files were there already:
+
+```ruby
+require 'bundler-download'
+Bundler::Download.new.exec('download', ['--keep-existing'])
```
## Contributing to bundler-download
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.