Define remote path with abra app new

This PR routes a request from

abra app new <git-url>

to add a RECIPE= line to the .env file. Like this,
if the abra configuration is on git, and used in other
places, also remote recipes get correctly updated.

Makefile

@@ -1,5 +1,5 @@
 ABRA         := ./cmd/abra
-XGETTEXT     := ./bin/xgettext-go
+XGETTEXT     := xgettext-go
 COMMIT       := $(shell git rev-list -1 HEAD)
 GOPATH       := $(shell go env GOPATH)
 GOVERSION    := 1.26
@@ -62,8 +62,8 @@ update-po:
 	done
 
 .PHONY: update-pot
-update-pot: $(XGETTEXT)
-	@${XGETTEXT} \
+update-pot: xgettext-go
+	@$(XGETTEXT) \
 		-o pkg/i18n/locales/$(DOMAIN).pot \
 		--keyword=i18n.G \
 		--keyword-ctx=i18n.GC \
@@ -71,10 +71,10 @@ update-pot: $(XGETTEXT)
 		--add-comments-tag="translators" \
 		$$(find . -name "*.go" -not -path "*vendor*" | sort)
 
-${XGETTEXT}:
-	@mkdir -p ./bin && \
-	wget -O ./bin/xgettext-go https://git.coopcloud.tech/toolshed/xgettext-go/raw/branch/main/xgettext-go && \
-	chmod +x ./bin/xgettext-go
+.PHONY: xgettext-go
+xgettext-go:
+	@command -v $(XGETTEXT) >/dev/null 2>&1 || \
+		go install git.coopcloud.tech/toolshed/xgettext-go@latest
 
 .PHONY: update-pot-po-metadata
 update-pot-po-metadata:

cli/app/deploy.go

