GUIs part 2, shells, libgit2

Author: ben

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

@@ -2,29 +2,33 @@
 
 If you've read this far, you've learned a lot about how to use Git at the command line.
 You can work with local files, connect your repository to others over a network, and work effectively with others.
-But the story doesn't end there; Git is usually used as part of a larger ecosystem, and the terminal isn't always the best way to work with Git.
-Now we'll take a look at some of the other kinds of environments where Git can be useful.
+But the story doesn't end there; Git is usually used as part of a larger ecosystem, and the terminal isn't always the best way to work with it.
+Now we'll take a look at some of the other kinds of environments where Git can be useful, and how other applications (including yours) work alongside Git.
 
 === Graphical Interfaces
 
 Git's native environment is in the terminal.
 New features show up there first, and only at the command line is the full power of Git completely at your disposal.
 But plain text isn't the best choice for all tasks; sometimes a visual representation is what you need, and some users are much more comfortable with a point-and-click interface.
 
-Remember that different interfaces are tailored for different workflows.
-Some clients only expose only a carefully curated subset of Git functionality, in order to support a specific way of using Git that the author considers effective.
-When viewed in this light, none of these tools is ``better'' than any of the others, they're simply more fit for their intended purpose.
-Also note that there's nothing these graphical clients can do that the command-line client can't.
+It's important to note that different interfaces are tailored for different workflows.
+Some clients only expose only a carefully curated subset of Git functionality, in order to support a specific way of working that the author considers effective.
+When viewed in this light, none of these tools can be called ``better'' than any of the others, they're simply more fit for their intended purpose.
+Also note that there's nothing these graphical clients can do that the command-line client can't; the command-line is still where you'll have the most power and control when working with your repositories.
 
-==== gitk & git-gui
+==== +gitk+ and +git-gui+
 
 When you install Git, you also get its visual tools, `gitk` and `git-gui`.
 
-`gitk` is a graphical shell over `git log`, and it acts primarily as a history viewer.
-It is easiest to invoke from the command-line; `cd` into a Git repository, and type:
+`gitk` is a graphical history viewer.
+Think of it like a powerful GUI shell over +git log+ and +git grep+.
+This is the tool to use when you're trying to find something that happened in the past, or visualize your project's history.
+
+Gitk is easiest to invoke from the command-line.
+Just `cd` into a Git repository, and type:
 
 -----
-gitk [git log options]
+$ gitk [git log options]
 -----
 
 Gitk accepts many command-line options, most of which are passed through to the underlying `git log` action.
@@ -44,7 +48,7 @@ In between is a collection of controls used for searching history.
 It, too, is easiest to invoke from the command line:
 
 -----
-git gui
+$ git gui
 -----
 
 And it looks something like <<git-gui>>.
@@ -53,28 +57,190 @@ And it looks something like <<git-gui>>.
 .The `git-gui` commit tool.
 image::images/git-gui.png[The `git-gui` commit tool.]
 
-==== GitHub for Windows/Mac
+On the left is the index; unstaged changes are on top, staged changes on the bottom.
+You can move entire files between the two states by clicking on their icons, or you can select a file for viewing by clicking on its name.
+
+At top right is the diff view, which shows the changes for the currently-selected file.
+You can stage individual hunks (or individual lines) by right-clicking in this area.
+
+At the bottom right is the message and action area. Type your message into the text box and click ``Commit'' to do something similar to +git commit+.
+You can also choose to amend the last commit by choosing the ``Amend'' radio button, which will update the ``Staged Changes'' area with the contents of the last commit.
+Then you can simply stage or unstage some changes, alter the commit message, and click ``Commit'' again to replace the old commit with a new one.
+
++gitk+ and +git-gui+ are examples of task-oriented tools.
+Each of them is tailored for a specific purpose (viewing history and creating commits, respectively), and omit the features not necessary for that task.
+There are several other graphical tools in this category, such as TODO.
+
+==== GitHub Desktop
+
+
+
+[[github_win]]
+.GitHub for Windows.
+image::images/github-win.png[GitHub for Windows.]
+
+[[github_mac]]
+.GitHub for Mac.
+image::images/github-win.png[GitHub for Mac.]
+
+// TODO: wait for Desktop? At least for source-list on Windows.
 
 ==== Other GUIs
 
+There are a number of other graphical Git clients, and they run the gamut from specialized, single-purpose tools all the way to apps that try to expose everything Git can do.
+The official Git website has a curated list of the most popular clients at http://git-scm.com/downloads/guis[].
+A more comprehensive list is available on the Git wiki site, at https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools#Graphical_Interfaces[].
+
 === Git in Visual Studio
 
