Install a specific branch or tag with @ syntax

- Use idiomatic `username/package@ref` style syntax.
- Check for upstream changes in a more portable way
- Disable outdated check on packages cloned by ref or tag

The ref selection is permanent at install time. Theres no way to
switch the package to a different ref without re-installing it.

Tags in git are effectively non-updatable. If you checked out a package
on a tag or commit hash its very likely that you'll never expect that
tag to change and want to pin the package to that specific version

Thanks to osse from #git for quick help ❤️

libexec/basher-_clone

@@ -2,18 +2,19 @@
 #
 # Summary: Clones a package from a site, but doesn't install it
 #
-# Usage: basher _clone <use_ssh> <site> <package>
+# Usage: basher _clone <use_ssh> <site> <package> [<ref>]
 
 set -e
 
-if [ "$#" -ne 3 ]; then
+if [ "$#" -ne 3 -a "$#" -ne 4 ]; then
   basher-help _clone
   exit 1
 fi
 
 use_ssh="$1"
 site="$2"
 package="$3"
+ref="$4"
 
 if [ -z "$use_ssh" ]; then
   basher-help _clone
@@ -30,6 +31,12 @@ if [ -z "$package" ]; then
   exit 1
 fi
 
+if [ -z "$ref" ]; then
+  BRANCH_OPTION=""
+else
+  BRANCH_OPTION="-b $ref"
+fi
+
 IFS=/ read -r user name <<< "$package"
 
 if [ -z "$user" ]; then
@@ -59,4 +66,4 @@ else
   URI="https://${site}/$package.git"
 fi
 
-git clone ${DEPTH_OPTION} --recursive "$URI" "${BASHER_PACKAGES_PATH}/$package"
+git clone ${DEPTH_OPTION} ${BRANCH_OPTION} --recursive "$URI" "${BASHER_PACKAGES_PATH}/$package"

libexec/basher-install

@@ -2,7 +2,7 @@
 #
 # Summary: Installs a package from github (or a custom site)
 #
-# Usage: basher install [--ssh] [site]/<package>
+# Usage: basher install [--ssh] [site]/<package>[@ref]
 
 set -e
 
@@ -47,7 +47,17 @@ if [ -z "$name" ]; then
   exit 1
 fi
 
-basher-_clone "$use_ssh" "$site" "$package"
+if [[ "$package" = */*@* ]]; then
+  IFS=@ read -r package ref <<< "$package"
+else
+  ref=""
+fi
+
+if [ -z "$ref" ]; then
+  basher-_clone "$use_ssh" "$site" "$package"
+else
+  basher-_clone "$use_ssh" "$site" "$package" "$ref"
+fi
 basher-_deps "$package"
 basher-_link-bins "$package"
 basher-_link-man "$package"

libexec/basher-outdated

@@ -15,8 +15,10 @@ do
   if [ ! -L "$package_path" ]; then
     cd $package_path
     git remote update > /dev/null 2>&1
-    if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/HEAD)" ]; then
-      echo "$package"
+    if git symbolic-ref --short -q HEAD > /dev/null; then
+        if [ "$(git rev-list --count HEAD...HEAD@{upstream})" -gt 0 ]; then
+          echo "$package"
+        fi
     fi
   fi
 done

tests/basher-_clone.bats

@@ -5,19 +5,27 @@ load test_helper
 @test "without arguments prints usage" {
   run basher-_clone
   assert_failure
-  assert_line "Usage: basher _clone <use_ssh> <site> <package>"
+  assert_line "Usage: basher _clone <use_ssh> <site> <package> [<ref>]"
 }
 
 @test "invalid package prints usage" {
   run basher-_clone false github.com invalid_package
   assert_failure
-  assert_line "Usage: basher _clone <use_ssh> <site> <package>"
+  assert_line "Usage: basher _clone <use_ssh> <site> <package> [<ref>]"
 }
 
 @test "too many arguments prints usage" {
-  run basher-_clone false site a/b third_arg
+  run basher-_clone false site a/b ref fourth_arg
   assert_failure
-  assert_line "Usage: basher _clone <use_ssh> <site> <package>"
+  assert_line "Usage: basher _clone <use_ssh> <site> <package> [<ref>]"
+}
+
+@test "install a specific version" {
+  mock_command git
+
+  run basher-_clone false site username/package version
+  assert_success
+  assert_output "git clone --depth=1 -b version --recursive https://site/username/package.git ${BASHER_PACKAGES_PATH}/username/package"
 }
 
 @test "does nothing if package is already present" {

tests/basher-install.bats

@@ -5,19 +5,19 @@ load test_helper
 @test "without arguments prints usage" {
   run basher-install
   assert_failure
-  assert_line "Usage: basher install [--ssh] [site]/<package>"
+  assert_line "Usage: basher install [--ssh] [site]/<package>[@ref]"
 }
 
 @test "incorrect argument prints usage" {
   run basher-install first_arg
   assert_failure
-  assert_line "Usage: basher install [--ssh] [site]/<package>"
+  assert_line "Usage: basher install [--ssh] [site]/<package>[@ref]"
 }
 
 @test "too many arguments prints usage" {
   run basher-install a/b wrong
   assert_failure
-  assert_line "Usage: basher install [--ssh] [site]/<package>"
+  assert_line "Usage: basher install [--ssh] [site]/<package>[@ref]"
 }
 
 @test "executes install steps in right order" {
@@ -71,6 +71,30 @@ basher-_link-completions username/package"
   assert_line "basher-_clone true github.com username/package"
 }
 
+@test "installs with custom version" {
+  mock_command basher-_clone
+  mock_command basher-_deps
+  mock_command basher-_link-bins
+  mock_command basher-_link-man
+  mock_command basher-_link-completions
+
+  run basher-install username/package@v1.2.3
+
+  assert_line "basher-_clone false github.com username/package v1.2.3"
+}
+
+@test "empty version is ignored" {
+  mock_command basher-_clone
+  mock_command basher-_deps
+  mock_command basher-_link-bins
+  mock_command basher-_link-man
+  mock_command basher-_link-completions
+
+  run basher-install username/package@
+
+  assert_line "basher-_clone false github.com username/package"
+}
+
 @test "doesn't fail" {
   create_package username/package
   mock_clone

tests/basher-outdated.bats

@@ -32,3 +32,15 @@ load test_helper
   assert_success
   assert_output username/outdated
 }
+
+@test "ignore packages checked out with a tag or ref" {
+  mock_clone
+  create_package username/tagged
+  basher-install username/tagged
+
+  create_command git 'if [ "$1" = "symbolic-ref" ]; then exit 128; fi'
+
+  run basher-outdated
+  assert_success
+  assert_output ""
+}