@@ -114,7 +114,9 @@ checkout as-is. Recipe commit hashes are also supported as values for
 		}
 
 		if !isChaosCommit && !tagcmp.IsParsable(toDeployVersion) {
-			log.Fatal(i18n.G("unable to parse deploy version: %s", toDeployVersion))
+			log.Warnf(i18n.G("version '%s' is not a semver tag; deploying as chaos", toDeployVersion))
+			isChaosCommit = true
+			internal.Chaos = true
 		}
 
 		if !internal.Chaos {
@@ -151,11 +153,12 @@ checkout as-is. Recipe commit hashes are also supported as values for
 
 		stackName := app.StackName()
 		deployOpts := stack.Deploy{
-			Composefiles: composeFiles,
-			Namespace:    stackName,
-			Prune:        false,
-			ResolveImage: stack.ResolveImageAlways,
-			Detach:       false,
+			Composefiles:     composeFiles,
+			Namespace:        stackName,
+			Prune:            false,
+			ResolveImage:     stack.ResolveImageAlways,
+			Detach:           false,
+			SendRegistryAuth: true,
 		}
 		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)
 		if err != nil {

cli/app/new.go

@@ -32,6 +32,18 @@ deploy <domain>" to do so.
 You can see what recipes are available (i.e. values for the [recipe] argument)
 by running "abra recipe ls".
 
+In addition to short catalogue names, [recipe] also accepts arbitrary git
+URLs to use a recipe from outside the catalogue (e.g. a fork or work in
+progress). Any of these forms is accepted:
+
+  abra app new git.example.com/user/recipe
+  abra app new https://git.example.com/user/recipe
+  abra app new git@git.example.com:user/recipe
+
+In that case a RECIPE=<canonical name> line is written to the app's .env
+file so a subsequent "abra app deploy" (on this or another machine) will
+re-fetch the recipe from the same git source.
+
 Recipe commit hashes are supported values for "[version]".
 
 Passing the "--secrets/-S" flag will automatically generate secrets for your
@@ -289,9 +301,13 @@ func createSecrets(cl *dockerClient.Client, secretsConfig map[string]secret.Secr
 // ensureDomainFlag checks if the domain flag was used. if not, asks the user for it/
 func ensureDomainFlag(recipe recipePkg.Recipe, server string) error {
 	if appDomain == "" && !internal.NoInput {
+		shortName := recipe.Name
+		if i := strings.LastIndex(shortName, "/"); i >= 0 {
+			shortName = shortName[i+1:]
+		}
 		prompt := &survey.Input{
 			Message: i18n.G("Specify app domain"),
-			Default: fmt.Sprintf("%s.%s", recipe.Name, server),
+			Default: fmt.Sprintf("%s.%s", shortName, server),
 		}
 		if err := survey.AskOne(prompt, &appDomain); err != nil {
 			return err
@@ -302,6 +318,10 @@ func ensureDomainFlag(recipe recipePkg.Recipe, server string) error {
 		return errors.New(i18n.G("no domain provided"))
 	}
 
+	if strings.ContainsAny(appDomain, "/\\") {
+		return errors.New(i18n.G("invalid domain '%s': must not contain '/' or '\\'", appDomain))
+	}
+
 	return nil
 }
 

cli/app/rollback.go

@@ -166,11 +166,12 @@ beforehand. See "abra app backup" for more.`),
 
 		stackName := app.StackName()
 		deployOpts := stack.Deploy{
-			Composefiles: composeFiles,
-			Namespace:    stackName,
-			Prune:        false,
-			ResolveImage: stack.ResolveImageAlways,
-			Detach:       false,
+			Composefiles:     composeFiles,
+			Namespace:        stackName,
+			Prune:            false,
+			ResolveImage:     stack.ResolveImageAlways,
+			Detach:           false,
+			SendRegistryAuth: true,
 		}
 
 		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)

cli/app/upgrade.go

@@ -178,11 +178,12 @@ beforehand. See "abra app backup" for more.`),
 
 		stackName := app.StackName()
 		deployOpts := stack.Deploy{
-			Composefiles: composeFiles,
-			Namespace:    stackName,
-			Prune:        false,
-			ResolveImage: stack.ResolveImageAlways,
-			Detach:       false,
+			Composefiles:     composeFiles,
+			Namespace:        stackName,
+			Prune:            false,
+			ResolveImage:     stack.ResolveImageAlways,
+			Detach:           false,
+			SendRegistryAuth: true,
 		}
 
 		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)

cli/internal/validate.go

@@ -59,9 +59,15 @@ func ValidateRecipe(args []string, cmdName string) recipe.Recipe {
 		log.Fatal(i18n.G("no recipe name provided"))
 	}
 
-	if _, ok := knownRecipes[recipeName]; !ok {
-		if !strings.Contains(recipeName, "/") {
-			log.Fatal(i18n.G("no recipe '%s' exists?", recipeName))
+	recipeName = recipe.NormalizeRecipeName(recipeName)
+
+	lookupName := recipeName
+	if i := strings.LastIndex(lookupName, ":"); i >= 0 {
+		lookupName = lookupName[:i]
+	}
+	if _, ok := knownRecipes[lookupName]; !ok {
+		if !strings.Contains(lookupName, "/") {
+			log.Fatal(i18n.G("no recipe '%s' exists? pass a git URL (e.g. https://git.example.com/user/recipe) to use a recipe outside the catalogue", lookupName))
 		}
 	}
 

cli/recipe/list.go

@@ -2,11 +2,13 @@ package recipe
 
 import (
 	"fmt"
+	"path"
 	"sort"
 	"strconv"
 	"strings"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/config"
 	"coopcloud.tech/abra/pkg/formatter"
 	"coopcloud.tech/abra/pkg/i18n"
 	"coopcloud.tech/abra/pkg/log"
@@ -41,6 +43,7 @@ var RecipeListCommand = &cobra.Command{
 
 		headers := []string{
 			i18n.G("name"),
+			i18n.G("source"),
 			i18n.G("category"),
 			i18n.G("status"),
 			i18n.G("healthcheck"),
@@ -56,6 +59,7 @@ var RecipeListCommand = &cobra.Command{
 		for _, recipe := range recipes {
 			row := []string{
 				recipe.Name,
+				i18n.G("catalogue"),
 				recipe.Category,
 				strconv.Itoa(recipe.Features.Status),
 				recipe.Features.Healthcheck,
@@ -76,6 +80,23 @@ var RecipeListCommand = &cobra.Command{
 			}
 		}
 
+		externals := externalRecipes(catl)
+		sort.Strings(externals)
+		for _, name := range externals {
+			row := []string{
+				name,
+				i18n.G("external"),
+				"-", "-", "-", "-", "-", "-", "-",
+			}
+			if pattern != "" {
+				if !strings.Contains(name, pattern) {
+					continue
+				}
+			}
+			table.Row(row...)
+			rows = append(rows, row)
+		}
+
 		if len(rows) > 0 {
 			if internal.MachineReadable {
 				out, err := formatter.ToJSON(headers, rows)
@@ -93,6 +114,30 @@ var RecipeListCommand = &cobra.Command{
 	},
 }
 
+// externalRecipes returns canonical names of locally-cloned recipes that
+// were sourced from an arbitrary git URL (i.e. they carry a .abra-source
+// sidecar) and are not already listed in the catalogue.
+func externalRecipes(catl recipe.RecipeCatalogue) []string {
+	dirs, err := recipe.GetRecipesLocal()
+	if err != nil {
+		log.Debug(i18n.G("can't read local recipes: %s", err))
+		return nil
+	}
+
+	var names []string
+	for _, dir := range dirs {
+		canonical := recipe.ReadRecipeSource(path.Join(config.RECIPES_DIR, dir))
+		if canonical == "" {
+			continue
+		}
+		if _, inCatalogue := catl[canonical]; inCatalogue {
+			continue
+		}
+		names = append(names, canonical)
+	}
+	return names
+}
+
 var (
 	pattern string
 )

cmd/abra/main.go

@@ -16,7 +16,7 @@ func main() {
 		Version = "dev"
 	}
 	if Commit == "" {
-		Commit = "       "
+		Commit = "unknown-commit"
 	}
 
 	cli.Run(Version, Commit)

devbox.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.17.2/.schema/devbox.schema.json",
+  "packages": [
+    "go@1.26",
+    "gnumake@latest",
+    "gettext@latest"
+  ],
+  "env": {
+    "GOPATH": "$PWD/.devbox",
+    "PATH": "$PWD/.devbox/bin:$PATH"
+  },
+  "shell": {
+    "init_hook": [
+      "mkdir -p .devbox/bin"
+    ],
+    "scripts": {
+      "xgettext-go": [
+        "go install git.coopcloud.tech/toolshed/xgettext-go@latest"
+      ],
+      "build": [
+        "make build"
+      ],
+      "test": [
+        "make test"
+      ]
+    }
+  }
+}

devbox.lock

@@ -0,0 +1,265 @@
+{
+  "lockfile_version": "1",
+  "packages": {
+    "gettext@latest": {
+      "last_modified": "2026-05-21T08:15:18Z",
+      "resolved": "github:NixOS/nixpkgs/4a29d733e8a7d5b824c3d8c958a946a9867b3eb2#gettext",
+      "source": "devbox-search",
+      "version": "1.0",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/i5aw4v15lklq5r5w5clvcy8dxc2igjck-gettext-1.0",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/17g5cqxvbkxivmfd39ppvyc0rx1wpcn8-gettext-1.0-man",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/kfx0dvvkmyw91jbqnp58yhzlxqi1xyi0-gettext-1.0-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/d14xspsnm4xj9w8yicrj50xmhs8bb5s2-gettext-1.0-info"
+            }
+          ],
+          "store_path": "/nix/store/i5aw4v15lklq5r5w5clvcy8dxc2igjck-gettext-1.0"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/jdqf3kqpj22agyhakrk5gklvzc6fxp3l-gettext-1.0",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/axz6675qpbr93bbs1hfz60m0dm1i01mg-gettext-1.0-man",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/5wckc0cg4l9wbmaqsi08rrmc09q7mxym-gettext-1.0-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/fd0d7h9y3kvp9i3x172lsj3x5ffz6sh7-gettext-1.0-info"
+            }
+          ],
+          "store_path": "/nix/store/jdqf3kqpj22agyhakrk5gklvzc6fxp3l-gettext-1.0"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/f46icmrv0rpaykfxs313d4g17g0jxn02-gettext-1.0",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/nk8dbg526a7lmsr4x41nbj3hizjk7f6k-gettext-1.0-man",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/w0wgn2f7ha2kp5ank9ymf1l8mlfki30a-gettext-1.0-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/cvp75qjcdjh8xrhzhrrdc62dyfil1f5j-gettext-1.0-info"
+            }
+          ],
+          "store_path": "/nix/store/f46icmrv0rpaykfxs313d4g17g0jxn02-gettext-1.0"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/rb8rna9gkhs0ybl6z2p904myslh8llg8-gettext-1.0",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/ck224axif94df161wk7b0wzwm035747f-gettext-1.0-man",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/2lp7blpw8ahc683287gbnp6vn4i9p9q4-gettext-1.0-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/33xaaniyh3qk6mq75dzx7v9c55n21i3p-gettext-1.0-info"
+            }
+          ],
+          "store_path": "/nix/store/rb8rna9gkhs0ybl6z2p904myslh8llg8-gettext-1.0"
+        }
+      }
+    },
+    "github:NixOS/nixpkgs/nixpkgs-unstable": {
+      "last_modified": "2026-05-27T10:28:13Z",
+      "resolved": "github:NixOS/nixpkgs/4100e830e085863741bc69b156ec4ccd53ab5be0?lastModified=1779877693&narHash=sha256-NOF9NAREhxr50bbBfVcVOq%2BArCMSoe8dP79Pk2uyARk%3D"
+    },
+    "gnumake@latest": {
+      "last_modified": "2026-05-27T10:28:13Z",
+      "resolved": "github:NixOS/nixpkgs/4100e830e085863741bc69b156ec4ccd53ab5be0#gnumake",
+      "source": "devbox-search",
+      "version": "4.4.1",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/8wwiw8pwyhrkzyq28hqzxfl4z84lks81-gnumake-4.4.1",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/wdm9prq35jlgwq6rjyhqxy4jzy833sfr-gnumake-4.4.1-man",
+              "default": true
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/6dbp1ysgxsrrn7xgjgf523faqrm605a5-gnumake-4.4.1-info"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/sl2ygvgjg4ml8dhyfxj5kh84x2bs1mhc-gnumake-4.4.1-doc"
+            }
+          ],
+          "store_path": "/nix/store/8wwiw8pwyhrkzyq28hqzxfl4z84lks81-gnumake-4.4.1"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/9ngw1ippk25jjj5fjxv36xbp6iq7rxdx-gnumake-4.4.1",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/dg3aa71vii59scbfhi02cdxnps64x6ql-gnumake-4.4.1-man",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/mdv67w2xvchbs76zjdzppdkk64z5avki-gnumake-4.4.1-debug"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/bybbj9avk3g107mwhgvkzkpm6mkbl8gv-gnumake-4.4.1-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/bxdqxx2q13sj15ss8z5l33jd31x55j5l-gnumake-4.4.1-info"
+            }
+          ],
+          "store_path": "/nix/store/9ngw1ippk25jjj5fjxv36xbp6iq7rxdx-gnumake-4.4.1"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/60y2hs45l18g56ykw9789b5vhhi2ls5q-gnumake-4.4.1",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/m2ba4bwmfgh994xbg1iqm6zj1mdrq8h7-gnumake-4.4.1-man",
+              "default": true
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/apljbm6plyajbfrnwif0a2d4nx6w0cpf-gnumake-4.4.1-info"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/s9y438l347nky6rkl1wfk2y3b0d9i636-gnumake-4.4.1-doc"
+            }
+          ],
+          "store_path": "/nix/store/60y2hs45l18g56ykw9789b5vhhi2ls5q-gnumake-4.4.1"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/d3bwqm6bymhy3pdgbvf7vxjqfp31m3j1-gnumake-4.4.1",
+              "default": true
+            },
+            {
+              "name": "man",
+              "path": "/nix/store/bmvqa5ym318mymhxlwwmxq8wxal958p4-gnumake-4.4.1-man",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/q683z843wi7xs96pngh1kinnx88vn2if-gnumake-4.4.1-debug"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/wxg27bzsljjw4k72m9b2v6a0fx5a68s0-gnumake-4.4.1-doc"
+            },
+            {
+              "name": "info",
+              "path": "/nix/store/03d41qgjsrhcr3fzq2z99ry07rahnj0v-gnumake-4.4.1-info"
+            }
+          ],
+          "store_path": "/nix/store/d3bwqm6bymhy3pdgbvf7vxjqfp31m3j1-gnumake-4.4.1"
+        }
+      }
+    },
+    "go@1.26": {
+      "last_modified": "2026-05-21T08:15:18Z",
+      "resolved": "github:NixOS/nixpkgs/4a29d733e8a7d5b824c3d8c958a946a9867b3eb2#go",
+      "source": "devbox-search",
+      "version": "1.26.3",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/7ycp8j45iay38g9mjaxmy4jhwdsrb47y-go-1.26.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/7ycp8j45iay38g9mjaxmy4jhwdsrb47y-go-1.26.3"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/jkcwcbwvhgzmxg59798z4clmj4bfv42i-go-1.26.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/jkcwcbwvhgzmxg59798z4clmj4bfv42i-go-1.26.3"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/3f2jzvxmhhlarjqxy1p7i9r5l34siz29-go-1.26.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/3f2jzvxmhhlarjqxy1p7i9r5l34siz29-go-1.26.3"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/33fw5m31lfcnk4ff2f0df7j2bxnh8lgk-go-1.26.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/33fw5m31lfcnk4ff2f0df7j2bxnh8lgk-go-1.26.3"
+        }
+      }
+    }
+  }
+}

