Skip to content

Clarify the portable-upgrade procedure #801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 25, 2025
Merged

Clarify the portable-upgrade procedure #801

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a951fa
Clarify the portable-upgrade procedure
pryrt May 24, 2025
a67cc2d
add suggestion to backup before upgrading portable
pryrt May 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 38 additions & 13 deletions content/docs/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ If there is a new version, the Updater dialog will allow you to choose:
Going to the main website and downloading the latest installer and running it yourself. You can watch the [Announcements](https://community.notepad-plus-plus.org/category/1/announcements) category in the [Notepad++ Community Forum](https://community.notepad-plus-plus.org/) to see when new release-candidates or final versions are released.

<a name="new-version-available-but-auto-updater-find-nothing" reasonLink="https://github.com/notepad-plus-plus/wingup/blob/21e375caf17360fb86f757612052d5a785261d96/src/winmain.cpp#L780" reasonDesc="wingup links to this anchor, so it needs to always exist, even though the safety-delay header has been rephrased"></a>

## No New Version Found: Safety Delay

There are two reasons that would cause there to be no new version found during an auto-triggered upgrade check or an on-demand upgrade check:
Expand All @@ -54,31 +55,55 @@ If you have a portable edition of Notepad++, unzipping the contents from the new

1. Starting condition:
- Your original installation is in `c:\PortableNpp\`
- You have the ComparePlus plugin, or otherwise understand how to compare contents of similar files
- You have read and understood the [Online UserManual section on Editing Configuration Files](https://npp-user-manual.org/docs/config-files/#editing-configuration-files)
- For these instructions, this is assumed to be where you want the upgraded copy of Notepad++ to end up.
- These instructions will refer to this as "the Destination".
- You have the ComparePlus plugin, or otherwise understand how to compare contents of similar files.
- You have read and understood the [Online UserManual section on Editing Configuration Files](https://npp-user-manual.org/docs/config-files/#editing-configuration-files).
- Make sure you have recently exited Notepad++ and restarted it, without having made any configuration changes in the GUI since restarting it, as per "Editing Configuration Files".
2. Unzip the new portable zipfile into `c:\PortableNpp.new\`
3. Compare each of the following configuration files. Look for any settings that are in the New but not in the Old, and copy them over.
- **Optional**: For some, the updates in the configuration files usually just give access to new features which you might not care about (like a new right-click menu action); in that case, it is up to you to decide whether you want to bring over the new features or not.
- **Overwrite**: For these configuration files, users rarely customize them. Unless you know that you have, it's generally safe to just overwrite it with the new copy.
- **Model**: For these configuration files, you will be comparing your raw file with the new `.model.` version. These are files that are often customized, so when you are comparing, you will want to be careful to bring over the new features (things that are in the new `.model.`) without getting rid of your customizations.

| Old (`c:\PortableNpp\...`) | New (`c:\PortableNpp.new\...`) | Notes |
- You have already backed up `c:\PortableNpp\` so that you can easily undo any accidental changes.
2. Unzip the new portable zipfile into `c:\PortableNpp.temp\`
- This is just being used to temporarily store the new version of Notepad++.
- These instructions will refer to this as the "Temporary" version.
3. Compare each of the following configuration files. Look for any settings that are in the "Temporary" but not in the "Destination", and copy those settings over inside each file.
- If you find a config file that exists in the "Temporary" but not in the "Destination", and it's not listed below, it could be a new configuration file that these instructions haven't been updated to include that, so you should copy that file over.
- **Key**:
- **Compare**: `config.xml` should always be compared, to make sure old choices are kept and new options are included.
- **Keep**: The `session.xml` file and `backup\` folder's files should always be kept in your "Destination" directory. Do not overwrite them or delete them. (The "Temporary" directory from the Portable unzip will not include that file or directory, but they are included in this list so you don't accidentally delete or overwrite them.)
- **Optional**: For some config files, the updates usually just give access to new features which you might not care about (like a new right-click menu action); in that case, it is up to you to decide whether you want to bring over the new features or not.
- **Overwrite**: For these configuration files, users rarely customize them. Unless you know that you have, it's generally safe to just overwrite it with the new copy. If you know you have customized them (for example, if you've customized your chosen Theme in the Style Configurator¹), you will need to compare them and merge.
- **Model**: For these configuration files, you will be comparing your raw "Destination" file with the new `.model.` version in the "Temporary" location. These are files that are often customized, so when you are comparing, you will want to be careful to bring over the new features (things that are in the new `.model.`) without getting rid of your customizations. The `.model.` files should also be copied over into the "Destination" directory.
- **Zero-byte file**: These configuration files are 0 bytes. If your "Destination" does not have the file, it can be copied from the "Temporary" to the "Destination".

| Destination (`c:\PortableNpp\...`) | Temporary (`c:\PortableNpp.temp\...`) | Notes |
|-----|-----|-------|
| `...\config.xml` | `...\config.xml` | |
| `...\config.xml` | `...\config.xml` | Compare |
| `...\session.xml` | _(does not exist)_ | Keep |
| `...\backup\*.*` | _(does not exist)_ | Keep |
| `...\contextMenu.xml` | `...\contextMenu.xml` | Optional |
| `...\shortcuts.xml` | `...\shortcuts.xml` | Optional |
| `...\toolbarIcons.xml` | `...\toolbarIcons.xml` | Optional |
| `...\langs.xml` | `...\langs.model.xml` | Model |
| `...\stylers.xml` | `...\stylers.model.xml` | Model |
| `...\*_example.xml` | `...\*_example.xml` | Overwrite |
| `...\themes\___.xml` | `...\themes\____.xml` | Overwrite ¹ |
| `...\autoCompletion\___.xml` | `...\autoCompletion\____.xml` | Overwrite |
| `...\localization\___.xml` | `...\localization\____.xml` | Overwrite |
| `...\functionList\___.xml` | `...\functionList\____.xml` | Overwrite |
| `...\userDefineLangs\___.xml` | `...\userDefineLangs\____.xml` | Overwrite |
| `...\updater\*.*` | `...\updater\*.*` | Overwrite |
| `...\change.log` | `...\change.log` | Overwrite |
| `...\license.txt` | `...\license.txt` | Overwrite |
| `...\doLocalConf.xml` | `...\doLocalConf.xml` | Zero-byte file |
| `...\nppLog*Issue.xml` | `...\nppLog*Issue.xml` | Zero-byte file |

- ¹: If you are using a specific theme, it's more likely that you will have customized that theme's file. Please do a full comparison on that theme file, but you can probably get away with just overwriting the other "Destination" theme files using the copies in the "Temporary" directory.

4. After updating the config files, then you can exit Notepad++, copy the `notepad++.exe` and `plugins\config\nppPluginList.dll` from the "Temporary" to the "Destination", and restart Notepad++ to start using your upgraded portable edition which resides in the "Destination" directory.

The "portable" versions of Notepad++ assume you are willing to do some things manually in order to get your true portability. If this procedure seems to complicated for you, and you would rather use something more automatic like the installer: You _can_ use the installer to put Notepad++ in any directory you want, not just in the Program Files hierarchy; and you can tell the installer that you don't want to use AppData, which will put the configuration files in the same directory that the executable goes in, which makes it _nearly_ portable (though the installer might have added hooks to make it easy for you to open files using the installed copy of Notepad++, which goes against the spirit of truly-portable software).

- ¹: If you are using a specific theme, it's more likely that you will have customized that theme's file. Please do a full comparison on that theme file, but you can probably get away with just overwriting the old theme files.
_Note: a similar procedure can be used when you think your installed copy of Notepad++ has themes or syntax highlighting configuration that is missing compared to a fresh install or portable: in that case, you would use `%AppData%\Notepad++\____.xml` and/or `C:\Program Files\Notepad++\____.xml` as the "Destination" location, instead of using a portable directory. See [Configuration Files during Upgrades](../config-files/#configuration-files-during-upgrades)._

4. After updating the config files, then you can exit Notepad++, copy the `notepad++.exe` and `plugins\config\nppPluginList.dll` from the old to the new, and restart Notepad++ to start using your upgraded portable edition.
## Upgrading Plugins

_Note: a similar procedure can be used when you think your installed copy of Notepad++ has themes or syntax highlighting configuration that is missing compared to a fresh install or portable, except you would use `%AppData%\Notepad++\____.xml` and/or `C:\Program Files\Notepad++\____.xml` as the **Old** location, instead of a portable location._
Neither the installer/updater nor manually upgrading your portable edition will affect (nearly all of) your plugins, though upgrading either edition should update the `nppPluginList.dll` used to determine what plugins the **Plugins Admin**. After upgrading Notepad++ by any means, you should go to [**Plugins > Plugins Admin > Updates**](../plugins/#install-using-plugins-admin) to check to see if any of your plugins should be updated. (To clarify: The installer may also update any of the default plugins, including NppExport, NppConverter, and MIME Tools; however, if you don't use the installer, those can be upgraded using **Plugins Admin**'s **Updates** tab, as well.)