Add search_remote_refs source parameter.

This parameter compliments the `refs_prefix` and enables the round trip
for gerrit's refs/for/<branch> change review workflow.

A gerrit user creates a change for review by pushing to
`refs/for/<branch>`, but then the gerrit remote will rename that ref to
`refs/changes/xxx/yy`.

Since we don't know the actual ref that will be created, we must search
the remote for a ref containing the version we just pushed, and fetch
from there.

Also need to remember to have a separate input and output resource so
that the pushed version isn't counted as an input in a later run.

Signed-off-by: Jamie Pate <jpate@fortinet.com>

README.md

@@ -121,6 +121,12 @@ Tracks the commits in a [git](http://git-scm.com/) repository.
 
 * `version_depth`: *Optional.* The number of versions to return when performing a check
 
+* `search_remote_refs`: *Optional.* True to search remote refs for the input version when checking out during the get step.
+    This can be useful during the `get` step after a `put` step for unconventional workflows. One example workflow is the
+    `refs/for/<branch>` workflow used by gerrit which 'magically' creates a `refs/changes/nnn` reference instead
+    of the straight forward `refs/for/<branch>` reference that a git remote would usually create.
+    See also `out params.refs_prefix`.
+
 ### Example
 
 Resource configuration for a private repo with an HTTPS proxy:
@@ -332,6 +338,9 @@ pushed regardless of the upstream state.
 
 * `refs_prefix`: *Optional.* Allows pushing to refs other than heads. Defaults to `refs/heads`.
 
+  Useful when paired with `source.search_remote_refs` in cases where the git remote
+  renames the ref you pushed.
+
 ## Development
 
 ### Prerequisites

assets/in

@@ -52,6 +52,7 @@ clean_tags=$(jq -r '(.params.clean_tags // false)' <<< "$payload")
 short_ref_format=$(jq -r '(.params.short_ref_format // "%s")' <<< "$payload")
 timestamp_format=$(jq -r '(.params.timestamp_format // "iso8601")' <<< "$payload")
 describe_ref_options=$(jq -r '(.params.describe_ref_options // "--always --dirty --broken")' <<< "$payload")
+search_remote_refs_flag=$(jq -r '(.source.search_remote_refs // false)' <<< "$payload")
 
 # If params not defined, get it from source
 if [ -z "$fetch_tags" ] || [ "$fetch_tags" == "null" ]  ; then
@@ -102,6 +103,15 @@ git fetch origin refs/notes/*:refs/notes/* $tagflag
 if [ "$depth" -gt 0 ]; then
   "$bin_dir"/deepen_shallow_clone_until_ref_is_found_then_check_out "$depth" "$ref" "$tagflag"
 else
+  if [ "$search_remote_refs_flag" == "true" ] && ! [ -z "$branchflag" ] && ! git rev-list -1 $ref 2> /dev/null > /dev/null; then
+    change_ref=$(git ls-remote origin | grep $ref | cut -f2)
+    if ! [ -z "$change_ref" ]; then
+      echo "$ref not found locally, but search_remote_refs is enabled. Attempting to fetch $change_ref first."
+      git fetch origin $change_ref
+    else
+      echo "WARNING: couldn't find a ref for $ref listed on the remote"
+    fi
+  fi
   git checkout -q "$ref"
 fi
 

test/get.sh

@@ -850,6 +850,38 @@ it_returns_list_of_all_tags_in_metadata() {
   "
 }
 
+it_can_get_from_url_at_branch_with_search_remote_refs() {
+  local repo=$(init_repo)
+  local ref1=$(make_commit_to_branch $repo branch-a)
+  local ref2=$(make_commit_to_branch $repo branch-a)
+  git -C $repo update-ref refs/heads/branch-a $ref1
+  git -C $repo update-ref refs/changes/1 $ref2
+  git -C $repo log --all --oneline
+  git -C $repo branch -v
+  local dest=$TMPDIR/destination
+
+  # use file:// repo to force the regular git transport instead of local copying
+  set +e
+  output=$(get_uri_at_branch_with_ref file://$repo "branch-a" $ref2 $dest 2>&1)
+  exit_code=$?
+  set -e
+
+  echo $output $exit_code
+  test "${exit_code}" = 128
+  echo "$output" | grep "fatal: reference is not a tree: "
+  test -e $dest/some-file
+  test "$(git -C $dest rev-parse HEAD)" != $ref2
+
+  rm -rf $dest
+
+  get_uri_at_branch_with_search_remote_refs file://$repo "branch-a" $ref2 $dest | jq -e "
+    .version == {ref: $(echo $ref2 | jq -R .)}
+  "
+
+  test -e $dest/some-file
+  test "$(git -C $dest rev-parse HEAD)" = $ref2
+}
+
 run it_can_use_submodules_with_missing_paths
 run it_can_use_submodules_with_names_that_arent_paths
 run it_can_use_submodules_without_perl_warning
@@ -892,3 +924,4 @@ run it_retains_tags_by_default
 run it_retains_tags_with_clean_tags_param
 run it_returns_list_without_tags_in_metadata
 run it_returns_list_of_all_tags_in_metadata
+run it_can_get_from_url_at_branch_with_search_remote_refs

test/helpers.sh

@@ -860,6 +860,31 @@ get_uri_at_branch_with_fetch_tags() {
   }" | ${resource_dir}/in "$3" | tee /dev/stderr
 }
 
+get_uri_at_branch_with_ref() {
+    jq -n "{
+    source: {
+      uri: $(echo $1 | jq -R .),
+      branch: $(echo $2 | jq -R .)
+    },
+    version: {
+      ref: $(echo $3 | jq -R .)
+    }
+  }" | ${resource_dir}/in "$4" | tee /dev/stderr
+}
+
+get_uri_at_branch_with_search_remote_refs() {
+  jq -n "{
+    source: {
+      uri: $(echo $1 | jq -R .),
+      branch: $(echo $2 | jq -R .),
+      search_remote_refs: true
+    },
+    version: {
+      ref: $(echo $3 | jq -R .)
+    }
+  }" | ${resource_dir}/in "$4" | tee /dev/stderr
+}
+
 get_uri_with_config() {
   jq -n "{
     source: {
@@ -1250,4 +1275,4 @@ put_uri_with_refs_prefix() {
       refs_prefix: $(echo $4 | jq -R .),
     }
   }" | ${resource_dir}/out "$2" | tee /dev/stderr
-}
+}