en-us/about_SYMLINK.help.txt

TOPIC
    about_Symlink
 
     
SHORT DESCRIPTION
    Symlink is a module designed to help manage symbolic links on the
    filesystem, by improving the user experience and making it easier to create,
    modify, and remove symlinks.
     
     
OVERVIEW
 1. This module manages symlink definitions (properties defined in a database)
    and the actual symlink items on the filesystem. When creating a new symlink,
    you are creating a definition, which always exists unless removed, and an
    item on the filesystem, which may or may not exist.
     
     
 2. When specifying any paths for any commands, you can include environment
    variables in the %VARIABLE% notation. These will then get expanded when
    necessary, assuming the variable is actually defined on the system.
     
  ! If the environment variable is modified, you can update the symbolic-links
    to point to the new path by running the 'Build-Symlink' command.
     
     
 3. The commands in this module operate on [Symlink] objects. The objects
    retrieved by the 'Get-Symlink' command can be piped to:
        - Build-Symlink
        - Remove-Symlink
        - Set-Symlink
     
    There are also methods on the [Symlink] object which can be run. To see a
    list of these methods/properties, run:
     
        PS C:\> Get-Symlink -Name "data" | Get-Member
     
     
 4. This module has custom-defined formatting outputs for:
        ------- -----
        Command Alias
        ------- -----
        Format-List fl
        Format-Table ft
        Format-Custom fc
        Format-Wide fw
     
    The 'Format-Custom' & 'Format-List' views contain the largest amount
    of information regarding the symlink.
     
     
 5. A font with ligatures is recommended for the best and clearest visual
    display.
     
    When running in the 'Windows Terminal', fancy formatting is supported.
    This formatting uses colours and emojis to make the output even clearer
    and easier to read/scan through.
     
     
     
CREATING A SYMLINK
 1. To create a new symlink, run:
     
        PS C:\> New-Symlink -Name "data" -Path ~\Documents\Data -Target D:\Files
     
    This command will create a new symlink definition, named "data", and a
    symbolic-link located in the user's document folder under a folder also
    named "data", pointing to a folder on the D:\ drive.
     
    -Name
        The name/identifier of this symlink (must be unique).
     
    -Path
        The location of the symbolic-link item on the filesystem. If any parent
        folders defined in this path don't exist, they will be created.
     
    -Target
        The location which the symbolic-link will point to. This defines whether
        the link points to a folder or file.
     
    OPTIONAL PARAMETERS
     
    -CreationCondition
        A scriptblock which decides whether the symbolic-link is actually
        created or not. This does not affect the creation of the symlink
        definition within the database. For more details about this, see the
        SCRIPTBLOCK section down below.
     
    -DontCreateItem
        Skips the creation of the symbolic-link item on the filesystem.
     
     
     
RETRIEVING A SYMLINK
 1. To retrieve the details of a symlink, run:
     
        PS C:\> Get-Symlink -Name "data"
     
    This command will retrieve the details of the symlink named "data", and
    output the information to the screen.
     
    -Names
        The name(s)/identifier(s) of the symlinks to retrieve. Multiple values
        are accepted to retrieve the data of multiple links.
      ! This parameter tab-completes valid symlink names.
     
     
 2. To retrieve the details of multiple symlinks, run:
     
        PS C:\> Get-Symlink -Names "data","files"
     
    [OR]PS C:\> "data","files" | Get-Symlink -Names
     
    This command will retrieve the details of the symlinks named "data" and
    "files", and output both to the screen, one after another.
  ! You can pipe the names to this command instead.
     
     
 3. To retrieve the details of all symlinks, run:
     
        PS C:\> Get-Symlink -All
     
    This command will retrieve the details of all symlinks, and output the
    information to the screen.
     
    -All
        Specifies to retrieve details for all symlinks.
     
     
     
