GIT-LFS-COMPLETION(1)

💅 GIT-LFS-COMPLETION(1) 💅

okay so bestie, this is the manual page for git-lfs-completion — the whole point is generating shell tab-completion scripts for Git LFS. iykyk ✨

🦋 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 💖

Okay so this command outputs a script which, when executed in a session of the given shell, will implement command-line tab-completion of Git LFS commands. periodt ✨

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.) no cap 💅

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. it's giving magic 🪄

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 more you know 🌈

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. fr fr, do not touch 💀

🌊 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. vibe check: each shell does its own thing ✨

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: the classic 💅
  • 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. slay ✅
  • 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. set it and forget it ✨
  • 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.) important bestie ⚠️
  • 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. homebrew girlies know 🍺
• fish: the friendly one 🐟
  • 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. cute 🫧
  • 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. works either way ✅
• Zsh: the customizable icon 💜
  • 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 way that works 🔄
  • 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. compatible queen 👑
  • 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. don't mix them, bestie 💀
  • 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. macOS Homebrew drama, but make it completion 🍎

✨ EXAMPLES ✨

Loading completions for the current shell session 🫶

okok so if you just want the completions right now, for this session only, no forever-commitment?? you literally just execute the script that git lfs completion spits out. that's it. that's the whole vibe. let's go shell by shell 💅

• Bash — source the output with a process substitution:

$ source <(git lfs completion bash)

⚠️ lowkey important: on Bash 3.2, the source builtin command will not properly execute the output of a process substitution 😭 so you gotta use a temporary file instead:

$ git lfs completion bash >git-lfs-completion.bash
$ source git-lfs-completion.bash

• fish — pipe it straight into source:

> git lfs completion fish | source

• zsh — same process-substitution slay, but heads up: 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 🎀

want it forever? main character energy? then you store the script that git lfs completion generates somewhere your shell actually reads during session startup. set it and forget it, bestie ✨

• Bash — okay so as mentioned in the SHELLS section, the bash-completion package is required by the Git LFS completion scripts for Bash. and bonus: 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. like this:

$ 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 😅 so 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 — again, the compinit function must also be executed to enable tab-completion, as described in the SHELLS section. don't skip it, i'm begging 🙈

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 you pick 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. iykyk 👑

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. dealer's choice 💅

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. the whole iconique family, fr fr 👑

---

okay that's the whole page bestie, no gatekeeping 💖 this footer is literally GIT-LFS-COMPLETION(1) — straight from the git-lfs source, version and date exactly as your build ships them, periodt 🫶