You might also be interested in:
Install Update's CLI and an example updater globally:
$ npm install --global update && updater-example
Initialize update
:
$ update init
Run update:
$ update
All updating is accomplished using plugins called updaters, which are run by command line or API, and can be installed globally, locally, or created in a local updatefile.js
.
You can create your own updaters using Update's API, or install updaters using npm, to do things like:
- create continuity and consistency across projects
- enforce conventions across all of your projects
- instantly update an old or inherited project to your latest personal preferences (convert tabs to spaces, convert from
jshint
toeslint
or the other way around, or any other detail) - reformat code to meet your standards
- convert a config file to a different format (json to yaml, yaml to json, etc)
- update files that are typically excluded from build cycles, and are often forgotten about after they're created. For example:
- fix dates in copyrights, licenses and banners
- remove deprecated fields from project manifests
- update settings in runtime config files, preferences in dotfiles
- after initializing a new project with a project generator, like [generate][] or Google's Yeoman, you can "normalize" all of the generated files to use your own preferences
- be more productive: Update eliminates time spent on things that can be automated, but typically aren't since they either don't need to be done often, don't fit into the build cycle or a project's deliverables, or because they're usually updated manually. As code projects mature, time spent on these things tend to stay linear or increase as the size of a community grows. If you maintain more than a handful of projects, time spent on these things compounds with each new project under your stewardship.
- your way, instantly: updaters can be published to and installed from npm, but you can also easily create your own personal updaters. Once your updaters are setup, just run
update init
, then projects under your maintenance will convert to the the conventions you prefer within milliseconds after runningupdate
. - plugin ecosystem: any plugins that work with Base applications will work also with Update. Which means you can use plugins (or generators) from [assemble][], [verb][], and [generate][], to name a few.
- well tested: with more than 1,250 unit tests
Here are some random example commits after running $ update
.
Project/Commit | Updaters used |
---|---|
generate-scaffold | editorconfig , travis |
updater-editorconfig | editorconfig , eslint , travis , license |
expand-target | editorconfig , eslint , travis , package |
- unparalleled flow control: through the use of updaters, sub-updaters and tasks
- generators: support for [generate][] generators. If your updater needs to create new files, there might be a generator for that. Just use the generator the same way you would use an updater.
- render templates: use templates to create new files, or replace existing files
- prompts: It's easy to create custom prompts. Answers to prompts can be used as context for rendering templates, for settings options, determining file names, directory structure, and anything else that requires user feedback.
- any engine: use any template engine to render templates, including [handlebars][], [lodash][], [swig][] and [pug][], or anything supported by [consolidate][].
- data: gather data from the user's environment to populate "hints" in user prompts or for rendering templates
- fs: in the spirit of [gulp][], use
.src
and.dest
to read and write globs of files. - vinyl: files and templates are [vinyl][] files
- streams: full support for [gulp][] and [assemble][] plugins
- smart plugins: Update is built on [base][], so any "smart" plugin from the Base ecosystem can be used
- stores: persist configuration settings, global defaults, project-specific defaults, answers to prompts, and so on.
- much more!
Install update
To use Update's CLI, update
must first be installed globally with npm:
$ npm install --global update
This adds the update
command to your system path, allowing it to be run from anywhere.
Updaters can be found on npm, but if you're not familiar with how Update works, we recommend installing updater-example
:
$ npm install --global updater-example
Create "example.txt"
In the current working directory, create an empty file named example.txt
.
Run
As a habit, when using update
make sure your work is committed, then run:
$ update example
This appends the string foo
to the contents of example.txt
. Visit the [updater-example][] project for additional steps and guidance.
Update ships with the following built-in tasks. These will be externalized to an updater or [generate][] generator at some point.
{%= apidocs("lib/updatefile.js") %}
$ update help
Usage: update <command> [options]
Command: updater or tasks to run
Options:
--config, -c Save a configuration value to the `update` object in package.json
--cwd Set or display the current working directory
--help, -h Display this help menu
--init, -i Prompts you to choose the updaters to automatically run (your "queue")
--add Add updaters to your queue
--remove Remove updaters from your queue
--run Force tasks to run regardless of command line flags used
--silent, -S Silence all tasks and updaters in the terminal
--show <key> Display the value of <key>
--version, -V Display the current version of update
--verbose, -v Display all verbose logging messages
Examples:
# run updater "foo"
$ update foo
# run task "bar" from updater "foo"
$ update foo:bar
# run multiple tasks from updater "foo"
$ update foo:bar,baz,qux
# run a sub-generator from updater "foo"
$ update foo.abc
# run task "xyz" from sub-generator "foo.abc"
$ update foo.abc:xyz
Update attempts to automatically determine if "foo" is a task or updater.
If there is a conflict, you can force update to run updater "foo"
by specifying its default task. Example: `$ update foo:default`
- Find updaters to install by searching npm for packages with the keyword
updateupdater
- Visit Update's GitHub org to see the updaters maintained by the core team
Plugins from any applications built on [base][] should work with Update (and can be used in your updater):
- base: find base plugins on npm using the
baseplugin
keyword - assemble: find assemble plugins on npm using the
assembleplugin
keyword - generate: find generate plugins on npm using the
generateplugin
keyword - templates: find templates plugins on npm using the
templatesplugin
keyword - update: find update plugins on npm using the
updateplugin
keyword - verb: find verb plugins on npm using the
verbplugin
keyword
Visit the updater documentation guide to learn how to use, author and publish updaters.
Customize settings and default behavior using the update
property in package.json. These values will override global defaults.
{
"update": {
"updaters": ["package", "license", "keywords"]
}
}
The following options may be defined in package.json.
The updaters to run on the current project.
Example
Run updater-license
and updater-package
on the current project:
{
"update": {
"updaters": ["package", "license"]
}
}
- See the updaters maintained by the core team
- Browse the documentation
- Browse the API documentation
- Learn about updaters
- Learn about the built-in updaters
- Learn more about [base][]
- Get Sublime Text Snippets for creating tasks and updaters
{%= increaseHeadings(changelog('CHANGELOG.md', { changelogFooter: true, stripHeading: true, repo: repo })) %}