CHANGING A SYMLINK
 1. To change the name/identifier of a symlink, run:
     
        PS C:\> Set-Symlink -Name "data" -Property "Name" -Value "WORK"
     
    This command will change the name of the symlink called "data", to the new
    name of "WORK". From now on, there is no symlink named "data" anymore.
     
    -Name
        The name/identifier of the symlink to edit.
      ! This parameter tab-completes valid symlink names.
     
    -Property
        The property to edit on this symlink. Valid values include:
        "Name", "Path", "Target", and "CreationCondition".
      ! This parameter tab-completes valid options.
     
    -Value
        The new value for the property to take.
     
     
 2. To change any other properties of a symlink, run:
     
        PS C:\> Set-Symlink -Name "data" -Property <...> -Value <...>
     
    The new value will undergo the same checks and validations as when creating
    a new symlink using the 'New-Symlink' command.
     
     
 3. Changing the -Path property of a symlink, will result in the symbolic-link
    item being deleted from its original location, and re-created at the new
    location.
     
    Changing the -Target property of a symlink, will result in the
    symbolic-link item being deleted and re-created in the same location, but
    now pointing to the new target.
     
  ! Changing the -CreationCondition will not change the existence of the
    symbolic-link item.
     
     
     
REMOVING A SYMLINK
 1. To remove a symlink, run:
     
        PS C:\> Remove-Symlink -Name "data"
         
    This command will remove a symlink definition, named "data", and delete the
    symbolic-link item from the filesystem.
     
    -Names
        The name(s)/identifier(s) of the symlinks to remove. Multiple values
        are accepted to remove multiple links at once.
      ! This parameter tab-completes valid symlink names.
         
    OPTIONAL PARAMETERS
     
    -DontDeleteItem
        Skips the deletion of the symbolic-link item on the filesystem. The
        link will remain afterwads.
     
     
 2. To remove multiple symlinks, run:
     
        PS C:\> Remove-Symlink -Names "data","files"
         
    [OR]PS C:\> "data","files" | Remove-Symlink -Names
     
    This command will remove the symlink definitions named "data" and "files",
    and delete the symbolic-link items of both.
  ! You can pipe the names to this command instead.
     
     
     
BUILDING/UPDATING SYMLINKS
 1. To create all symbolic-link items on the filesystem, run:
     
        PS C:\> Build-Symlink -All
     
    This command will go through all of the symlink definitions, and create
    the symbolic-link items on the filesystem, assuming the creation condition
    for them is met.
     
    -All
        Specifies to create all symlinks.
     
     
 2. To create only certain symbolic-links on the filesystem, run:
     
        PS C:\> Build-Symlink -Names "data","files"
         
    [OR]PS C:\> "data","files" | Build-Symlink -Names
     
    This command will only go through the symlinks given in, and create the
    items on the filesystem.
  ! You can pipe the names to this command instead.
     
    -Names
        The name(s)/identifier(s) of the symlinks to create. Multiple values
        are accepted to build multiple links at once.
      ! This parameter tab-completes valid symlink names.
     
     
 3. This command can be used if you're given a database file, and want to
    create the symbolic-link items for the first time.
     
    This command can also be used to update existing items. Whilst the
    'Set-Symlink' command will update the symbolic-link items itself, changing
    an environment variable will not. If you change the value of an environment
    variable, you can run this command to "re-build" all of the symbolic-link
    items and either change their location or their target (if either have
    a variable in the path).
     
     
     
CREATION CONDITION SCRIPTBLOCK
    When creating a new symlink, or by setting the property using the
    'Set-Symlink' command, you can define a 'Creation Condition' scriptblock.
    This scriptblock gets evaluated when the actual symbolic-link item is
    being created on the filesystem, and it determines whether it should or
    should not be created.
     
     
    For example, the scriptblock could check for the machine name, and only
    create the symlink on certain computers.
     
        The scriptblock would look like:
         
            {
                if ($env:COMPUTERNAME -eq "specific-name")
                    { return $true } else { return $false }
            }
         
        Then when either the 'Build-Symlink' command, or the
        [Symlink].CreateFile() method are run, this scriptblock will be
        evaluated and decide whether the creation should go through or not.
         
      ! The scriptblock must return $TRUE or $FALSE values from all control
        paths. This cannot be checked by the commands, so you must make sure
        of this.
     
     
    This allows the use of the same database file across multiple machines for
    instance, even if the individual machines have slightly varying requirements
    regarding which symlinks are actually needed on the filesystem.
     
     
     
OTHER
    The module stores all data in %APPDATA%\Powershell\Symlink
    It is advised to **not** manually modify any files within this directory as
    it could cause unintended consequences.
     
     
     
KEYWORDS
    Symlink
    Symbolic Link
    Management