update / update

Update is a new developer framework and CLI for automating updates of any kind in code projects. If you know how to use assemble, generate or verb, you'll know how to use update.

Be scalable! Update is a new, open source developer framework and CLI for automating updates of any kind in code projects.

update

You might also be interested in:

• generate
• assemble
• verb

Quickstart

Install Update's CLI and an example updater globally:

$ npm install --global update && updater-example

Initialize update:

$ update init

Run update:

$ update

Overview

What does Update do?

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 to eslint 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

Why should I use Update?

• 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 running update.
• 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

Examples

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

Features

• 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!

CLI

Installing update

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.

Installing updaters

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.

Tasks

Update ships with the following built-in tasks. These will be externalized to an updater or generate generator at some point.

init

Select the updaters to run every time update is run. Use --add to add additional updaters, and --remove to remove them. You can run this command whenever you want to update your preferences, like after installing new updaters.

Example

$ update init

list

Display a list of currently installed updaters.

Example

$ update defaults:list
# aliased as
$ update list

help

Display a help menu of available commands and flags.

Example

$ update defaults:help
# aliased as
$ update help

show

Show the list of updaters that are registered to run on the current project.

Example

$ update defaults:show
# aliased as
$ update show

help

Default task for the built-in defaults generator.

Example

$ update help

Help menu

