GIT-LFS-COMPLETION(1)		        		 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.

 							 GIT-LFS-COMPLETION(1)