+Starting with Visual Studio 2013 Update 1, Visual Studio users have a Git client built directly into their IDE.
+Visual Studio has had source-control integration features for quite some time, but they were oriented towards centralized, file-locking systems, and Git was not a good match for this workflow.
+Visual Studio 2013's Git support is a separate feature with its own command pane, but integrates with your day-to-day work just as well as the older feature.
+
+* Commiting
+* diffing
+* history
+* syncing
+* others?
+
 === Git in Eclipse
 
+// TODO: Egit
+
+* Commiting
+* diffing
+* history
+* syncing
+* others?
+
 === 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.
+
+One way is by enabling tab-completion.
+// TODO
+
+To enable the tab-completion plugin, open your +.bashrc+ and add a line like this:
+
+-----
+# TODO
+-----
+
+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+:
+
+-----
+. ~/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.
+
+[[git_bash]]
+.Customized +bash+ prompt.
+image::images/git-bash.png[Customized +bash+ prompt.]
+
 === Git in Zsh
 
+If you're a Zsh user, TODO
+
+* tab completion in the box?
+* raw zsh custom prompt
+* oh-my-zsh, themes
+
 === Git in Powershell
 
+The standard command-line terminal on Windows (+cmd.exe+) isn't really capable of a customized Git experience, but if you're using Powershell, you're in luck.
+A package called Posh-Git (TODO: URL) provides powerful tab-completion facilities, as well as an enhanced prompt to help you stay on top of your repostitory status. It looks like <<git_posh>>.
+
+[[git_posh]]
+.Powershell with Posh-git.
+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+):
+
+-----
+# 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+:
+
+-----
+# TODO
+-----
+
 === Git in Your Application
 
-==== libgit2
+If your application is for developers, chances are good that it could benefit from integration with source control.
+Even other applications, such as document editors, could potentially benefit from version-control features, and Git's model works very well for many different scenarios.
+
+Beyond the most trivial use-cases, if you want to make your app work with Git repositories, you have essentially two choices.
+
+==== Command-line Git
+
+One option is to spawn a shell process and use the Git command-line tool to do the work.
+This has the benefit of being canonical, and all of Git's features are supported.
+This also happens to be fairly easy, as most runtime environments have a relatively simple facility for invoking a process with command-line arguments.
+However, this approach does have some downsides.
+
+One is that all the output is in plain text.
+This means that you'll have to parse Git's occasionally-changing output format to read progress and result information, which can be inefficient and error-prone.
+
+Another is the lack of error recovery.
+If a repository is corrupted somehow, or the user has a malformed configuration value, Git will simply refuse to perform many operations.
+
+Yet another is process management.
+Git requires you to maintain a shell environment on a separate process, which can add unwanted complexity.
+Trying to coordinate many of these processes (especially when potentially accessing the same repository from several processes) can be quite a challenge.
+
+==== Libgit2
+
+The other option at your disposal is to use Libgit2.
+Libgit2 is a dependency-free implementation of Git, with a focus on having a nice API for use within other programs.
+
+Here's what it looks like to read HEAD's commit message with Libgit2:
+
+-----
+// TODO
+-----
+
+Of course, it isn't very probably that you'll want to write C when using Libgit2.
+Fortunately, there are a number of language-specific bindings available that make it fairly easy to work with Git repositories from your specific language and environment.
+
+===== LibGit2Sharp
+
+If you're writing a .NET or Mono application, LibGit2Sharp (http://libgit2sharp.github.io/[]) is what you're looking for.
+The bindings are written in C#, and great care has been taken to wrap the raw Libgit2 calls with native-feeling CLR APIs.
+Here's what it looks like to read HEAD's commit message:
+
+-----
+// TODO
+-----
+
+For desktop Windows applications, there's a NuGet package that will help you get started quickly.
+// TODO: will this work under WinRT? Probably not.
+
+===== objective-git
+
+If your application is running on an Apple platform, you're likely using Objective C as your implementation language.
+Objective-Git (TODO: URL) is the name of the Libgit2 bindings for that environment.
+Again, here's how to read HEAD's commit message:
+
+-----
+// TODO
+-----
+
+===== rugged
+
+For Ruby programs, Rugged (TODO: URL) is the library to use.
 
-==== libgit2sharp
+===== pygit2
 
-==== objective-git
+The bindings for Libgit2 in Python are called Pygit2, and can be found at (TODO: URL).
 
-==== rugged
+===== Others
 
-==== pygit2
+Libgit2 has been bound for a wide variety of programming languages and environments, including C++, Go, Node.js, Erlang, and the JVM.
+The official collection of bindings can be found by browsing the repositories at https://github.com/libgit2/[].