Delete a reference in a Git repository

Removes a branch or a tag from the central repository Clarive hosts. The deletion happens in place, without a clone and without a push, so the ref is gone for every client the moment the op returns.

This is the cleanup end of the Git ops. It pairs with Create a branch in a Git repository for retiring a feature branch once it has merged, and with Create a tag in a Git repository for clearing a tag you are about to rewrite, which is an alternative to turning the force option on there.

Fields

Repository

The repositories to delete from. More than one entry is allowed and the same name is deleted from each of them in turn. The picker offers variables as well as repository resources, and a variable that resolves to several ids separated by commas counts as several repositories.

Blank stops the op with a missing-repository error.

Type

What kind of ref the name refers to.

Type	What happens
Any	the name is looked up in the repository's refs; a match on a branch head deletes a branch, anything else is deleted as a tag
Branch	deleted as a branch, with no lookup
Tag	deleted as a tag, with no lookup

The combo opens on Any, so an op whose form you open and save gets a usable value. An op saved without that field ever being set stops at run time with a missing-type error.

Any costs you an extra failure mode: when the name matches no ref at all, the lookup fails before the delete is even attempted, and the op stops. Pick Branch or Tag when you already know which one you are removing, and the error you get back is the plain Git error for that ref.

Sha or Ref

The name to delete. The label mentions a sha, but a raw commit id is close to useless here: what is deleted is a branch or a tag, so what belongs in this field is the branch name or the tag name. The field expands ${var} placeholders against the stash.

Blank stops the op with a missing-sha error.

What deletion does and does not do

Branch deletion is forced. Git's usual refusal to drop a branch whose commits are not merged anywhere else does not apply, and commits reachable only from that branch become unreachable. There is no confirmation and no record of the commit the branch pointed at, so capture it beforehand if you need it for a rollback.

Tag deletion removes the tag name only. Commits are not touched.

The revision resource that Create a branch in a Git repository registers is not removed. After this op the branch is gone from Git while the resource that names it is still listed in Clarive. Remove it separately when the leftover matters.

Nothing is pushed anywhere, because the deletion is applied to the repository Clarive hosts. Clones that already fetched the branch keep their local copy until they prune.

Failure, ordering and rollback

Repositories are handled in picker order and the first failure stops the op. Refs deleted before that point stay deleted, and nothing is put back. The repositories further down the list are never reached. Deleting the same name from a set of repositories where it exists in only some of them fails on the first repository that lacks it.

The op returns nothing, so a Return Key on it lands an empty value in the stash.

Both directions are enabled on a new op, so a delete left at its defaults runs again during a rollback pass and fails the second time, because the ref is already gone. Untick Run Rollback, or set the op's Error Handling to ignore errors when a missing ref is an acceptable outcome.

Combining with other ops

The usual pairing is after Merge a branch in a Git repository: merge the topic branch, then delete it. Put IF var condition THEN between the two so the delete only fires when the merge actually ran.

Record where the branch stood before you drop it by running Create a tag in a Git repository on the same name first. The tag survives the branch deletion and gives you something to branch from again.

For a list of repositories that is only known at run time, wrap the op in FOREACH CI. To tolerate a ref that may or may not be there, put the op inside TRY with a CATCH that logs and carries on.

Examples

Retire a topic's feature branch after its merge, in the repository the job is working on.

Repository   ${repository}
Type         Branch
Sha or Ref   feature/${topic_id}

Drop a tag before rewriting it, as an alternative to forcing the tag op.

Repository   ${repository}
Type         Tag
Sha or Ref   release/${version}

Clean up a name when you do not know which kind of ref it is, across a list of repositories. Set the op's Error Handling to ignore errors so repositories that never had the ref do not stop the rule.

Repository   ${project_repos}
Type         Any
Sha or Ref   ${branch_to_remove}