Variable definition in bash using the local keyword

Question

I'm learning bash scripting and found this on my /usr/share/bash-completion, line 305:

local cword words=()

What does it do? All tutorials online are just in the format

local var=value

Answer 1

Although I like answer given by jordanm I think it's equally important to show less experienced Linux users how to cope with such questions by themselves.

The suggested way is faster and more versatile than looking for answers at random pages showing up at Google search results page.

First, all commands that can be run in Bash without typing an explicit path to it such as ./command can be divided into two categories: Bash shell builtins and external commands. Bash shell builtins come installed with Bash and are part of it while external commands are not part of Bash. This is important because Bash shell builtins are documented inside man bash and their documentation can be also invoked with help command while external commands are usually documented in their own manpages or take some king of -h, --help flag. To check whether a command is a Bash shell builtin or an external command:

$ type local
local is a shell builtin

It will display how command would be interpreted if used as a command name (from help type). Here we can see that local is a shell builtin. Let's see another example:

$ type vim
vim is /usr/bin/vim

Here we can see that vim is not a shell builtin but an external command located in /usr/bin/vim. However, sometimes the same command could be installed both as an external command and be a shell builtin at the same time. Add -a to type to list all possibilities, for example:

$ type -a echo
echo is a shell builtin
echo is /usr/bin/echo
echo is /bin/echo

Here we can see that echo is both a shell builtin and an external command. However, if you just typed echo and pressed Return a shell builtin would be called because it appears first on this list. Note that all these versions of echo do not need to be the same. For example, on my system /usr/bin/echo takes --help flag while a builtin doesn't.

Ok, now when we know that local is a shell builtin let's find out how it works:

$ help local
local: local [option] name[=value] ...
Define local variables.

Create a local variable called NAME, and give it VALUE.  OPTION can
be any option accepted by `declare'.

Local variables can only be used within a function; they are visible
only to the function where they are defined and its children.

Exit Status:
Returns success unless an invalid option is supplied, an error occurs,
or the shell is not executing a function.

Note the first line: name[=value]. Everything between [ and ] is optional. It's a common convention used in many manpages and form of documentation in *nix world. That being said, command you asked about in your question is perfectly legal. In turn, ... character means that previous argument can be repeated. You can also read about this convention in some versions of man man:

The following conventions apply to the SYNOPSIS section and can be used
as a guide in other sections.

bold text          type exactly as shown.
italic text        replace with appropriate argument.
[-abc]             any or all arguments within [ ] are optional.
-a|-b              options delimited by | cannot be used together.
argument ...       argument is repeatable.
[expression] ...   entire expression within [ ] is repeatable.

So, at the end of the day, I hope that now you'll have an easier time understanding how different commands in Linux work.

Answer 2

The local keyword can take multiple variables. Providing the variable with a value is optional. Your example declares two variables, cword and words. The words variable is assigned an empty array.

Answer 3

local simply declares a variable to have scope only in the currently-defined function, so that the main executing environment cannot "see" the value. You can't use local outside a function. Example

func() {
   nonlocal="Non local variable"
   local onlyhere="Local variable"
}
func
echo $nonlocal 
echo $onlyhere

Output: Non local variable

So $onlyhere wasn't visible outside the scope of the function.

Answer 4

It should be noted that Bash is dynamically scoped, which means local doesn't behave how you might expect from other languages.

Observe:

#!/usr/bin/env bash

x=15

print1 () {
    echo "I am printing $x"
}

print2 () {
    local x=44
    print1
}

print1 # prints "I am printing 15"
print2 # prints "I am printing 44"
print1 # prints "I am printing 15"

So essentially this means local doesn't mean "local variable" it means "locally redefined global variable"