Initial release

Author: heckman

.github/workflows/build.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Build
-        run: chmod +x build.sh && ./build.sh
+        run: chmod +x build && ./build
         env:
           APP_VERSION: ${{ github.ref_name }}
 

.gitignore

@@ -1,8 +1,11 @@
 .DS_Store
 /.build
+/bin
 /Packages
 xcuserdata/
 DerivedData/
 .swiftpm/configuration/registries.json
 .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
 .netrc
+/Sources/**/generated*
+.vscode/launch.json

.vscode/launch.json

@@ -5,12 +5,18 @@ import PackageDescription
 let package = Package(
     name: "aliastools",
     targets: [
+        .target(
+            name: "config",
+            path: "Sources/config"
+        ),
         .executableTarget(
             name: "readalias",
+            dependencies: ["config"],
             path: "Sources/readalias"
         ),
         .executableTarget(
             name: "mkalias",
+            dependencies: ["config"],
             path: "Sources/mkalias"
         ),
     ],

Package.swift

@@ -0,0 +1,76 @@
+# Alias Tools
+
+Tools for working with MacOS alias files.
+
+Includes two universal binaries: `readalias` and `mkalias`,
+for resolving and creating alias files.
+
+Neither is very thouroughly tested.
+
+I wrote these utilities for my own needs, on Tahoe 26.2,
+but they likely work on some earlier verions of macOS.
+
+## Installation
+
+Download the [latest release](https://github.com/heckman/macOS-alias-tools/releases/latest)
+and put the two universal binaries somewhere on your `PATH`.
+
+Alternatively, build the binaries from source.
+You will neet to have Command Line Tools (CLT) installed,
+which can be installed with `xcode-select --install`.
+Clone [the repository](https://github.com/heckman/macOS-alias-tools),
+and change your current directory to its root.
+From there, run `./build`.
+This should produce the `readalias` and `mkalias` binaries
+in a `./bin` directory.
+
+## Features
+
+At the moment, `readalias` simply prints the path to the original item,
+and has no options beyond `--help` and `--version`,
+while `mkalias` can be given the `force` ( or `-f`) option
+indicating existing files should be overwritten--by default it
+is non-destructive.
+
+Both respond well to the `--help` option, producing output which
+includes descriptions their various exit codes.
+
+### Future features
+
+By default `mkalias` will fail if the file specified for
+the new alias already exists, adn will overwrite it if the
+destructive behaviour is selected with the `force` (or `-f`) option.
+
+I indend to offer a third behaviour, which, when the
+specified name for the alias is taken, generates a new name
+in the way the Finder does. This might become the default
+behaviour in which case we will need a new a command-line
+option for the fail-on-existing file behaviour.
+
+The renaming strategy is this: Use the same name as the original,
+if avaialbe, otherwise append ` alias` to the name. If that
+is still not unique, then append the smallest integer
+greater than one, separated by a space, sufficient to
+generate a unique name.
+
+### Edge Cases
+
+These tools have only been nominally tested,
+and most edge cases have not been explored:
+
+- Broken Aliases
+- Aliases to unmounted external/network volumes
+- Creating and Alias to another Alias
+
+## Props where due
+
+Prior to writing these two tools,
+I was using _alisma_, by Howard Oakley,
+which you can find on his site
+[eclecticlight.co](https://eclecticlight.co/)
+where he shares a great number of useful tools.
+
+I found myself wrapping _alisma_ in shell functions to
+provide interfaces that felt more natural to me,
+so I decided to use the same system calls as _alisma_
+to make two new programs: `readalias` and `mkalias`.

README.md

@@ -1,37 +1,31 @@
 import Foundation
+import config
 
 // Copyright 2026 Erik Heckman <erik@heckman.ca>
 // SPDX-License-Identifier: MIT
 //
 // mkalias
 
-#if VERSION
-    let version = "mkalias v\(VERSION)"
-#else
-    let version = "mkalias v0.0.1"  // Fallback for local dev
-#endif
-
 let usage = """
-    Usage: mkalias [-f|--force] <path-of-original> <alias-file>
-           mkalias -h|--help
+    Usage: mkalias [-f|--force] [--] <path-of-original> <alias-file>
+           mkalias -h|-v|--help|--version
     """
 let help = """
     Create an alias file that points to the path of an original
     filesystem object.
 
-    Will not overwrite and existing file with <alias-file> unless
-    the `--force` (or `-f`) option is specified.
-
-    On success, create the alias, print nothing, and exit with a
-    zero exit status.
+    Will not overwrite and existing file with <alias-file>
+    unless the `--force` (or `-f`) option is specified.
+    Will never overwrite an existing directory.
 
-    On failure, print an error message to stderr and exit
-    with a non-zero exit status: 2 if the file is not specified,
+    On success, create the alias, print nothing,
+    and exit with a status of zero.
 
-    On failure, print an error message to stderr and exit
-    with a non-zero exit status: 2 if the file is not specified,
-    not found, or not an alias file; 1 if the alias cannot be
-    resolved; 71 on an unexpected file-system error.
+    On failure, print an error message to stderr and terminate
+    with a non-zero exit status: 3 when refusing to clobber
+    something already at <alias-file>; 2 when <path-of-original>
+    does not exist, invalid options are specified, or not enough
+    arguments are provided; 1 when faling to create the alias.
     """
 
 do {
@@ -94,14 +88,14 @@ do {
                     "Error: cannot overwrite directory: \(aliasFile)\n",
                     stderr
                 )
-                exit(2)
+                exit(3)
             }
         } else {
             fputs(
                 "Error: \(isDir.boolValue ? "directory" : "file") exists: \(aliasFile)\n",
                 stderr
             )
-            exit(2)
+            exit(3)
         }
 
     }

Sources/mkalias/main.swift

@@ -1,26 +1,22 @@
 import Foundation
+import config
 
 // Copyright 2026 Erik Heckman <erik@heckman.ca>
 // SPDX-License-Identifier: MIT
 //
 // readalias
 
-#if VERSION
-    let version = "readalias v\(VERSION)"
-#else
-    let version = "readalias v0.0.1"  // Fallback for local dev
-#endif
-
 let usage = """
     Usage: readalias <alias-file>
-           readalias -h|--help
+           readalias -h|-v|--help|--version
     """
 let help = """
     Print the path to the original file of an alias file.
-    On failure, print an error message to stderr and exit
-    with a non-zero exit status: 2 if the file is not specified,
-    not found, or not an alias file; 1 if the alias cannot be
-    resolved; 71 on an unexpected file-system error.
+
+    On failure, print an error message to stderr and exit with
+    a non-zero exit status: 2 if the file is not specified,
+    not found, or not an alias file; 1 if the alias cannot
+    be resolved; 71 on an unexpected file-system error.
     """
 
 do {

Sources/readalias/main.swift

@@ -0,0 +1,32 @@
+#!/bin/zsh
+set -e
+
+cd ${0:h}
+
+print "Cleaning old build files..."
+rm -rf .build bin
+rm -f Sources/config/generated.*(N)
+
+VERSION="${${APP_VERSION:-$(git describe --tags --always --dirty --long || echo 0.0.1)}#v}"
+print "Building universal binaries for version: $VERSION"
+
+mkdir -p Sources/config
+cat <<EOF > Sources/config/generated.version.swift
+// Generated by build script. Should be ignored by Git.
+public let version = "$VERSION"
+EOF
+
+swift build -c release --arch arm64 --arch x86_64
+
+if [[ -t 1 ]]
+then
+	print "\nBuild complete!"
+	print "Location: ${0:A:h}/.build/apple/Products/Release/"
+	ls -lh "${0:A:h}/.build/apple/Products/Release/"{readalias,mkalias}
+	print "Copying binaries to ${0:A:h}/bin/"
+	mkdir -p bin
+	cp \
+		.build/apple/Products/Release/readalias \
+		.build/apple/Products/Release/mkalias \
+		bin
+fi