- Notifications
You must be signed in to change notification settings - Fork41
ember-cli/ember-cli-update
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
UpdateEmber CLI projects
The 2 use cases are:
- Updating a project's boilerplate code from an older Ember version to a newer one like 3.4.0 to 3.20.0 for example. These are called base blueprints and there are 3 types officially provided by ember-cli:
app,addon, andglimmer.- This is different from the existing
ember initcommand. That command tries to reset your project back to a brand new project. It removes all your changes and additions.
- This is different from the existing
- Updating boilerplate code for a blueprint from an Ember addon from an older version to a newer one. These are called custom blueprints.
Check outthe wiki guide for more details.
You can run the CLI either as a global executable available to all projects or an Ember CLI command in a single project.
The CLI attempts to be a thin wrapper ofboilerplate-update.
As a global executable:
npm install -g ember-cli-update
As an Ember CLI command:
ember install ember-cli-update
(You must commit the change topackage.json before running the update command or else you get an error.)
Make sure your git working directory is clean before updating.
Inside your project directory, if you installed globally run
ember-cli-update
or if you installed as an Ember CLI command run
ember update
This will update your app or addon to the latest Ember CLI version. It does this by fetching the latest version and comparing it to your project's Ember CLI version. It then applies a diff of the changes from the latest version to your project. It will only modify the files if there are changes between your project's version and the latest version, and it will only change the section necessary, not the entire file.
This is different from the existingember init command. That command tries to reset your project back to a brand new project. It removes all your changes and additions.
You will probably encounter merge conflicts, in which the default behavior is to let you resolve conflicts on your own. You can supply the--resolve-conflicts option to run your system's git merge tool if any conflicts are found.
This tool can also run codemods for you. The option--run-codemods will figure out what codemods apply to your current version of Ember.js, and download and run them for you.
(These examples assume you are using the global command.)
To update to the latest version of Ember CLI:
ember-cli-updateTo update to a certain version of Ember CLI:
ember-cli-update --to 3.1.0To run codemods:
(This should be run after running the normal update shown above, and after you've resolved any conflicts.)
ember-cli-update --run-codemodsember-cli-updateCommands: ember-cli-update bootstrap saves the detected blueprint state ember-cli-update codemods Run codemods to help update your code ember-cli-update compare Show the changes between different versions without updating ember-cli-update init initialize a blueprint ember-cli-update install <addon> install an addon ember-cli-update reset reset a blueprint ember-cli-update save save old blueprint state ember-cli-update stats list blueprint version updatesOptions: --help Show help [boolean] --version Show version number [boolean] -p, --package-name, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https:// git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@ github.com/tildeio/libkit.git", "../blueprint") [string] --from Use a starting version that is different than what is in your package.json ("2.9.1") [string] --to Update to a version that isn't latest ("2.14.1", "~2.15", "latest", "beta") [string] --resolve-conflicts Automatically run git mergetool if conflicts found [boolean] [default: false] --run-codemods Run codemods to help update your code [boolean] [default: false] --codemods-source Supply your own codemods manifest via URL ("ember-app-codemods-manifest@*", "git+https://github.com/ember-cli/ember-app-cod emods-manifest.git#semver:*") [string] --codemods-json Supply your own codemods manifest via JSON (`{ /* json */ }`) [string] --reset Reset your code to the default blueprint at the new version [boolean] [default: false] --compare-only Show the changes between different versions without updating [boolean] [default: false] --stats-only Show all calculated values regarding your project [boolean] [default: false] --list-codemods List available codemods [boolean] [default: false] --output-repo An output repository of changes over time [string]ember-cli-update bootstrapsaves the detected blueprint stateOptions: --help Show help [boolean] --version Show version number [boolean]ember-cli-update codemodsRun codemods to help update your codeOptions: --help Show help [boolean] --version Show version number [boolean] -p, --packageName, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] --source-json Supply your own codemods manifest via JSON (`{ /* json */ }`) [string] --list List available codemods [boolean] [default: false]ember-cli-update compareShow the changes between different versions without updatingOptions: --help Show help [boolean] --version Show version number [boolean] -p, --packageName, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] --to Update to a version that isn't latest ("2.14.1", "~2.15", "latest", "beta") [string]ember-cli-update initinitialize a blueprintOptions: --help Show help [boolean] --version Show version number [boolean] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] --to Update to a version that isn't latest ("2.14.1", "~2.15", "latest", "beta") [string] --resolveConflicts Automatically run git mergetool if conflicts found [boolean] [default: false] --outputRepo An output repository of changes over time [string] --codemodsSource Supply your own codemods manifest via URL ("ember-app-codemods-manifest@*", "git+https://github.com/ember-cli/ember-app-codemods-m anifest.git#semver:*") [string]ember-cli-update install <addon>install an addonOptions: --help Show help [boolean] --version Show version number [boolean] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string]ember-cli-update resetreset a blueprintOptions: --help Show help [boolean] --version Show version number [boolean] -p, --packageName, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] --to Update to a version that isn't latest ("2.14.1", "~2.15", "latest", "beta") [string]ember-cli-update savesave old blueprint stateOptions: --help Show help [boolean] --version Show version number [boolean] -p, --packageName, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] --from Use a starting version that is different than what is in your package.json ("2.9.1") [string] --outputRepo An output repository of changes over time [string] --codemodsSource Supply your own codemods manifest via URL ("ember-app-codemods-manifest@*", "git+https://github.com/ember-cli/ember-app-code mods-manifest.git#semver:*") [string]ember-cli-update statslist blueprint version updatesOptions: --help Show help [boolean] --version Show version number [boolean] -p, --packageName, --package Provide a package that can contain many blueprints ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string] -b, --blueprint Provide a custom blueprint for use in the update ("@glimmer/blueprint", "git+https://git@github.com/tildeio/libkit.git", "../blueprint") [string]Let's update from Ember CLI 2.18.2 to Ember CLI 3.1.4
First, make sure you are on the latest ember-cli-update version for good measure.
npm install -g ember-cli-updateThen, run all compatible codemods against your current version. Since codemods are downloaded on the fly, they can be updated (and new ones added) without even getting a new version of ember-cli-update. Also, we may add additional codemods targeting your older version of Ember.js.
ember-cli-update --run-codemodsAssuming you are multiple versions behind of Ember CLI, you may want to update in stages. Unless you have a really simple app, updating in stages can help isolate upgrade issues.
ember-cli-update --to 3.0Once you resolve conflicts and commit, You again want to run codemods. This is because new codemods targeting Ember.js 3.0 will now apply.
ember-cli-update --run-codemodsNow you are ready to update again. (If your final update is going to be the latest version of Ember CLI, you don't need the--to option.)
ember-cli-update --to 3.1Again, after you resolve conflicts and commit, you want to run codemods because of new Ember.js 3.1 codemods.
ember-cli-update --run-codemodsAnd then you're done! You have a freshly updated app (or addon). As noted, you can consolidate these steps by doing a direct update, but then you may be confused if you encounter issues which version is to blame.
Need help usinggit mergetool? Here are some starting points:
If you made a mistake during the update/conflict resolution, run these commands to undo everything and get you back to before the update:
git reset --hardgit clean -fIf you notice ".orig" files lying around after a merge and don't want that behavior, rungit config --global mergetool.keepBackup false.
To avoid being prompted "Hit return to start merge resolution tool (vimdiff):" for every conflict, set a merge tool likegit config --global merge.tool "vimdiff".
If you run into an error likeerror: unrecognized input, you may need to update your git config color option likegit config --global color.ui auto.
If you are getting an error or unexpected results, running the command with the debug flag:
- Unix (global):
DEBUG=ember-cli-update,boilerplate-update,git-diff-apply ember-cli-update - Windows (global):
set DEBUG=ember-cli-update,boilerplate-update,git-diff-apply && ember-cli-update - Unix (command):
DEBUG=ember-cli-update,boilerplate-update,git-diff-apply ember update - Windows (command):
set DEBUG=ember-cli-update,boilerplate-update,git-diff-apply && ember update
will give you more detailed logging.
About
Update Ember CLI projects
