Shell completions, part 2

Author: ben

en/book/10-git-in-other-environments/chapter10.asc

@@ -116,39 +116,80 @@ Visual Studio 2013's Git support is a separate feature with its own command pane
 === Git in Bash
 
 If you're a Bash user, you can tap into some of your shell's features to make your experience with Git a lot friendlier.
+Git actually ships with plugins for several shells, but it's not turned on by default.
 
-One way is by enabling tab-completion.
-// TODO
-
-To enable the tab-completion plugin, open your +.bashrc+ and add a line like this:
+First, you need to get a copy of the `contrib/completion/git-completion.bash` file out of the Git source code.
+Copy it somewhere handy, like your home directory, and add this to your `.bashrc`:
 
+[source,shell]
 -----
-# TODO
+. ~/git-completion.bash
 -----
 
+Once that's done, change your directory to a git repository, and type:
+
+[source,shell]
+----
+$ git chec<tab>
+----
+
+…and Bash will auto-complete to `git checkout`.
+This works with all of Git's subcommands, command-line parameters, and remotes and ref names where appropriate.
+
 It's also useful to customize your prompt to show information about the current directory's Git repository.
 This can be as simple or complex as you want, but there are generally a few key pieces of information that most people want, like the current branch, and the status of the working directory.
 To add these to your prompt, just copy the `contrib/completion/git-prompt.sh` file from Git's source repository to your home directory, add something like this to your +.bashrc+:
 
+[source,shell]
 -----
 . ~/git-prompt.sh
 export GIT_PS1_SHOWDIRTYSTATE=1
 export PS1='\w$(__git_ps1 " (%s)")\$ '
 -----
 
-This makes your shell prompt look like <<git_bash>> when you're anywhere inside a Git-controlled project.
+The `\w` means print the current working directory, the `\$` prints the `$` part of the prompt, and `__git_ps1 " (%s)"` calls the function provided by `git-prompt.sh` with a formatting argument.
+Now your bash prompt will look like <<git_bash>> when you're anywhere inside a Git-controlled project.
 
 [[git_bash]]
 .Customized +bash+ prompt.
 image::images/git-bash.png[Customized +bash+ prompt.]
 
+Both of these scripts come with helpful documentation; take a look at the contents of `git-completion.bash` and `git-prompt.sh` for more information.
+
 === Git in Zsh
 
-If you're a Zsh user, TODO
+Git also ships with a tab-completion library for Zsh.
+Just copy `contrib/completion/git-completion.zsh` to your home directory and source it from your `.zshrc`.
+Zsh's interface is a bit more powerful than Bash's:
+
+[source,shell]
+----
+$ git che<tab>
+check-attr        -- display gitattributes information
+check-ref-format  -- ensure that a reference name is well formed
+checkout          -- checkout branch or paths to working tree
+checkout-index    -- copy files from index to working directory
+cherry            -- find commits not merged upstream
+cherry-pick       -- apply changes introduced by some existing commits
+----
+
+Ambiguous tab-completions aren't just listed.
+They have helpful descriptions, and you can graphically navigate the list by repeatedly hitting tab.
+This works with Git commands, their arguments, and names of things inside the repository (like refs and remotes), as well filenames and all the other things Zsh knows how to tab-complete.
+
+Zsh happens to be fairly compatible with Bash when it comes to prompt customization, but it allows you to have a right-side prompt as well.
+To include the branch name on the right side, add these lines to your `~/.zshrc` file:
+
+[source,shell]
+----
+setopt prompt_subst
+. ~/git-prompt.sh
+export RPROMPT=$'$(__git_ps1 "%s")'
+----
+
+This results in TODO
 
-* tab completion in the box?
-* raw zsh custom prompt
-* oh-my-zsh, themes
+TODO: oh-my-zsh, themes
 
 === Git in Powershell
 
@@ -161,12 +202,14 @@ image::images/git-posh.png[Powershell with Posh-git.]
 
 If you've installed GitHub for Windows, Posh-Git is included by default, and all you have to do is add these lines to your +profile.ps1+ (which is usually located in +C:\Users\<username>\Documents\WindowsPowerShell+):
 
+[source,powershell]
 -----
 # TODO
 -----
 
 If you're not a GitHub for Windows user, just download a Posh-Git release from (TODO: URL), uncompress it to the +WindowsPowershell+ directory, and add this to your +profile.ps1+:
 
+[source,powershell]
 -----
 # TODO
 -----