1GIT-LFS-COMPLETION(1) GIT-LFS-COMPLETION(1)
2
6 git-lfs-completion - Shell tab-completion script generation for Git LFS
7
9 git lfs completion bash
10 git lfs completion fish
11 git lfs completion zsh
12
14 Outputs a script which, when executed in a session of the given shell,
15 will implement command-line tab-completion of Git LFS commands.
16 Each shell requires a different set of commands to load the completion
18 script, either for an individual session or automatically whenever a
19 new session is started. See the EXAMPLES section for details.
20 The script for each shell provides tab-completion of Git LFS command
22 names and flags, but does not offer completion of Git terms such as the
23 names of Git remotes, branches, or tags. (This may change in a future
24 release of Git LFS.)
25 By default, each shell’s script supports Git LFS command completion
27 when prompted with a tab character entered following the program name
28 git-lfs. For instance, git-lfs [Tab] will list the available Git LFS
29 commands such as fetch, migrate, and pull, and git-lfs pull --[Tab]
30 will list the possible flags for the git-lfs-pull(1) command.
31 However, most users will be accustomed to using Git LFS as a program
33 invoked by Git, e.g., git lfs checkout or git lfs pull. To enable
34 tab-completion of Git LFS commands in this case, tab-completion for
35 regular Git commands must be active as well. Assuming this is true, the
36 scripts generated by the git lfs completion command should support
37 completion of Git LFS commands when a tab character is entered
38 following git lfs, such as git lfs [Tab] to list all available Git LFS
39 commands or git lfs pull --[Tab] to list that command’s possible flags.
40 See the SHELLS section for details regarding Git tab-completion in the
41 supported shells.
42 As is common for shell tab-completion, a space must be entered after
44 the git-lfs or git lfs command names before the tab character will
45 cause the Git LFS completion script to be executed. Without the space
46 character, any active shell tab-completion will instead search for
47 programs whose names have a matching prefix.
48 The completion scripts make use of "hidden" Git LFS commands to
50 request completion results from the Git LFS client, specifically the
51 git lfs __complete and git lfs __completeNoDesc commands. These
52 commands may be removed in the future, or their action may be altered
53 without notice, and so users should not call them directly or consider
54 them to be part of the officially documented Git LFS command-line
55 interface.
56
58 The git lfs completion command supports three Unix shells, GNU Bash
59 (Bourne Again SHell), fish, and Zsh (Z shell). Tab-completion is
60 configured differently in each, both in general and specifically for
61 Git and therefore also for Git LFS.
62 On Windows, users who have Git LFS installed as part of the Git for
64 Windows project have access to an emulation of the Bash shell which is
65 packaged with Git for Windows.
66 • Bash:
68 While Bash does not offer tab-completion for Git by default, a
70 completion script is available from the Git project, as described
71 in the documentation:
72 https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash
74 The script returned by the git lfs completion bash command should
76 be compatible with this Git completion script and allow for
77 tab-completion of Git LFS commands entered using either the git lfs
78 or git-lfs command formats.
79 After retrieving a copy of the Git completion script appropriate to
81 your version of Git, run the following command to load the script
82 in your current session:
83 $ source git-completion.bash
85 To load the script in all future sessions, add this command to your
87 Bash startup files, or place the file in one of the locations
88 searched by the utilities from the bash-completion package.
89 The bash-completion project, which is separate from the GNU Bash
91 shell itself, includes a large number of command completion scripts
92 and utilities to load them automatically when starting a new
93 session:
94 https://github.com/scop/bash-completion
96 The Git LFS completion script for Bash depends on several functions
98 provided by the bash-completion package, and so that package must
99 be installed in order to use tab-completion with Git LFS commands.
100 (It is not required by the Git completion script for Bash,
101 however.)
102 Assuming the bash-completion package is installed, to load the Git
104 completion script in all future sessions started by the current
105 user (but not all users), place the git-completion.bash script in
106 the bash-completion/completions directory within the location
107 defined by the XDG_DATA_HOME environment variable, or, if that
108 variable is not defined, the ~/.local/share directory. For example:
109 $ cp git-completion.bash ~/.local/share/bash-completion/completions/git
111 For the bash-completion utilities to load the Git completion script
113 for all users, place the Git completion script in the appropriate
114 system directory. On Linux this may be
115 /usr/share/bash-completion/completions, and on macOS, when
116 bash-completion is installed using Homebrew, it may be the
117 share/bash-completion/completions directory within the location
118 returned by the brew --prefix command. However, these locations
119 will vary depending on how the bash-completion package was
120 installed.
121 • fish:
123 The fish shell provides its own implementation of Git command
125 tab-completion, defined in a git.fish file which is likely present
126 by default in the list of locations the shell searches for
127 completion scripts.
128 The script returned by the git lfs completion fish command should
130 be compatible with this implementation and allow for tab-completion
131 of Git LFS commands entered using either the git lfs or git-lfs
132 command formats.
133 • Zsh:
135 To enable tab-completion in Zsh for any commands, the compinit
137 function must be loaded first with a command similar to the
138 following:
139 % autoload -Uz compinit && compinit
141 This may be done individually for each session, or added to a
143 startup file such as ~/.zshrc or /etc/zshrc so it will apply to all
144 future sessions, either for the current user or for all users.
145 Zsh reads completion functions from the locations specified in the
147 FPATH environment variable, with the paths listed first taking
148 precedence. This list is also available as an array in the fpath
149 variable; the shell automatically synchronizes FPATH and fpath.
150 The Z shell provides its own implementation of Git command
152 tab-completion, defined in a _git file which is likely present in
153 one of the locations specified in fpath.
154 The script returned by the git lfs completion zsh command should be
156 compatible with this implementation and allow for tab-completion of
157 Git LFS commands entered using either the git lfs or git-lfs
158 command formats.
159 The Git project also offers completion scripts for Zsh, in the form
161 of the same git-completion.bash script used for the Bash shell,
162 plus a git-completion.zsh script which is intended to be renamed to
163 _git and placed in a location listed in fpath. These scripts are
164 not compatible with the one returned by the git lfs completion zsh
165 command, and if they used in conjunction with that script,
166 tab-completion of Git LFS commands will not function properly when
167 initiated using the git lfs command format.
168 On macOS, if Git is installed using Homebrew, the Git project’s Zsh
170 completion scripts may be installed in a location where they take
171 precedence over the implementation provided by Zsh. In this case,
172 to make full use of the script returned by git lfs completion zsh,
173 the _git completion script file installed by Homebrew for Git must
174 be moved or removed so it does not precede the Z shell’s own Git
175 completion script in the path order specified by fpath.
176
178 Loading completions for the current shell session
179 To load Git LFS command completions for the current shell session only,
180 execute the script generated by git lfs completion directly.
181 • Bash:
183 $ source <(git lfs completion bash)
185 Note that with Bash 3.2, the source builtin command will not
187 properly execute the output of a process substitution, and so it
188 will be necessary to use a temporary file instead:
189 $ git lfs completion bash >git-lfs-completion.bash
191 $ source git-lfs-completion.bash
192 • fish:
194 > git lfs completion fish | source
196 • zsh:
198 Note that the compinit function must also be executed to enable
200 tab-completion, as described in the SHELLS section.
201 % source <(git lfs completion zsh)
203 % compdef _git-lfs git-lfs
204 Automatically loading completions for future shell sessions
206 To load Git LFS command completions in all future shell sessions, store
207 the script generated by git lfs completion in a location where it will
208 be read by your shell during session startup.
209 • Bash:
211 As mentioned in the SHELLS section, the bash-completion package is
213 required by the Git LFS completion scripts for Bash, and it also
214 provides convenient utilities which search for completion scripts
215 in a set of defined locations and execute them during session
216 startup.
217 To load the Git LFS completion script in all future sessions
219 started by the current user (but not other users), store the script
220 in the bash-completion/completions directory within the location
221 defined by the XDG_DATA_HOME environment variable, or, if that
222 variable is not defined, the ~/.local/share directory. For example:
223 $ mkdir -p ~/.local/share/bash-completion/completions
225 $ git lfs completion bash >~/.local/share/bash-completion/completions/git-lfs
226 To load the completion script in all users' future sessions, store
228 the script instead in an appropriate system directory, which on
229 Linux may be /usr/share/bash-completion/completions, or on macOS,
230 if bash-completion was installed using Homebrew, may be the
231 share/bash-completion/completions directory within the location
232 returned by the brew --prefix command. These locations will vary
233 depending on how the bash-completion package was installed and
234 configured, however. For details, check the documentation relevant
235 to your system’s bash-completion package.
236 • fish:
238 The fish shell searches for completion scripts in a number of
240 locations, as described in the documentation:
241 https://fishshell.com/docs/current/completions.html#where-to-put-completions
243 To load the Git LFS completion script in all sessions started by
245 the current user (but not other users), store the script in the
246 fish/completions directory within the location defined by the
247 XDG_CONFIG_HOME environment variable, or, if that variable is not
248 defined, the ~/.config directory. For example:
249 > mkdir -p ~/.config/fish/completions
251 > git lfs completion fish >~/.config/fish/completions/git-lfs.fish
252 To load the completion script in all users' future sessions, store
254 the script in one of the other locations searched by the shell,
255 such under fish/completions within the shell’s system configuration
256 directory. On Linux this is typically /etc/fish/completions. On
257 macOS, when the fish shell is installed using Homebrew, this would
258 normally be the etc/fish/completions directory within the location
259 returned by the brew --prefix command.
260 • zsh:
262 Note that the compinit function must also be executed to enable
264 tab-completion, as described in the SHELLS section.
265 To load the Git LFS completion script in all sessions, store the
267 script as a file named _git-lfs in one of the locations listed in
268 the fpath variable. The specific location selected may affect
269 whether the completion script is loaded only for sessions started
270 by the current user or for all users' sessions, depending on how
271 the set of paths in the fpath array is constructed.
272 The following command will store the script in the first location
274 defined in fpath:
275 % git lfs completion zsh >"${fpath[1]}/_git-lfs"
277 You may also prefer to store the file in another location defined
279 in fpath, for instance, the last location, in which case
280 ${fpath[-1]} should be used instead.
281 It is also possible to add a custom location to the list in fpath
283 and store the Git LFS completion script there. To do this, add the
284 commands that update the fpath variable to a startup file such as
285 ~/.zshrc or /etc/zshrc so they will apply to all future sessions,
286 either for the current user or for all users.
287
289 Part of the git-lfs(1) suite.
290 GIT-LFS-COMPLETION(1)