gradle-completion

Bash and Zsh completion support for Gradle.

This provides fast tab completion for:

• Gradle tasks for the current project and sub-projects
• Gradle CLI switches (e.g. --parallel)
• Common Gradle properties (e.g. -Dorg.gradle.debug)

It also handles custom default build files, so rootProject.buildFileName = 'build.gradle.kts' is supported.

See instructions for bash or for zsh, then consider optional additional configuration.

Here's a demo for the gradle project itself:

Installation for Zsh 5.0+

Install via Homebrew

brew install gradle-completion

# Ensure /usr/local/share/zsh/site-functions is on $fpath. You should get a result from the following
echo $fpath | grep "/usr/local/share/zsh/site-functions"

Install as oh-my-zsh plugin

Download the latest release tarball and extract it into your oh-my-zsh custom plugins directory:

VERSION=1.4.4  # Replace with the latest version from https://github.com/gradle/gradle-completion/releases
curl -L https://github.com/gradle/gradle-completion/releases/download/v${VERSION}/gradle-completion-${VERSION}.tar.gz | tar xz -C ~/.oh-my-zsh/custom/plugins/

Add gradle-completion to the plugins array in your '.zshrc' file:

plugins+=(gradle-completion)

Start a new terminal session.

Install manually

Download the latest release tarball and extract it to your preferred location:

VERSION=1.4.4  # Replace with the latest version from https://github.com/gradle/gradle-completion/releases
mkdir -p ~/.zsh
curl -L https://github.com/gradle/gradle-completion/releases/download/v${VERSION}/gradle-completion-${VERSION}.tar.gz | tar xz -C ~/.zsh/

Add the following to your '.zshrc' file:

fpath=(~/.zsh/gradle-completion-${VERSION} $fpath)
autoload -Uz compinit && compinit

Start a new terminal session. You may need to disable the gradle plugin for oh-my-zsh.

(Optional) Manual Completion Cache Initialization

Completion cache initialization happens the first time you invoke completion, and usually takes a few seconds, depending on the size of your project. You can manually initialize the cache and avoid interrupting your development mojo by running:

cd path/to/your-project
# For oh-my-zsh installation:
source ~/.oh-my-zsh/plugins/gradle-completion-VERSION/_gradle 1>&2 2>/dev/null; __gradle-completion-init
# OR for manual installation:
source ~/.zsh/gradle-completion-VERSION/_gradle 1>&2 2>/dev/null; __gradle-completion-init

Installation for Bash 3.2+

This script depends on the bash-completion framework, which is not installed on macOS by default.

Understanding .bashrc vs .bash_profile

Bash reads different config files depending on how it's started:

| Shell type | Config file | When | |------------|-------------|------| | Login shell | ~/.bash_profile | First shell at login, or bash -l | | Non-login interactive | ~/.bashrc | Running bash from another shell (e.g., zsh) |

Since macOS Catalina (2019), zsh is the default shell. If you type bash to switch from zsh, you get a non-login shell that only reads ~/.bashrc.

The bash-completion documentation recommends:

1. Put all interactive bash configuration (including completions) in ~/.bashrc
2. Have ~/.bash_profile source ~/.bashrc
3. Do not source bash-completion directly in ~/.bash_profile — it won't work in non-login shells

Install via Homebrew

1. Install the bash-completion framework. This is a required prerequisite.

   For macOS built-in Bash 3.2:

   brew install bash-completion
   

   For Homebrew Bash 4.2+ (recommended):

   brew install bash bash-completion@2
   

   Note: The macOS built-in Bash 3.2 is quite old. If you experience issues, consider installing a newer Bash via Homebrew.

2. Install gradle-completion.

   brew install gradle-completion
   

3. Configure ~/.bash_profile to source ~/.bashrc:

   LINE='[[ -f ~/.bashrc ]] && source ~/.bashrc' && grep -qxF "$LINE" ~/.bash_profile 2>/dev/null || printf '%s\n' "$LINE" >> ~/.bash_profile     
   

4. Configure ~/.bashrc to load bash-completion:

   echo '[[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && source "$(brew --prefix)/etc/profile.d/bash_completion.sh"' >> ~/.bashrc
   

5. Start a new Bash session (for example, open a new Terminal window that uses Bash or run bash in your current shell), then run source ~/.bashrc (or source ~/.bash_profile in a login shell).

Install manually

1. Ensure bash-completion is installed and configured. You can install it with your favorite package manager or by following the official installation instructions.

   Note: Homebrew's bash-completion@2 is patched to load completions from bash_completion.d/. If you install bash-completion@2 from source or another package manager, it only loads from the completions/ directory by default. In that case, either install to the completions/ directory or source gradle-completion.bash directly in your ~/.bashrc.

2. Download gradle-completion.bash and place it in your bash_completion.d folder (e.g., /usr/local/etc/bash_completion.d or ${HOME}/bash_completion.d).

   DEST="/usr/local/etc/bash_completion.d" # or DEST="${HOME}/bash_completion.d"
   mkdir -p "$DEST"
   curl -LA gradle-completion https://raw.githubusercontent.com/gradle/gradle-completion/master/gradle-completion.bash -o "$DEST/gradle"
   

3. Configure your shell profile (continue from step 3 in the Homebrew section above).

Troubleshooting

Check if completion is loaded:

type _gradle

If it shows _gradle is a function, completion is working. If it says not found, the completion script hasn't been sourced.

Check if you're in a login shell:

shopt -q login_shell && echo "login" || echo "not login"

If it shows not login, make sure your ~/.bash_profile sources ~/.bashrc (see step 3 above).

Check your Bash version:

echo $BASH_VERSION

If you're using macOS built-in Bash 3.2 and experiencing issues, consider installing a newer Bash: brew install bash

Common mistake — escaped $: Make sure your config uses $(brew --prefix) and not \$(brew --prefix) (with a backslash). The backslash prevents the command from running.

(Optional) Manual Completion Cache Initialization

Completion cache initialization happens the first time you invoke completion, and usually takes a few seconds, depending on the size of your project. You can manually initialize the cache and avoid interrupting your development mojo by running:

cd path/to/your-project
__gradle-completion-init

Additional Configuration

Excluding build scripts from UP-TO-DATE check

Tab completion checks known build scripts to see if they've been changed and refreshes the task cache if so. You can exclude build scripts from this check (and speed up completion) by specifying:

# Default is `"/(build|integTest|out)/"`
export GRADLE_COMPLETION_EXCLUDE_PATTERN="/(build|integTest|samples|smokeTest|testFixtures|templates|out|features)/"
# Essentially turn off checking for changed scripts
export GRADLE_COMPLETION_EXCLUDE_PATTERN="gradle"

Completion cache

One can manually (re)generate the completion cache by invoking __gradle-completion-init after the completion script has been sourced. This graciously avoids an unexpected cache build when invoking completion.

The build script cache is invalidated if any *.gradle or *.gradle.kts files change. However, these completion scripts do not search for new build scripts every time completion is invoked, because that would make completion ~20x slower (unless you have so really good ideas on this).

By default, the build script cache is invalidated every 3 weeks (30240 minutes). You can configure this value by exporting a new value for $GRADLE_CACHE_TTL_MINUTES:

export GRADLE_CACHE_TTL_MINUTES=$(expr 1440 \* number_of_days_you_want)

Implicit Tasks

Gradle allows you to access tasks of subprojects from the project root implicitly. For example, given these tasks:

:foo
:help
:bar:baz

You can execute gradle baz from the project root and it will execute :bar:baz.

gradle-completion will not tab complete these tasks by default because it adds a significant number of completion options, which may not be what you want and negatively impacts completion speed.

To allow completion of implicit tasks, set $GRADLE_COMPLETION_UNQUALIFIED_TASKS=true:

export GRADLE_COMPLETION_UNQUALIFIED_TASKS="true"

You may need to invalidate the cache using the cache config above or by executing touch build.gradle.

Troubleshooting

If zsh completion isn't working, first try checking your $fpath with echo $fpath.

HEADS UP: If you get an error 'parse error near `]]"', please upgrade zsh. zsh 5.0.5 has a bug in script parsing that is fixed as of zsh 5.0.8. See issues #4 and #7 for more details.

If zsh completion reports "Generating Gradle task cache..." every time, the zsh completion cache may be disabled. Enable it by adding the following to your ~/.zshrc file:

zstyle ':completion:*' use-cache on

Contributing

See the