pkg/app/app.go

@@ -390,13 +390,21 @@ func TemplateAppEnvSample(r recipe.Recipe, appName, server, domain string) error
 		return err
 	}
 
+	shortName := r.Name
+	if i := strings.LastIndex(shortName, "/"); i >= 0 {
+		shortName = shortName[i+1:]
+	}
 	newContents := strings.Replace(
 		string(read),
-		fmt.Sprintf("%s.example.com", r.Name),
+		fmt.Sprintf("%s.example.com", shortName),
 		domain,
 		-1,
 	)
 
+	if strings.Contains(r.Name, "/") {
+		newContents = injectRecipeLine(newContents, r.Name)
+	}
+
 	err = os.WriteFile(appEnvPath, []byte(newContents), 0)
 	if err != nil {
 		return err
@@ -407,6 +415,37 @@ func TemplateAppEnvSample(r recipe.Recipe, appName, server, domain string) error
 	return nil
 }
 
+// injectRecipeLine ensures the env file carries a RECIPE=<canonical name>
+// line so a downstream `abra app deploy` (potentially on another machine)
+// can re-fetch the recipe from its original git source. If a RECIPE= line
+// already exists in the copied .env.sample it is replaced; otherwise a new
+// line is inserted immediately after the TYPE= line, or appended at the
+// end if no TYPE= line is present.
+func injectRecipeLine(contents, canonicalName string) string {
+	lines := strings.Split(contents, "\n")
+	for i, line := range lines {
+		trimmed := strings.TrimLeft(line, " \t")
+		if strings.HasPrefix(trimmed, "RECIPE=") {
+			lines[i] = "RECIPE=" + canonicalName
+			return strings.Join(lines, "\n")
+		}
+	}
+	for i, line := range lines {
+		trimmed := strings.TrimLeft(line, " \t")
+		if strings.HasPrefix(trimmed, "TYPE=") {
+			out := make([]string, 0, len(lines)+1)
+			out = append(out, lines[:i+1]...)
+			out = append(out, "RECIPE="+canonicalName)
+			out = append(out, lines[i+1:]...)
+			return strings.Join(out, "\n")
+		}
+	}
+	if contents != "" && !strings.HasSuffix(contents, "\n") {
+		contents += "\n"
+	}
+	return contents + "RECIPE=" + canonicalName + "\n"
+}
+
 // SanitiseAppName makes a app name usable with Docker by replacing illegal
 // characters.
 func SanitiseAppName(name string) string {

pkg/formatter/formatter.go

@@ -27,10 +27,16 @@ var BoldUnderlineStyle = lipgloss.NewStyle().
 	Underline(true)
 
 func ShortenID(str string) string {
+	if len(str) < 12 {
+		return str
+	}
 	return str[:12]
 }
 
 func SmallSHA(hash string) string {
+	if len(hash) < 8 {
+		return hash
+	}
 	return hash[:8]
 }
 

pkg/git/read.go

@@ -36,6 +36,11 @@ func IsClean(repoPath string) (bool, error) {
 		return false, err
 	}
 
+	// Ignore the abra-managed sidecar file that records the canonical
+	// source URL for externally-cloned recipes; it lives alongside the
+	// recipe but is not part of the upstream tree.
+	patterns = append(patterns, gitignore.ParsePattern(".abra-source", nil))
+
 	if len(patterns) > 0 {
 		worktree.Excludes = append(patterns, worktree.Excludes...)
 	}

pkg/git/read_test.go

@@ -2,6 +2,8 @@ package git
 
 import (
 	"errors"
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/go-git/go-git/v5"
@@ -13,3 +15,37 @@ func TestIsClean(t *testing.T) {
 	assert.Equal(t, isClean, false)
 	assert.True(t, errors.Is(err, git.ErrRepositoryNotExists))
 }
+
+// TestIsCleanIgnoresAbraSource confirms that the .abra-source sidecar
+// file written by abra next to externally-cloned recipes does not cause
+// IsClean to report the worktree as dirty.
+func TestIsCleanIgnoresAbraSource(t *testing.T) {
+	dir := t.TempDir()
+
+	if _, err := git.PlainInit(dir, false); err != nil {
+		t.Fatalf("git init failed: %s", err)
+	}
+
+	sidecar := filepath.Join(dir, ".abra-source")
+	if err := os.WriteFile(sidecar, []byte("git.example.com/u/recipe\n"), 0o644); err != nil {
+		t.Fatalf("writing sidecar failed: %s", err)
+	}
+
+	isClean, err := IsClean(dir)
+	if err != nil {
+		t.Fatalf("IsClean returned error: %s", err)
+	}
+	assert.True(t, isClean, "expected worktree with only .abra-source to be reported clean")
+
+	// Sanity check: an unrelated untracked file should still mark it dirty.
+	other := filepath.Join(dir, "random.txt")
+	if err := os.WriteFile(other, []byte("hello"), 0o644); err != nil {
+		t.Fatalf("writing extra file failed: %s", err)
+	}
+
+	isClean, err = IsClean(dir)
+	if err != nil {
+		t.Fatalf("IsClean returned error: %s", err)
+	}
+	assert.False(t, isClean, "expected worktree with unrelated untracked file to be reported dirty")
+}

pkg/i18n/locales/abra.pot

@@ -7,7 +7,7 @@
 msgid   ""
 msgstr  "Project-Id-Version: \n"
         "Report-Msgid-Bugs-To: EMAIL\n"
-        "POT-Creation-Date: 2026-04-11 11:34+0200\n"
+        "POT-Creation-Date: 2026-05-30 11:14+0200\n"
         "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
         "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
         "Language-Team: LANGUAGE <LL@li.org>\n"

pkg/recipe/git.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path"
 	"slices"
 	"sort"
 	"strings"
@@ -19,6 +20,11 @@ import (
 	"github.com/go-git/go-git/v5/plumbing"
 )
 
+// SourceFile is the sidecar file written next to an externally-cloned
+// recipe so the canonical "host/path" name can be recovered later (the
+// on-disk directory name escapes "/" and "." to "_", which is lossy).
+const SourceFile = ".abra-source"
+
 type EnsureContext struct {
 	Chaos            bool
 	Offline          bool
@@ -78,6 +84,12 @@ func (r Recipe) EnsureExists() error {
 		if err := gitPkg.Clone(r.Dir, r.GitURL); err != nil {
 			return err
 		}
+		if strings.Contains(r.Name, "/") {
+			sidecar := path.Join(r.Dir, SourceFile)
+			if err := os.WriteFile(sidecar, []byte(r.Name+"\n"), 0o644); err != nil {
+				log.Debug(i18n.G("failed to write recipe source sidecar %s: %s", sidecar, err))
+			}
+		}
 	}
 
 	if err := gitPkg.EnsureGitRepo(r.Dir); err != nil {
@@ -87,6 +99,18 @@ func (r Recipe) EnsureExists() error {
 	return nil
 }
 
+// ReadRecipeSource returns the canonical name recorded in the .abra-source
+// sidecar inside the given recipe directory, or the empty string if no
+// sidecar exists. This lets callers recover the unescaped "host/path"
+// form for externally-cloned recipes.
+func ReadRecipeSource(recipeDir string) string {
+	data, err := os.ReadFile(path.Join(recipeDir, SourceFile))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
 // IsChaosCommit determines if a version sttring is a chaos commit or not.
 func (r Recipe) IsChaosCommit(version string) (bool, error) {
 	isChaosCommit := false
@@ -163,6 +187,9 @@ func (r Recipe) EnsureVersion(version string) (bool, error) {
 
 		hash, err := repo.ResolveRevision(plumbing.Revision(version))
 		if err != nil {
+			if isRemoteBranch(repo, version) {
+				log.Fatal(i18n.G("'%s' is a branch name; ':<version>' only supports tags or commit hashes, not branches", version))
+			}
 			log.Fatal(i18n.G("unable to resolve '%s': %s", version, err))
 		}
 
@@ -479,6 +506,28 @@ func (r Recipe) GetRecipeVersions() (RecipeVersions, []string, error) {
 	return versions, uniqueWarnings, nil
 }
 
+// isRemoteBranch reports whether name matches a branch on any configured
+// remote. Used to give a clearer error when a user passes a branch as the
+// ":version" suffix, which is unsupported.
+func isRemoteBranch(repo *git.Repository, name string) bool {
+	remotes, err := repo.Remotes()
+	if err != nil {
+		return false
+	}
+	for _, remote := range remotes {
+		refs, err := remote.List(&git.ListOptions{})
+		if err != nil {
+			continue
+		}
+		for _, ref := range refs {
+			if ref.Name().IsBranch() && ref.Name().Short() == name {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 // Head retrieves latest HEAD metadata.
 func (r Recipe) Head() (*plumbing.Reference, error) {
 	repo, err := git.PlainOpen(r.Dir)

pkg/recipe/recipe.go

@@ -8,6 +8,7 @@ import (
 	"net/url"
 	"os"
 	"path"
+	"regexp"
 	"sort"
 	"strconv"
 	"strings"
@@ -121,7 +122,83 @@ type Features struct {
 	SSO         string `json:"sso"`
 }
 
+// scpURLPattern matches SCP-style git URLs like git@host:path or git@host:port/path.
+// Captures: 1=host(:port)?, 2=path.
+var scpURLPattern = regexp.MustCompile(`^[\w.-]+@([\w.-]+(?::\d+)?):(.+)$`)
+
+// NormalizeRecipeName canonicalizes a recipe identifier to a stable
+// "host/path" form (or returns short catalog names unchanged). Accepts:
+//
+//   - https://host/path[.git][:version]
+//   - http://host/path[.git][:version]
+//   - ssh://git@host[:port]/path[.git][:version]
+//   - git@host:path[.git][:version]            (SCP-style)
+//   - host/path[.git][:version]                (already canonical)
+//   - short-name[:version]                     (catalog recipe, pass through)
+//
+// The optional trailing :version suffix is preserved verbatim. The .git
+// suffix and trailing slashes on the path are stripped so the four URL
+// forms of the same repository collapse to one canonical value.
+func NormalizeRecipeName(input string) string {
+	input = strings.TrimSpace(input)
+
+	// Split off the version suffix first, but only if it's not part of a
+	// scheme (https://) or SCP-style git@host: prefix. The simplest way is
+	// to detect those prefixes and treat the rest as the path-with-version.
+	var (
+		body    = input
+		version string
+	)
+
+	switch {
+	case strings.HasPrefix(input, "https://") || strings.HasPrefix(input, "http://") || strings.HasPrefix(input, "ssh://"):
+		u, err := url.Parse(input)
+		if err != nil {
+			return input
+		}
+		host := u.Hostname() // strip port to keep canonical form colon-free
+		p := strings.TrimPrefix(u.Path, "/")
+		p, version = splitVersion(p)
+		body = host + "/" + p
+	case scpURLPattern.MatchString(input):
+		m := scpURLPattern.FindStringSubmatch(input)
+		host := m[1]
+		if i := strings.Index(host, ":"); i >= 0 {
+			host = host[:i] // strip port
+		}
+		p, v := splitVersion(m[2])
+		body = host + "/" + p
+		version = v
+	default:
+		body, version = splitVersion(input)
+	}
+
+	body = strings.TrimSuffix(body, "/")
+	body = strings.TrimSuffix(body, ".git")
+
+	if version != "" {
+		return body + ":" + version
+	}
+	return body
+}
+
+// splitVersion separates a trailing ":version" suffix from a recipe path.
+// It only treats the final colon-separated segment as a version if it
+// looks like one (no slashes, contains a digit or '+').
+func splitVersion(s string) (string, string) {
+	idx := strings.LastIndex(s, ":")
+	if idx < 0 {
+		return s, ""
+	}
+	candidate := s[idx+1:]
+	if candidate == "" || strings.ContainsAny(candidate, "/") {
+		return s, ""
+	}
+	return s[:idx], candidate
+}
+
 func Get(name string) Recipe {
+	name = NormalizeRecipeName(name)
 	version := ""
 	versionRaw := ""
 	if strings.Contains(name, ":") {

pkg/recipe/recipe_test.go

@@ -88,6 +88,88 @@ func TestGet(t *testing.T) {
 				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
 			},
 		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe.git:1.2.4",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				EnvVersion:    "1.2.4",
+				EnvVersionRaw: "1.2.4",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "ssh://git@mygit.org/myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "git@mygit.org:myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "git@mygit.org:myorg/cool-recipe:1.2.4",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				EnvVersion:    "1.2.4",
+				EnvVersionRaw: "1.2.4",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
 	}
 
 	for _, tc := range testcases {
@@ -101,6 +183,49 @@ func TestGet(t *testing.T) {
 	}
 }
 
+func TestNormalizeRecipeName(t *testing.T) {
+	cases := []struct {
+		in, want string
+	}{
+		// catalog short names pass through
+		{"foo", "foo"},
+		{"foo:1.2.3", "foo:1.2.3"},
+
+		// bare host/path form
+		{"mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"mygit.org/myorg/cool-recipe.git:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+		{"mygit.org/myorg/cool-recipe/", "mygit.org/myorg/cool-recipe"},
+
+		// https://
+		{"https://mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"https://mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"https://mygit.org/myorg/cool-recipe.git:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+		{"http://mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+
+		// ssh://, with and without port
+		{"ssh://git@mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"ssh://git@mygit.org:2222/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+
+		// SCP-style git@host:path
+		{"git@mygit.org:myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"git@mygit.org:myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"git@mygit.org:myorg/cool-recipe:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+
+		// whitespace
+		{"  https://mygit.org/myorg/cool-recipe  ", "mygit.org/myorg/cool-recipe"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			got := NormalizeRecipeName(tc.in)
+			if got != tc.want {
+				t.Errorf("NormalizeRecipeName(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
 func TestGetVersionLabelLocalDoesNotUseTimeoutLabel(t *testing.T) {
 	test.Setup()
 	t.Cleanup(func() { test.Teardown() })