= git-lfs-completion(1)

== NAME

git-lfs-completion - Shell tab-completion script generation for Git LFS

== SYNOPSIS

`git lfs completion bash` +
`git lfs completion fish` +
`git lfs completion zsh`

== DESCRIPTION

Outputs a script which, when executed in a session of the given shell,
will implement command-line tab-completion of Git LFS commands.

Each shell requires a different set of commands to load the completion
script, either for an individual session or automatically whenever a
new session is started.  See the <<_examples>> section for details.

The script for each shell provides tab-completion of Git LFS command
names and flags, but does not offer completion of Git terms such as
the names of Git remotes, branches, or tags.  (This may change in a
future release of Git LFS.)

By default, each shell's script supports Git LFS command completion
when prompted with a tab character entered following the program name
`git-lfs`.  For instance, `git-lfs [Tab]` will list the available Git LFS
commands such as `fetch`, `migrate`, and `pull`, and `git-lfs pull --[Tab]`
will list the possible flags for the git-lfs-pull(1) command.

However, most users will be accustomed to using Git LFS as a program
invoked by Git, e.g., `git lfs checkout` or `git lfs pull`.  To enable
tab-completion of Git LFS commands in this case, tab-completion for
regular Git commands must be active as well.  Assuming this is true,
the scripts generated by the `git lfs completion` command should support
completion of Git LFS commands when a tab character is entered following
`git lfs`, such as `git lfs [Tab]` to list all available Git LFS commands
or `git lfs pull --[Tab]` to list that command's possible flags.  See
the <<_shells>> section for details regarding Git tab-completion in
the supported shells.

As is common for shell tab-completion, a space must be entered after
the `git-lfs` or `git lfs` command names before the tab character will
cause the Git LFS completion script to be executed.  Without the
space character, any active shell tab-completion will instead search for
programs whose names have a matching prefix.

The completion scripts make use of "hidden" Git LFS  commands to request
completion results from the Git LFS client, specifically the
`git lfs \__complete` and `git lfs __completeNoDesc` commands.  These
commands may be removed in the future, or their action may be altered
without notice, and so users should not call them directly or consider
them to be part of the officially documented Git LFS command-line
interface.

== SHELLS

The `git lfs completion` command supports three Unix shells, GNU Bash
(Bourne Again SHell), fish, and Zsh (Z shell).  Tab-completion is
configured differently in each, both in general and specifically
for Git and therefore also for Git LFS.

On Windows, users who have Git LFS installed as part of the Git for Windows
project have access to an emulation of the Bash shell which is packaged
with Git for Windows.

* Bash:
+
While Bash does not offer tab-completion for Git by default, a completion
script is available from the Git project, as described in the documentation:
+
https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash
+
The script returned by the `git lfs completion bash` command should
be compatible with this Git completion script and allow for tab-completion
of Git LFS commands entered using either the `git lfs` or `git-lfs`
command formats.
+
After retrieving a copy of the Git completion script appropriate to your
version of Git, run the following command to load the script in your
current session:
+
....
$ source git-completion.bash
....
+
To load the script in all future sessions, add this command to your Bash
startup files, or place the file in one of the locations searched by
the utilities from the bash-completion package.
+
The bash-completion project, which is separate from the GNU Bash shell
itself, includes a large number of command completion scripts and utilities
to load them automatically when starting a new session:
+
https://github.com/scop/bash-completion
+
The Git LFS completion script for Bash depends on several functions provided
by the bash-completion package, and so that package must be installed in
order to use tab-completion with Git LFS commands.  (It is not required
by the Git completion script for Bash, however.)
+
Assuming the bash-completion package is installed, to load the Git
completion script in all future sessions started by the current user
(but not all users), place the `git-completion.bash` script in the
`bash-completion/completions` directory within the location defined
by the `XDG_DATA_HOME` environment variable, or, if that variable is
not defined, the `~/.local/share` directory.  For example:
+
....
$ cp git-completion.bash ~/.local/share/bash-completion/completions/git
....
+
For the bash-completion utilities to load the Git completion script for
all users, place the Git completion script in the appropriate system
directory.  On Linux this may be `/usr/share/bash-completion/completions`,
and on macOS, when bash-completion is installed using Homebrew, it may
be the `share/bash-completion/completions` directory within the location
returned by the `brew --prefix` command.  However, these locations will
vary depending on how the bash-completion package was installed.

* fish:
+
The fish shell provides its own implementation of Git command
tab-completion, defined in a `git.fish` file which is likely present
by default in the list of locations the shell searches for completion
scripts.
+
The script returned by the `git lfs completion fish` command should
be compatible with this implementation and allow for tab-completion
of Git LFS commands entered using either the `git lfs` or `git-lfs`
command formats.

