Bash colon operator in variable substitution?

Question

I inherited some bash code and these two lines are bewildering me:

branch_name=`git describe --contains --all HEAD`
branch_name=${branch_name:-HEAD}

My understanding of the : colon operator is that is creates a substring based on an index so using a string, -HEAD in this case, does not make any sense.

Solution 1

This takes the variable branch_name, if it is defined. If it is not defined, use HEAD instead.

See Shell Parameter Expansion for details:

3.5.3 Shell Parameter Expansion

The ‘$’ character introduces parameter expansion, command substitution, or arithmetic expansion. ... The basic form of parameter expansion is ${parameter}.
...
When not performing substring expansion, using the form described below (e.g., ‘:-’), Bash tests for a parameter that is unset or null. Omitting the colon results in a test only for a parameter that is unset. Put another way, if the colon is included, the operator tests for both parameter’s existence and that its value is not null; if the colon is omitted, the operator tests only for existence.

${parameter:-word}

If parameter is unset or null, the expansion of word is substituted. Otherwise, the value of parameter is substituted.

---

Substrings are covered a few lines below. The difference between the two is

${parameter:-word}

vs

${parameter:offset}
${parameter:offset:length}

${parameter:offset}
${parameter:offset:length}

This is referred to as Substring Expansion. It expands to up to length characters of the value of parameter starting at the character specified by offset.
...
If offset evaluates to a number less than zero, the value is used as an offset in characters from the end of the value of parameter. ... Note that a negative offset must be separated from the colon by at least one space to avoid being confused with the ‘:-’ expansion.

Solution 2

In this case, the colon is just a modifier for the - operator. ${branch-HEAD} would expand to "HEAD" only if branch is unset, while ${branch:-HEAD} expands to "HEAD" if branch is the null string as well.

$ branch=master
$ echo "${branch-HEAD} + ${branch:-HEAD}"
master + master
$ branch=""
$ echo "${branch-HEAD} + ${branch:-HEAD}"
 + HEAD
$ unset branch
$ echo "${branch-HEAD} + ${branch:-HEAD}"
HEAD + HEAD

From the manual:

Omitting the colon results in a test only for a parameter that is unset.

Solution 3

In bash, ${VAR1:-VAR2} is equivalent to SQL's coalesce(VAR1, VAR2), or C#'s VAR1 ?? VAR2.

In your case:

branch_name=`git describe --contains --all HEAD`
branch_name=${branch_name:-HEAD}

The first line executes the git command and sets the value in the branch_name variable, then, the second line coalesces its value assigning the value of HEAD if branch_name is null.

As you said ${VAR1:NUM} is a string prefix operation (left in SQL), which when used with a negative number, as ${VAR1: -NUMBER} becomes a suffix (right) operation. Note the whitespace before the minus sign: if you skip that whitespace it becomes the coalesce operation as I've said before.

Comments

[willemdh]

And what if there is only ':-' ? LIke "${RDAUTH:-}"

[Olaf Dietsche]

This works like an empty string, tt gives either the contents of RDAUTH or an empty string.