Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dpa99c/cordova-check-plugins
A CLI tool to check for / manage plugin updates in Cordova/Phonegap projects.
https://github.com/dpa99c/cordova-check-plugins
Last synced: 19 days ago
JSON representation
A CLI tool to check for / manage plugin updates in Cordova/Phonegap projects.
- Host: GitHub
- URL: https://github.com/dpa99c/cordova-check-plugins
- Owner: dpa99c
- Created: 2015-12-10T22:10:38.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-10-25T10:52:04.000Z (about 1 year ago)
- Last Synced: 2024-11-17T19:06:00.852Z (26 days ago)
- Language: JavaScript
- Homepage:
- Size: 302 KB
- Stars: 216
- Watchers: 8
- Forks: 25
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
cordova-check-plugins [](https://travis-ci.org/dpa99c/cordova-check-plugins) [](https://www.npmjs.com/package/cordova-check-plugins) [](https://npm-stat.com/charts.html?package=cordova-check-plugins)
=====================
A CLI tool to check for / manage plugin updates in Cordova/Phonegap projects.
[](https://raw.githubusercontent.com/dpa99c/cordova-check-plugins/master/screenshot/1.jpg)
**Table of Contents**
- [Purpose](#purpose)
- [Use cases](#use-cases)
- [Installation](#installation)
- [Usage](#usage)
- [Command-line options](#command-line-options)
- [-h or --help](#-h-or---help)
- [-v or --version](#-v-or---version)
- [--verbose](#--verbose)
- [--update={mode|pluginIds}](#--updatemodepluginids)
- [--unconstrain-versions](#--unconstrain-versions)
- [--force, --force-update](#--force---force-update)
- [--nosave](#--nosave)
- [--github-username and --github-password](#--github-username-and---github-password)
- [--target](#--target)
- [--allow-downdate](#--allow-downdate)
- [--remove-all](#--remove-all)
- [--obfuscate-credentials](#--obfuscate-credentials)
- [--nofetch](#--nofetch)
- [--cwd](#--cwd)
- [--nospinner](#--nospinner)
- [Supported plugin sources](#supported-plugin-sources)
- [Integration with Cordova CLI](#integration-with-cordova-cli)
- [License](#license)
# Purpose
This tool intends to provide a convenient way to check if the plugins contained within a Cordova project are up-to-date and to optionally update them.
It has arisen from my own necessity when managing complex Cordova projects containing many plugins.
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZRD3W47HQ3EMJ)
I dedicate a considerable amount of my free time to developing and maintaining this tool, along with my other Open Source software.
To help ensure this tool is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this tool in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.
## Use cases
This tool is useful for:
- Checking if updates are available for plugins installed in a project.
- Updating outdated plugins, either automatically or interactively.
- Keeping installed plugin versions in sync with those specified in config.xml
- Quickly removing all installed plugins in a project.
# Installation
npm install -g cordova-check-plugins
# Usage
Once `cordova-check-plugins` is installed globally, it can be run from the root of any Cordova/Phonegap project:
$ cordova-check-plugins
By default, it will display lists of plugins under the following categories:
- "Plugin update available" - installed plugins for which a new remote version is available (displayed in green)
- "Installed plugin version newer than remote default" - installed plugins for which the installed version is newer than the default remote version (displayed in yellow)
- "Unknown plugin version mismatch" - installed plugins for which the remote version could not be determined as older/newer (displayed in yellow)
- "Error checking plugin version" - installed plugins for which an error occurred while checking the plugin versions (displayed in red)
- "Up-to-date plugins" - installed plugins which are up-to-date with the detected remote version (displayed in grey)
Plugins for which updates are available can optionally be updated either interactively or automatically via the `--update` command-line option.
## Command-line options
### -h or --help
$ cordova-check-plugins -h
$ cordova-check-plugins --help
Displays usage information.
### -v or --version
$ cordova-check-plugins -v
$ cordova-check-plugins --version
Displays currently installed version of this module.
### --verbose
Displays detailed log output.
$ cordova-check-plugins --verbose
### --update={mode|pluginIds}
Specifies update mode for plugins which have updates available. Valid modes are:
- `none` - (default) don't update plugins
- `interactive` - using interactive CLI to choose which plugins to update manually
- `auto` - automatically update any plugins for which an update is available
i.e.
$ cordova-check-plugins --update=none
same as: $ cordova-check-plugins
$ cordova-check-plugins --update=interactive
$ cordova-check-plugins --update=auto
Or where `pluginIds` is the ID of a single specific plugin to update, or a space-separated list of multiple plugin IDs.
e.g
$ cordova-check-plugins --update=cordova-plugin-geolocation
$ cordova-check-plugins --update="cordova-plugin-geolocation cordova-plugin-dialogs"
### --unconstrain-versions
$ cordova-check-plugins --unconstrain-versions
Unconstrains checking of remote version so the highest remote version will be displayed regardless of specified version.
By default, if the version was specified when the plugin was installed, the specified version number will be used to constrain which remote versions are returned.
For example, let's say `cordova-plugin-foo` has remote versions `1.0.1`, `1.0.2`, `1.1.0`, `2.0.0`:
- If `cordova plugin add cordova-plugin-foo` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `2.0.0`
- If `cordova plugin add cordova-plugin-foo@1` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `1.1.0`
- If `cordova plugin add [email protected]` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `1.0.2`
- If `cordova plugin add [email protected]` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `1.0.1`
- If `cordova plugin add cordova-plugin-foo@~1.0.1` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `1.0.2`
- If `cordova plugin add cordova-plugin-foo@^1.0.1` was used to install the plugin, then `cordova-check-plugins` will return the highest remote version as `1.1.0`
Calling `cordova-check-plugins --unconstrain-versions` will ignore the specified version, so in the example above, all cases would return `2.0.0`.
Note that this only option affects plugins whose source is npm.
It will have no effect on plugins installed directly from github repos.
This is because it's not possible to distinguish if github URLs contain a branch or a tag reference. Both are specified using `#`.
So it's not possible to distinguish a tag URL (e.g. `http://github.com/some/repo#r1.2.3`) from a branch URL (e.g. `http://github.com/some/repo#some_branch`).
### --force, --force-update
Forces the update of dependent plugins when updating plugins.
By default, Cordova/Phonegap will not allow the removal of plugins on which other plugins are dependent, and therefore will not allow them to be updated/removed.
For example, `cordova-plugin-file-transfer` depends on `cordova-plugin-file`.
By setting this option, both plugins will be updated (if updates are available).
Without it, only the "parent" plugin - in this case `cordova-plugin-file-transfer` - will be updated.
$ cordova-check-plugins --update=auto --force
### --nosave
Omits saving changes when updating plugins.
By default (if this argument is omitted), when updating plugins, changes will be saved to config.xml and package.json.
$ cordova-check-plugins --update=auto --force-update --nosave
$ cordova-check-plugins --remove-all --nosave
### --github-username and --github-password
Allows specification of user credentials for GitHub, increasing API request limit to 5000 requests/hour.
Also enables access to private repos.
When checking remote versions for that are hosted on GitHub, by default unauthenticated access to the GitHub API is used.
This is [rate limited](https://developer.github.com/v3/#rate-limiting) to 60 requests/hour.
For most users, this should be sufficient, but if this module is used in a Continuous Integration environment with a project using multiple GitHub-hosted plugins, that rate can be exceeded.
By specifying valid GitHub user credentials, these will be used when communicating with the GitHub API, which increases the number of allowed requests to 5000 requests/hour.
$ cordova-check-plugins --github-username=myUsername --github-password=myPassword
### --target
Sets the target to use for establishing if installed plugins are up-to-date.
Valid values are:
- `remote` - (default) installed plugin versions will be compared to available versions in the remote source (e.g npm registry, git repo, local folder).
- `config` - installed plugin versions will be to compared to the versions specified in `` elements in the config.xml file.
$ cordova-check-plugins --target=config
Setting `--target=config` is useful if you want to keep locally installed plugins in sync with the versions specified in the config.xml, rather than the newest remote versions.
### --allow-downdate
If the installed plugin version is newer than the version specified in the config.xml, allow the plugin to be downgraded to the version specified in the config.xml. Only applies if `--target=config`.
$ cordova-check-plugins --target=config --allow-downdate
### --remove-all
$ cordova-check-plugins --remove-all
Removes all installed plugins from the project. If `--save` is also specified, entries will also be removed from config.xml.
This option is exclusive and the default behaviour of checking for plugin updates will be skipped, as will any updates if `--update` is specified.
### --obfuscate-credentials
$ cordova-check-plugins --obfuscate-credentials="my_password my_access_token"
A space-separated list of credentials to obfuscate when logging output to the console.
This is useful if your plugin source URLs contain sensitive credentials such as passwords or access tokens that you don't want to appear in console output from the tool.
Any credentials specified here will be replaced with {obfuscated} in the console output.
### --nofetch
$ cordova-check-plugins --update=auto --nofetch
If using `cordova@7+`, forces Cordova CLI to use legacy `git clone` mechanism when installing plugins, rather than the default `npm install` method.
Only applies when updating plugins.
See the [Cordova 7 release notes](https://cordova.apache.org/news/2017/05/04/cordova-7.html) for more details.
### --cwd
$ cordova-check-plugins --cwd=/path/to/project
Sets the directory from which the tool should be executed.
If not specified, defaults to the directory from which the `cordova-check-plugins` command is executed.
### --nospinner
$ cordova-check-plugins --nospinner
Turns off the [CLI spinner](https://www.npmjs.com/package/cli-spinner) which is used by default to indicate when an async operation is in progress.
If you're capturing the output of this command to a log (e.g. in a CI environment), then this spinner pollutes the log with unnecessary junk, so turning it off makes for a more readable log.
# Supported plugin sources
- Plugins installed via the npm registry (with optionally specified versions)
- Plugins installed directly from GitHub repos (with optionally specified branches/tags)
- Plugins installed from local sources (on the local machine)
For example:
cordova-plugin-camera
cordova-plugin-geolocation@*
cordova-plugin-whitelist@1
[email protected]
cordova-plugin-inappbrowser@~1.1.1
cordova-plugin-device@^1.0.0
https://github.com/apache/cordova-plugin-battery-status
cordova-plugin-battery-status@https://github.com/apache/cordova-plugin-battery-status <-- cordova@7 syntax
https://github.com/apache/cordova-plugin-battery-status#r1.0.0
git://github.com/apache/cordova-plugin-battery-status.git#r1.0.0
https://username:[email protected]/apache/cordova-plugin-battery-status
https://access_token:@github.com/apache/cordova-plugin-battery-status
/some/local/path/to/a/plugin
# Integration with Cordova CLI
Using [cordova-plugin-config-command](https://github.com/dpa99c/cordova-plugin-config-command), this tool can be triggered during the Cordova CLI build cycle by inserting a `` into the `config.xml`.
For example, to automatically update installed plugins to match versions specified in the `config.xml`:
License
================
The MIT License
Copyright (c) 2015 Dave Alden / Working Edge Ltd.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.