$ 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`

API

Updaters

Discovering updaters

• 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

Discovering plugins

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

Authoring updaters

Visit the updater documentation guide to learn how to use, author and publish updaters.

Configuration

Customize settings and default behavior using the update property in package.json. These values will override global defaults.

{
  "update": {
    "updaters": ["package", "license", "keywords"]
  }
}

Options

The following options may be defined in package.json.

updaters

The updaters to run on the current project.

Example

Run updater-license and updater-package on the current project:

{
  "update": {
    "updaters": ["package", "license"]
  }
}

More information

• 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

Release History

key

Changelog entries are classified using the following labels from keep-a-changelog:

• added: for new features
• changed: for changes in existing functionality
• deprecated: for once-stable features removed in upcoming releases
• removed: for deprecated features removed in this release
• fixed: for any bug fixes

Custom labels used in this changelog:

• dependencies: bumps dependencies
• housekeeping: code re-organization, minor edits, or other changes that don't fit in one of the other categories.

Heads up!

Please let us know if any of the following heading links are broken. Thanks!

0.7.3 - 2016-07-21

fixed

• ensure app.cwd in the current instance is the cwd defined by the user on the options or argv.

0.7.0 - 2016-07-21

added

• as of v0.7.0, we will begin using the keep-a-changelog format for release history
• adds support user-defined templates
• adds support for app.home(), which resolves to ~/ or the user-defined options.homedir. This directory is used to determine the base directory for user-defined templates.
• adds support for common-config. Exposed on the app.common object (e.g. app.common.set() etc)
• adds experimental support for a home updater. If an updatefile.js exists in the ~/update directory (this will be customizable, but it's not yet), this file will be loaded and .use()d as a plugin before other updaters are loaded. You can use this to set options, add defaults, etc. But you can also run it explictly via commandline with the update home command.

fixed

• fixes app.cwd so that it's updated when app.options.dest (--dest) is set
• ensure args are parsed consistently

0.6.0

• Swap out base for assemble-core (which uses Base via templates). This allows updaters to seamlessly run generators from generate, assemble, or verb (when a file needs to be created, or re-created for example)
• Adds assemble-loader to support glob patterns in collection methods

[0.5.0]

First stable release!

(Changelog generated by helper-changelog)

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• base: Framework for rapidly creating high quality, server-side node.js applications, using plugins like building blocks | homepage
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Community

Are you using Update in your project? Have you published an updater and want to share your Update project with the world?

Here are some suggestions!

• If you get like Update and want to tweet about it, please use the hashtag #updatejs (not @)
• Show your love by starring Update and update
• Get implementation help on StackOverflow (please use the updatejs tag in questions)
• Gitter Discuss Update with us on Gitter
• If you publish an updater, thank you! To make your project as discoverable as possible, please add the keyword updateupdater to package.json.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on January 23, 2018.

update's Issues

updater-contributors: Adding entries to the package.json "contributors" property.

This would be really handy for quickly adding people who contributed to the project, which encourages better citation for them I think. By creating entries in the "contributors" property in the package.json, and perhaps managing a AUTHORS file, or some other citation method.

It would be cool if it could somehow scan the git commits for the authors as well? Not sure if something like that obtainable with this module alone, might need some deps.

Also, following All Contributors would be interesting as well (pretty much just discovered this on my home page).

Please fix `assign-deep` and `set-value` vulnerabilities

I am using latest package [email protected]. It's using vulnerable packages assign-deep and set-value. Please fix it and provide updates.

npm audit

High            Prototype Pollution
Package         assign-deep
Patched in      >=1.0.1
Dependency of   update [dev]
Path            update > assemble-core > templates > template-error > engine > assign-deep
More info       https://npmjs.com/advisories/1014


High            Prototype Pollution
Package         assign-deep
Patched in      >=1.0.1
Dependency of   update [dev]
Path            update > assemble-core > templates > engine-base > engine > assign-deep
More info       https://npmjs.com/advisories/1014


High            Prototype Pollution
Package         set-value
Patched in      >=2.0.1 <3.0.0 || >=3.0.1
Dependency of   update [dev]
Path            update > common-config > question-cache > set-value
More info       https://npmjs.com/advisories/1012


High            Prototype Pollution
Package         set-value
Patched in      >=2.0.1 <3.0.0 || >=3.0.1
Dependency of   update [dev]
Path            update > base-questions > question-store > question-cache > set-value
More info       https://npmjs.com/advisories/1012

Error: Cannot find module 'del'

'del' is listed in devDependencies so update fails to run.

Recursive Updater ?

Absolutely fantastic project, can stop using it to consolidate all my projects!!!

One idea I was thinking of:

• It would be great to apply all updates in a directory (with several projects)
• Maybe based of an .update.yml file where I can define the updaters defined for this projects
• Then I could just run something like update --recursive and the based on the current directory all updaters defined in each of the projects would be applied

I started to prototype that a bit and this is what I was actually seeking for for quite some time.

What are your thoughts?

Update 2

Critical vulnerability in the [email protected] module that Update uses

Update uses:

update 0.7.4
├─┬ base-cli-process 0.1.19
│ ├─┬ base-config-process 0.1.9
│ │ └─┬ base-config-schema 0.1.24
│ │ └─┬ base-pkg 0.2.5
│ │ └─┬ expand-pkg 0.1.9
│ │ └── defaults-deep 0.2.4
│ └─┬ base-pkg 0.2.5
│ └─┬ expand-pkg 0.1.9
│ └── defaults-deep 0.2.4
├─┬ base-config-process 0.1.9
│ └─┬ base-config-schema 0.1.24
│ └─┬ base-pkg 0.2.5
│ └─┬ expand-pkg 0.1.9
│ └── defaults-deep 0.2.4
└─┬ base-generators 0.4.6
└─┬ base-pkg 0.2.5
└─┬ expand-pkg 0.1.9
└── defaults-deep 0.2.4

[email protected], has a critical vulnerability (GHSA-pjxw-22xf-6pwc) for which there seems to be no current fix. I have contacted expand-pkg, but I thought you should be informed too.

----

init adds duplicate updater names

when $ update init is run, and all is chosen, it doesn't filter out duplicates if other updaters are also chosen.

(thanks to @phated for pointing this out)

[Suggestion] Choose template for update

One feature I am in general missing in generate/update:

• Let's say I have different project types
• Depending on the project type I'd like to add different templates for a .gitignore
• Then I'd like to do something like update editorconfig --t=gitignore_projectTypeA
  (Then the template gitignore_projectTypeA from ~\templates would be taken).

Is this something which is already possible resp. you are considering to implement?

npm Package Vulnerabilities

It appears that updates currently uses a number of dependencies that have vulnerabilities/patches.

• version: 0.7.4"
• reduced test case:

1. Install npm package
2. run npm audit

• error messages: found 16 vulnerabilities (12 low, 4 moderate)

Broken docs links

It seems that all /update/docs/* links on http://update.github.io/update/ are broken.

updater-files: Adding entries to the package.json "files" property.

I don't imagine this should be something too hard, as it is just an array. you could probably just Array.prototype.push.apply(files, input) or something of the like.

I have never made an update plugin before. I could give it a shot if you want.

run check for staged/un-committed files by default

request: allow the user to sort queued updaters

In the init prompt, we can allow users to sort the values after we port sort-prompt over to use enquirer