#1788: Created a commandlet to simulate the behaviour of ln -s

.editorconfig

@@ -18,7 +18,7 @@ ij_wrap_on_typing = false
 
 [*.properties]
 ij_properties_align_group_field_declarations = false
-ij_properties_keep_blank_lines = true
+ij_properties_keep_blank_lines = false
 ij_properties_key_value_delimiter = equals
 ij_properties_spaces_around_key_value_delimiter = false
 
@@ -354,4 +354,4 @@ ij_yaml_keep_line_breaks = true
 ij_yaml_sequence_on_new_line = false
 ij_yaml_space_before_colon = false
 ij_yaml_spaces_within_braces = true
-ij_yaml_spaces_within_brackets = true
+ij_yaml_spaces_within_brackets = true

.gitignore

@@ -14,7 +14,6 @@
 !.anyedit.properties
 !.ide.properties
 !.templateengine
-!.github
 target/
 eclipse-target/
 generated/

CHANGELOG.adoc

@@ -20,6 +20,7 @@ Release with new features and bugfixes:
 * https://github.com/devonfw/IDEasy/issues/1834[#1834]: Fix fix-vpn-tls-problem NullPointerException
 * https://github.com/devonfw/IDEasy/issues/1724[#1724]: Add gui commandlet
 * https://github.com/devonfw/IDEasy/issues/1853[#1853]: Add ARM releases for VSCode on Mac
+* https://github.com/devonfw/IDEasy/issues/1788[#1788]: Add Commandlet to create links
 * https://github.com/devonfw/IDEasy/issues/797[#797]: Use system unzip on macOS to preserve symlinks in ZIP extraction
 * https://github.com/devonfw/IDEasy/issues/1723[#1723]: Add commandlet for GitHub Copilot CLI
 * https://github.com/devonfw/IDEasy/issues/1880[#1880]: Reinstall all plugins for IDE in force mode

cli/src/main/java/com/devonfw/tools/ide/commandlet/CommandletManagerImpl.java

