Skip to main content

Upgrading an application

Summary​

  1. Option 1 - Automatic Upgrade
  2. Option 2 - Manual Upgrade

Option 1 - Automatic Upgrade​

This is helpful to:

  • Have the latest JHipster features in an existing application
  • Get the changes when there is an important bug fix or security update
  • Retain your changes in your codebase, and merge them with newly generated code
warning

Please read this page carefully before doing an upgrade, to understand how the upgrade process works

Requirements​

For this sub-generator to work you need to have git installed from http://git-scm.com.

Running the upgrade sub-generator​

Go into the application's root directory:

cd myJHipsterProject/

To upgrade your application, type:

npx generator-jhipster@latest upgrade

An alternative is to use global installation:

npm install -g generator-jhipster@latest
jhipster upgrade

Here are the options you can pass:

  • --skip-checks - Disable checks during project regeneration
  • --silent - Hides output of the generation process

Upgrading from JHipster 7 and previous versions​

The migrate blueprint is an advanced version of the upgrade sub-generator. If you need to upgrade a JHipster 7 app, it's recommended you use the migrate blueprint. For example, let's assume you have a 7.9.3 app.

Run jhipster-migrate to upgrade to the latest version. Resolve conflicts, commit, and celebrate!

For a working example, see the following pull requests from the 21-Points Health project.

Graphical view of the upgrade process​

Here is how the upgrade process works graphically (read the sections below to have a textual explanation):

Git graph showing each invocation of 'npx jhipster upgrade' and the commits on jhipster_upgrade branch

Raw .mermaid file

Please note that the jhipster_upgrade branch will be created orphan on your project, although it doesn't display correctly on the above graph.

Step-by-step explanation of the upgrade process​

Below are the steps processed by the JHipster upgrade sub-generator:

  1. Check if there is a new version of JHipster available (not applicable if you are using --force).
  2. Check if the application is already initialized as a git repository, or else JHipster will initialize one for you and commit the current codebase to the master branch.
  3. Check to ensure that there are no un-committed local changes in the repository. The process will exit if there are un-committed changes found.
  4. Check if a jhipster_upgrade branch exists. If not, a branch is created: details about this step is provided in the "Specific steps on first upgrade" section.
  5. Checkout the jhipster_upgrade branch.
  6. Upgrade JHipster to the latest available version globally.
  7. Clean the current project directory.
  8. Re-generate the application using the jhipster --force command.
  9. Commit the generated code to the jhipster_upgrade branch.
  10. Merge the jhipster_upgrade branch back to the original branch from where the npx jhipster upgrade command was launched.
  11. Now you need to proceed with resolving merge conflicts if there are any.

Congratulations, your application is now upgraded with the latest version of JHipster!

Specific steps on first upgrade​

On the first run of the JHipster upgrade sub-generator, in order to avoid erasing all your changes, some additional steps are run:

  1. A jhipster_upgrade branch is created orphan (it has no parent).
  2. The whole application is generated (using your current JHipster version).
  3. A block-merge commit is made on the master branch: no alteration is made on your codebase on the master branch; this is a practical way to record in Git that the HEAD of master is up-to-date with the current JHipster version.

Advice​

  • Don't commit anything on the jhipster_upgrade branch. This branch is dedicated to the JHipster upgrade sub-generator: each time the sub-generator is run, a new commit will be created.

  • If you are updating from a very old version (example from 5.0.0 to latest) we suggest updating gradually between each minor/patch version and performing tests to make sure the application works as expected.

  • There are some helpful approaches from the JHipster community around designing the application in such a way that makes the update process easier, and reduces the amount of merge conflicts. We recommend using JHipster Side-by-Side approach.

Option 2 - Manual Upgrade​

For a manual upgrade, first upgrade your version of JHipster with:

npm install -g generator-jhipster

Delete your project node_modules folder and then run jhipster:

rm -rf node_modules
jhipster

You can also update your project and all its entities by running

jhipster --force

You can also update your entities individually by running the entity sub-generator, i.e., if your entity is named Foo:

jhipster entity Foo

Hints about renamed files​

Sometimes files may be renamed in the generator. If you want to see Git rename detection result then you can run git add (git add . stages all) and view changes after that with your favorite Git client.

If many files are renamed then you may want to increase diff.renameLimit in Git config to make Git rename detection work as expected. For example git config --replace-all diff.renameLimit 10000.

By default Git rename detection uses similarity threshold 50%. To see less similar files as renamed, you can use option --find-renames=<n> in Git commands. For example git diff --staged --find-renames=30.

See your own changes​

If you would like to see changes you have done after generating project you can follow the steps described below.

Clone your project into the new folder with git clone.

Delete all files and folders from cloned project except .git, .jhipster and .yo-rc.json.

Find out what JHipster version you used last time to generate your project: look at the .yo-rc.json in the project root folder, find out the value of the jhipsterVersion.

Install JHipster version you used last time you generated your project:

npm install -g generator-jhipster@jhipsterVersionYouUsedLastTime

Regenerate your project:

jhipster --force --skip-install

With git diff you can now see all your changes as reverted. If you would like to see all your changes as added then you can commit all to Git and then revert the last commit.

See JHipster changes​

If you would like to see changes done by JHipster you can follow the steps described below.

Generate project with JHipster version you used last time to generate your project:

  • create a new folder
  • copy your project .yo-rc.json file and .jhipster folder into this new folder
  • find out what JHipster version you used last time to generate your project: look at the .yo-rc.json, find out the value of the jhipsterVersion
  • install JHipster version you used last time to generate your project: npm install -g generator-jhipster@jhipsterVersionYouUsedLastTime
  • in the created folder run: jhipster --skip-install

Generate project with the latest JHipster:

  • create a new folder
  • copy your project .yo-rc.json file and .jhipster folder into this new folder
  • install the latest JHipster version: npm install -g generator-jhipster
  • in the created folder run: jhipster --skip-install

Compare those 2 folders with your favorite file and folder compare tool to see changes done by JHipster.