* Zsh:
+
To enable tab-completion in Zsh for any commands, the `compinit` function
must be loaded first with a command similar to the following:
+
....
% autoload -Uz compinit && compinit
....
+
This may be done individually for each session, or added to a startup
file such as `~/.zshrc` or `/etc/zshrc` so it will apply to all future
sessions, either for the current user or for all users.
+
Zsh reads completion functions from the locations specified in the `FPATH`
environment variable, with the paths listed first taking precedence.
This list is also available as an array in the `fpath` variable; the
shell automatically synchronizes `FPATH` and `fpath`.
+
The Z shell provides its own implementation of Git command
tab-completion, defined in a `_git` file which is likely present in
one of the locations specified in `fpath`.
+
The script returned by the `git lfs completion zsh` command should
be compatible with this implementation and allow for tab-completion
of Git LFS commands entered using either the `git lfs` or `git-lfs`
command formats.
+
The Git project also offers completion scripts for Zsh, in the form of
the same `git-completion.bash` script used for the Bash shell, plus a
`git-completion.zsh` script which is intended to be renamed to `_git`
and placed in a location listed in `fpath`.  These scripts are not
compatible with the one returned by the `git lfs completion zsh` command,
and if they used in conjunction with that script, tab-completion of
Git LFS commands will not function properly when initiated using the
`git lfs` command format.
+
On macOS, if Git is installed using Homebrew, the Git project's Zsh
completion scripts may be installed in a location where they take
precedence over the implementation provided by Zsh.  In this case, to
make full use of the script returned by `git lfs completion zsh`, the
`_git` completion script file installed by Homebrew for Git must be moved
or removed so it does not precede the Z shell's own Git completion script
in the path order specified by `fpath`.

== EXAMPLES

=== Loading completions for the current shell session

To load Git LFS command completions for the current shell session only,
execute the script generated by `git lfs completion` directly.

* Bash:
+
....
$ source <(git lfs completion bash)
....
+
Note that with Bash 3.2, the `source` builtin command will not properly
execute the output of a process substitution, and so it will be
necessary to use a temporary file instead:
+
....
$ git lfs completion bash >git-lfs-completion.bash
$ source git-lfs-completion.bash
....

* fish:
+
....
> git lfs completion fish | source
....

* zsh:
+
Note that the `compinit` function must also be executed to enable
tab-completion, as described in the <<_shells>> section.
+
....
% source <(git lfs completion zsh)
....

=== Automatically loading completions for future shell sessions

To load Git LFS command completions in all future shell sessions,
store the script generated by `git lfs completion` in a location where
it will be read by your shell during session startup.

* Bash:
+
As mentioned in the <<_shells>> section, the bash-completion package
is required by the Git LFS completion scripts for Bash, and it also
provides convenient utilities which search for completion scripts in
a set of defined locations and execute them during session startup.
+
To load the Git LFS completion script in all future sessions started
by the current user (but not other users), store the script in the
`bash-completion/completions` directory within the location defined by
the `XDG_DATA_HOME` environment variable, or, if that variable is not
defined, the `~/.local/share` directory.  For example:
+
....
$ mkdir -p ~/.local/share/bash-completion/completions
$ git lfs completion bash >~/.local/share/bash-completion/completions/git-lfs
....
+
To load the completion script in all users' future sessions, store the
script instead in an appropriate system directory, which on Linux may be
`/usr/share/bash-completion/completions`, or on macOS, if bash-completion
was installed using Homebrew, may be the `share/bash-completion/completions`
directory within the location returned by the `brew --prefix` command.
These locations will vary depending on how the bash-completion package
was installed and configured, however.  For details, check the documentation
relevant to your system's bash-completion package.

* fish:
+
The fish shell searches for completion scripts in a number of locations,
as described in the documentation:
+
https://fishshell.com/docs/current/completions.html#where-to-put-completions
+
To load the Git LFS completion script in all sessions started by the
current user (but not other users), store the script in the
`fish/completions` directory within the location defined by the
`XDG_CONFIG_HOME` environment variable, or, if that variable is not
defined, the `~/.config` directory.  For example:
+
....
> mkdir -p ~/.config/fish/completions
> git lfs completion fish >~/.config/fish/completions/git-lfs.fish
....
+
To load the completion script in all users' future sessions, store the
script in one of the other locations searched by the shell, such under
`fish/completions` within the shell's system configuration directory.
On Linux this is typically `/etc/fish/completions`.  On macOS, when
the fish shell is installed using Homebrew, this would normally be the
`etc/fish/completions` directory within the location returned by
the `brew --prefix` command.

* zsh:
+
Note that the `compinit` function must also be executed to enable
tab-completion, as described in the <<_shells>> section.
+
To load the Git LFS completion script in all sessions, store the script
as a file named `_git-lfs` in one of the locations listed in the `fpath`
variable.  The specific location selected may affect whether the completion
script is loaded only for sessions started by the current user or for all
users' sessions, depending on how the set of paths in the `fpath` array
is constructed.
+
The following command will store the script in the first location
defined in `fpath`:
+
....
% git lfs completion zsh >"${fpath[1]}/_git-lfs"
....
+
You may also prefer to store the file in another location defined in
`fpath`, for instance, the last location, in which case `${fpath[-1]}`
should be used instead.
+
It is also possible to add a custom location to the list in `fpath`
and store the Git LFS completion script there.  To do this, add the
commands that update the `fpath` variable to a startup file such as
`~/.zshrc` or `/etc/zshrc` so they will apply to all future sessions,
either for the current user or for all users.

== SEE ALSO

Part of the git-lfs(1) suite.