@@ -110,6 +110,7 @@ public CommandletManagerImpl(IdeContext context) {
     add(new StatusCommandlet(context));
     add(new RepositoryCommandlet(context));
     add(new UninstallCommandlet(context));
+    add(new LnCommandlet(context));
     add(new UpdateCommandlet(context));
     add(new UpgradeSettingsCommandlet(context));
     add(new CreateCommandlet(context));

cli/src/main/java/com/devonfw/tools/ide/commandlet/LnCommandlet.java

@@ -0,0 +1,91 @@
+package com.devonfw.tools.ide.commandlet;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import com.devonfw.tools.ide.cli.CliException;
+import com.devonfw.tools.ide.context.IdeContext;
+import com.devonfw.tools.ide.io.PathLinkType;
+import com.devonfw.tools.ide.property.FlagProperty;
+import com.devonfw.tools.ide.property.PathProperty;
+
+/**
+ * // * Link creation {@link Commandlet} similar to {@code ln -s}.
+ * <p>
+ * It tries to create a true symbolic link first. On Windows, symlink creation may be restricted due to missing privileges. In that case, IDEasy will create a
+ * hard link as an alternative (file-only, same volume) to avoid the Git-Bash behavior of silently copying files.
+ */
+public final class LnCommandlet extends Commandlet {
+
+  /** Grammar token {@code -s} (optional). */
+  public final FlagProperty symbolic;
+
+  /** Grammar token {@code -r} (optional). */
+  public final FlagProperty relative;
+
+  /** The source path to link to. */
+  public final PathProperty source;
+
+  /** The target path (the created link). */
+  public final PathProperty link;
+
+  /**
+   * The constructor.
+   *
+   * @param context the {@link IdeContext}.
+   */
+  public LnCommandlet(IdeContext context) {
+
+    super(context);
+    addKeyword(getName());
+
+    this.symbolic = add(new FlagProperty("--symbolic", false, "-s"));
+    this.relative = add(new FlagProperty("--relative", false, "-r"));
+    this.source = add(new PathProperty("", true, "source", true));
+    this.link = add(new PathProperty("", true, "link", false));
+  }
+
+  @Override
+  public String getName() {
+
+    return "ln";
+  }
+
+  @Override
+  public boolean isIdeRootRequired() {
+
+    return false;
+  }
+
+  @Override
+  public boolean isIdeHomeRequired() {
+
+    return false;
+  }
+
+  @Override
+  public boolean isWriteLogFile() {
+
+    return false;
+  }
+
+  @Override
+  protected void doRun() {
+
+    Path cwd = this.context.getCwd();
+    if (cwd == null) {
+      throw new CliException("Missing current working directory!");
+    }
+
+    Path sourcePath = cwd.resolve(this.source.getValue()).normalize();
+    Path linkPath = cwd.resolve(this.link.getValue()).normalize();
+    boolean relative = this.relative.isTrue();
+
+    if (!Files.exists(sourcePath)) {
+      throw new CliException("Source does not exist: " + sourcePath);
+    }
+
+    PathLinkType linkType = this.symbolic.isTrue() ? PathLinkType.SYMBOLIC_LINK : PathLinkType.HARD_LINK;
+    this.context.getFileAccess().link(sourcePath, linkPath, relative, linkType);
+  }
+}

cli/src/main/java/com/devonfw/tools/ide/io/FileAccess.java

@@ -124,8 +124,8 @@ default void hardlink(Path source, Path link) {
   }
 
   /**
-   * Creates a link. If the given {@code link} already exists and is a symbolic link or a Windows junction, it will be replaced. In case of missing privileges,
-   * Windows mklink may be used as fallback, which must point to absolute paths. In such case the {@code relative} flag will be ignored.
+   * Creates a link. If the given {@code link} already exists and is a symbolic link or a Windows junction, it will be replaced. In case of missing
+   * privileges, Windows mklink may be used as fallback, which must point to absolute paths. In such case the {@code relative} flag will be ignored.
    *
    * @param source the source {@link Path} to link to, may be relative or absolute.
    * @param link the destination {@link Path} where the link shall be created pointing to {@code source}.

cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java

@@ -424,24 +424,22 @@ private void copyRecursive(Path source, Path target, FileCopyMode mode, PathCopy
   }
 
   /**
-   * Deletes the given {@link Path} if it is a symbolic link or a Windows junction. And throws an {@link IllegalStateException} if there is a file at the given
-   * {@link Path} that is neither a symbolic link nor a Windows junction.
+   * Deletes the given {@link Path} if it is a symbolic link or a Windows junction or hard link. And throws an {@link IllegalStateException} if it fails to
+   * delete the file at the given {@link Path}.
    *
    * @param path the {@link Path} to delete.
    */
   private void deleteLinkIfExists(Path path) {
 
     boolean isJunction = isJunction(path); // since broken junctions are not detected by Files.exists()
-    boolean isSymlink = Files.exists(path, LinkOption.NOFOLLOW_LINKS) && Files.isSymbolicLink(path);
+    boolean exists = Files.exists(path, LinkOption.NOFOLLOW_LINKS);
 
-    assert !(isSymlink && isJunction);
-
-    if (isJunction || isSymlink) {
-      LOG.info("Deleting previous " + (isJunction ? "junction" : "symlink") + " at " + path);
+    if (isJunction || exists) {
+      LOG.info("Deleting previous link or file at " + path);
       try {
         Files.delete(path);
       } catch (IOException e) {
-        throw new IllegalStateException("Failed to delete link at " + path, e);
+        throw new IllegalStateException("Failed to delete link or file at " + path, e);
       }
     }
   }
@@ -545,7 +543,7 @@ public void link(Path source, Path link, boolean relative, PathLinkType type) {
       if (type == PathLinkType.SYMBOLIC_LINK) {
         Files.createSymbolicLink(finalLink, finalSource);
       } else if (type == PathLinkType.HARD_LINK) {
-        Files.createLink(finalLink, finalSource);
+        createHardLink(finalSource, finalLink);
       } else {
         throw new IllegalStateException("" + type);
       }
@@ -555,7 +553,13 @@ public void link(Path source, Path link, boolean relative, PathLinkType type) {
             "Due to lack of permissions, Microsoft's mklink with junction had to be used to create a Symlink. See\n"
                 + "https://github.com/devonfw/IDEasy/blob/main/documentation/symlink.adoc for further details. Error was: "
                 + e.getMessage());
-        mklinkOnWindows(finalSource, absoluteSource, finalLink, type, relative);
+
+        try {
+          mklinkOnWindows(finalSource, absoluteSource, finalLink, type, relative);
+        } catch (IllegalStateException mkEx) {
+          LOG.info("Creating a hard link as a fallback for the failed mklink attempt.");
+          createHardLink(absoluteSource, finalLink);
+        }
       } else {
         throw new RuntimeException(e);
       }
@@ -564,6 +568,22 @@ public void link(Path source, Path link, boolean relative, PathLinkType type) {
     }
   }
 
+
+  /**
+   * Creates a hard link at {@code link} pointing to {@code source}.
+   *
+   * @param source the {@link Path} the hard link will point to.
+   * @param link the {@link Path} where to create the hard link.
+   */
+  void createHardLink(Path source, Path link) {
+    try {
+      Files.createLink(link, source);
+      LOG.trace("Created hard link at {} pointing to {}", link, source);
+    } catch (IOException e) {
+      throw new RuntimeException("Failed to create a hardlink for " + source + " at " + link, e);
+    }
+  }
+
   @Override
   public Path getPathStart(Path path, int nameEnd) {
 
@@ -748,13 +768,12 @@ public void extractZip(Path file, Path targetDir) {
   /**
    * Extracts a ZIP archive to the given target directory using Java (commons-compress {@link ZipFile}).
    * <p>
-   * Symlinks are handled in a two-phase approach: all regular files and directories are written first, and symlinks are
-   * collected and created afterwards. This ensures every symlink target already exists on disk before the link is made.
+   * Symlinks are handled in a two-phase approach: all regular files and directories are written first, and symlinks are collected and created afterwards. This
+   * ensures every symlink target already exists on disk before the link is made.
    * <p>
-   * {@link ZipFile} is used instead of {@link org.apache.commons.compress.archivers.zip.ZipArchiveInputStream} because
-   * Unix file attributes (needed for symlink detection and permission restoration) are stored in the ZIP central
-   * directory at the end of the file. A sequential stream only sees the local file headers, where external attributes
-   * are always zero. {@link ZipFile} reads the central directory via random access, so attributes are always correct.
+   * {@link ZipFile} is used instead of {@link org.apache.commons.compress.archivers.zip.ZipArchiveInputStream} because Unix file attributes (needed for symlink
+   * detection and permission restoration) are stored in the ZIP central directory at the end of the file. A sequential stream only sees the local file headers,
+   * where external attributes are always zero. {@link ZipFile} reads the central directory via random access, so attributes are always correct.
    *
    * @param file the ZIP archive to extract.
    * @param targetDir the directory to extract into.
@@ -807,8 +826,8 @@ private void extractZipWithJava(Path file, Path targetDir) {
   /**
    * Returns the Unix file mode stored in the external file attributes of the given ZIP entry.
    * <p>
-   * The ZIP specification stores platform-specific metadata in a 32-bit external-attributes field. When the archive was
-   * created on a Unix system the layout is:
+   * The ZIP specification stores platform-specific metadata in a 32-bit external-attributes field. When the archive was created on a Unix system the layout
+   * is:
    * <ul>
    *   <li>bits 31–16 (upper 16 bits): Unix file mode (same bit layout as {@code stat.st_mode})</li>
    *   <li>bits 15–0 (lower 16 bits): MS-DOS attributes (read-only, hidden, …)</li>
@@ -828,8 +847,7 @@ private static int getZipUnixMode(ZipArchiveEntry entry) {
   /**
    * Returns {@code true} if the given ZIP entry represents a symbolic link.
    * <p>
-   * Unix file modes encode the file type in the top 4 bits (bits 15–12) of the mode word. The possible file-type
-   * values are defined in {@code <sys/stat.h>}:
+   * Unix file modes encode the file type in the top 4 bits (bits 15–12) of the mode word. The possible file-type values are defined in {@code <sys/stat.h>}:
    * <ul>
    *   <li>{@code 0x8000} – regular file ({@code S_IFREG})</li>
    *   <li>{@code 0x4000} – directory ({@code S_IFDIR})</li>
@@ -849,8 +867,8 @@ private static boolean isZipSymlink(ZipArchiveEntry entry) {
   /**
    * Applies Unix file permissions stored in a ZIP entry to the extracted file.
    * <p>
-   * Permissions are only applied on non-Windows systems because POSIX permission bits have no equivalent on Windows.
-   * If the entry carries no Unix attributes (mode is {@code 0}), the call is a no-op.
+   * Permissions are only applied on non-Windows systems because POSIX permission bits have no equivalent on Windows. If the entry carries no Unix attributes
+   * (mode is {@code 0}), the call is a no-op.
    *
    * @param entry the source ZIP entry carrying the Unix mode.
    * @param target the extracted file whose permissions should be updated.
@@ -1329,7 +1347,6 @@ private long getFileSize(Path file) {
   }
 
 
-
   @Override
   public Path findExistingFile(String fileName, List<Path> searchDirs) {
 

cli/src/main/resources/nls/Help.properties

@@ -85,6 +85,8 @@ cmd.list-editions=List the available editions of the selected tool.
 cmd.list-editions.detail=To list all available editions of e.g. 'intellij' simply type: 'ide list-editions intellij'.
 cmd.list-versions=List the available versions of the selected tool.
 cmd.list-versions.detail=To list all available versions of e.g. 'intellij' simply type: 'ide list-versions intellij'.
+cmd.ln=Create a symbolic or hard link.
+cmd.ln.detail=Creates a link similar to the command "ln" but working cross-platform (unlike in git-bash on Windows that typically only creates a copy).
 cmd.mvn=Tool commandlet for Maven (Build-Tool).
 cmd.mvn.detail=Apache Maven is a build automation and dependency management tool for Java projects. Detailed documentation can be found at https://maven.apache.org/guides/index.html
 cmd.nest=Tool commandlet for Nest CLI.
@@ -167,9 +169,11 @@ opt.--no-colors=disable colored log messages.
 opt.--offline=enable offline mode (skip updates or git pull, fail downloads or git clone).
 opt.--privacy=enable GDPR-compliant console output.
 opt.--quiet=disable info logging (only log success, warning or error).
+opt.--relative=use relative paths.
 opt.--skip-repositories=skip the setup of repositories.
 opt.--skip-tools=skip the installation/update of tools.
 opt.--skip-updates=disables tool updates if the configured versions match the installed versions.
+opt.--symbolic=Create a symbolic link instead of a hard link (default).
 opt.--trace=enable trace logging.
 opt.--version=Print the IDE version and exit.
 options.global=Global options:
@@ -180,8 +184,10 @@ val.args=The commandline arguments to pass to the tool.
 val.cfg=Selection of the configuration file (settings | home | conf | workspace).
 val.commandlet=The selected commandlet (use 'ide help' to list all commandlets).
 val.edition=The tool edition.
+val.link=The path where the link is created.
 val.plugin=The plugin to select
 val.settingsRepository=The settings git repository with the IDEasy configuration for the project.
+val.source=The source path the link points to (existing file or directory).
 val.tool=The tool commandlet to select.
 val.version=The tool version.
 values=Values:

cli/src/main/resources/nls/Help_de.properties

@@ -85,6 +85,8 @@ cmd.list-editions=Listet die verfügbaren Editionen des selektierten Werkzeugs a
 cmd.list-editions.detail=Um alle verfügbaren Editionen von z.B. 'intellij' aufzulisten, geben Sie einfach 'ide list-editions intellij' in die Konsole ein.
 cmd.list-versions=Listet die verfügbaren Versionen des selektierten Werkzeugs auf.
 cmd.list-versions.detail=Um alle verfügbaren Versionen von z.B. 'intellij' aufzulisten, geben Sie einfach 'ide list-versions intellij' in die Konsole ein.
+cmd.ln=Erstellt einen symbolischen oder harten Link
+cmd.ln.detail=Erstellt einen Link wie das Kommando "ln" jedoch plattform-übergreifend (anders als in Git-Bash unter Windows wo typischerweise nur eine Kopie erstellt wird).
 cmd.mvn=Werkzeug Kommando für Maven (Build-Werkzeug).
 cmd.mvn.detail=Apache Maven ist ein Build-Automatisierungs- und Abhängigkeitsverwaltungstool für Java-Projekte. Detaillierte Dokumentation ist zu finden unter https://maven.apache.org/guides/index.html
 cmd.nest=Werkzeug Kommando für Nest CLI.
@@ -167,9 +169,11 @@ opt.--no-colors=Deaktiviert farbige Log-Meldungen.
 opt.--offline=Aktiviert den Offline-Modus (Überspringt Aktualisierungen oder git pull, schlägt fehl bei Downloads or git clone).
 opt.--privacy=Aktiviert DSGVO konforme Konsolenausgaben.
 opt.--quiet=Deaktiviert Info Logging ( nur success, warning und error).
+opt.--relative=Relative Pfade verwenden.
 opt.--skip-repositories=Überspringt die Einrichtung der Repositories.
 opt.--skip-tools=Überspringt die Installation/Aktualisierung der Tools.
 opt.--skip-updates=Deaktiviert Aktualisierungen von Tools wenn die installierten Versionen mit den konfigurierten Versionen übereinstimmen.
+opt.--symbolic=Erstellt einen symbolischen Link anstelle eines Hardlinks (Standard).
 opt.--trace=Aktiviert Trace-Ausgaben (detaillierte Fehleranalyse).
 opt.--version=Zeigt die IDE Version an und beendet das Programm.
 options.global=Globale Optionen:
@@ -180,8 +184,10 @@ val.args=Die Kommandozeilen-Argumente zur Übergabe an das Werkzeug.
 val.cfg=Auswahl der Konfigurationsdatei (settings | home | conf | workspace).
 val.commandlet=Das ausgewählte Commandlet ("ide help" verwenden, um alle Commandlets aufzulisten).
 val.edition=Die Werkzeug Edition.
+val.link=Pfad des zu erstellenden Links.
 val.plugin=Die zu selektierende Erweiterung.
 val.settingsRepository=Das settings git Repository mit den IDEasy Einstellungen für das Projekt.
+val.source=Ziel des Links (existierender Pfad).
 val.tool=Das zu selektierende Werkzeug Kommando.
 val.version=Die Werkzeug Version.
 values=Werte: