IDEasy has build-in functionality to configure your IDE.
This allows to merge and manage complex configurations.
The easiest way is that you do not care.
When you launch the IDE of your choice (e.g. via ide eclipse, ide intellij, ide vscode), this will happen automatically.
For every supported IDE we distinguish the following file structures:
-
workspace
The actual configuration location of the tool itself. We configure the tool to relocate this to a specific workspace (so by default
workspaces/main/). -
setup
-
update
A configuration location with the configuration used to update and override:
settings/«ide»/workspace/update. Contains settings that are overridden with every update and enforced for every team member. If a developer manually changes such configuration setting, it will be reset on the next time the IDE gets started.
The configurator will recursively traverse the directory structure of 2. and 3. together.
For each located file «relative-path»/«file» it will create or update 1. according to the following rules:
-
If
«relative-path»/«file»is present in 1. (workspace) it will be loaded and used as basis. -
Otherwise if
«relative-path»/«file»is present in 2. (setup) it will be loaded and used as basis. -
If
«relative-path»/«file»is present in 3. (update) it will be loaded and merged with the current basis. -
Variables in the from
$[«variable-name»]get resolved if«variable-name»is defined. Please note that in devonfw-ide the syntax was${«variable-name»}and legacy support for this can be enabled/disabled. However, this clashes with the variable syntax already used by IDE tools like Eclipse, IntelliJ, etc. Therefore this was changed in IDEasy and the new syntax should be used to avoid problems. -
If this caused any change the result is written to
«relative-path»/«file»in 1. (workspace).
In other words this means:
-
When your workspace configuration is initially created, 1. is empty. Hence, settings from 2. are used and merged with 3.
-
Settings in 2. are therefore used as initial defaults and suggestions but can be changed by the end-user (developer). Hence, use 2. for things such as themes, UI tweaks, etc. Once the workspace is configured 2. typically is not relevant anymore.
-
Settings in 3. are applied on every update. By default this happens every time you start your IDE, these settings are managed by the
settingsand in control of theconfigurator. If the user modifies such settings and reopens his IDE his changes are reverted. Hence, use 3. for things such as code-formatters, compiler options, paths to tools shipped withIDEasy, etc. that should be consistent and homogeneous for every team-member.
The settings for your ide are located in settings/«ide»/workspace where you find the setup (2.) and update (3.) sub-folders.
E.g. for Eclipse the most relevant settings can be found in settings/eclipse/workspace/update/.metadata/.plugins/org.eclipse.core.runtime/.settings.
Of course you could manually edit these settings with a text editor.
However, this requires a lot of knowledge.
As we want to provide a great user-experience with IDEasy you can also do the following:
-
Launch the IDE to configure (e.g.
ide intellij). -
In case of a non-trivial tweak you may first create a backup copy of the IDE configuration in
workspaces/main(for IntelliJ in.intelijand.ideasubfolders and for eclipse in.metadata). -
Do the desired modification of the configuration via the GUI of your IDE (Preferences dialog).
-
Exit your IDE and wait untill it is shutdown
-
Call
ws-reversecommand for your IDE (e.g.ide intellij ws-reverse) - ensure you do this in the same workspace where you launched and tweaked the config (without intermediatecdcommands). -
Review the changes to your settings with a git and diff tool of your choice (e.g. call
git diff). -
If all looks as expected commit these changes and push them - consider using a feature branch and ask a colleague to test these changes before you apply this to the main branch.
-
In case you could not find the expected changes, you may have tweaked a property that is not yet managed. Therefore, you can try again with
ws-reverse-addinstead ofws-reverse(e.g.ide eclipse ws-reverse-add) but be aware to revert undesired changes. Be sure not to add undesired settings that should not be managed. -
In case your changes are in an entirely new configuration file that is currently not managed, you can simply diff the current workspace folder with the previously created backup copy using a recursive diff tool (such as winmerge or maybe just
diff -R). Once you figured out the relevant change from that diff, you can manually apply it to the according«ide»/workspace/updatefolder in youride-settingsgit repository.
The XML Merger in IDEasy is a tool designed to merge XML documents using different strategies.
It allows control over how elements are combined, overridden, or kept intact during the merge process.
This merger is mainly used to merge incoming IDE configuration files changes from ide-settings into the workspace.
The merger supports three main strategies, which can be specified for each element using the merge:strategy attribute:
-
COMBINE: This strategy combines the source and target elements. It overrides text nodes and attributes, and recursively applies the process to child elements. If a source element exists in the target document, they are combined; otherwise, the source element is appended. -
OVERRIDE: This strategy replaces the target element with the source element, without considering child elements. If the element exists in the target, it is overridden; otherwise, it is appended. -
KEEP: This strategy keeps the existing target element intact if the source element exists in the target document. If the source element doesn’t exist in the target, it is appended.
It is not necessary to provide a merge:strategy for each element, strategies are inherited to child elements.
So you only need to configure a merge:strategy for an element if it shall be different from its parent.
The default if nothing is configured for the root element is COMBINE.
Elements are identified and matched using the merge:id attribute.
This attribute is used to determine which elements in the source and target documents correspond to each other.
The merge:id can be set to one of the following:
-
An attribute name prefixed with @ (e.g.,
@id,@name) -
The string
name()to match by element name -
The string
text()to match by text content -
A full XPath expression (e.g.,
../element[@attr=’value’]or/root/element[@attr=’value’])
For each first occurrence of an element the provided value of merge:id is saved and then later used for elements with the same name (qualified tag name), so it is enough to provide a merge:id for each element only once, unless you want it to change later in the document.
If no merge:id was provided, the merger uses the following strategy as default:
-
If no attributes are present at all, use the qualified tag name
-
If an
idattribute is present use it (@id) -
Otherwise if a
nameattribute is present use it (@name) -
Otherwise you will get an error and need to adjust your template.
In Eclipse and IntelliJ, elements are usually identified by either the id or name attribute, which means we could just omit merge:id in these cases.
In order to use this tool, it is necessary to declare the merge namespace in the root element like this:
<root xmlns:merge="https://github.com/devonfw/IDEasy/merge">
// some elements
</root>