diff --git a/en/book/02-git-basics/chapter2.asc b/en/book/02-git-basics/chapter2.asc index bef21f515..d8d9da928 100644 --- a/en/book/02-git-basics/chapter2.asc +++ b/en/book/02-git-basics/chapter2.asc @@ -877,19 +877,6 @@ b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unbor Of the nearly 40,000 commits in the Git source code history, this command shows the 6 that match those criteria. -==== Using a GUI to Visualize History - -If you like to use a more graphical tool to visualize your commit history, you may want to take a look at a Tcl/Tk program called gitk that is distributed with Git. -Gitk is basically a visual `git log` tool, and it accepts nearly all the filtering options that `git log` does. -If you type gitk on the command line in your project, you should see something like <>. - -[[gitk_visualizer]] -.The gitk history visualizer. -image::images/18333fig0202-tn.png[The gitk history visualizer.] - -You can see the commit history in the top half of the window along with a nice ancestry graph. -The diff viewer in the bottom half of the window shows you the changes introduced at any commit you click. - [[_undoing]] === Undoing Things diff --git a/en/book/10-git-in-other-environments/chapter10.asc b/en/book/10-git-in-other-environments/chapter10.asc index 9c809222a..03b27eb4a 100644 --- a/en/book/10-git-in-other-environments/chapter10.asc +++ b/en/book/10-git-in-other-environments/chapter10.asc @@ -1,31 +1,340 @@ == Git in Other Environments +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 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 -==== gitk & git-gui +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. + +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` and `git-gui` + +When you install Git, you also get its visual tools, `gitk` and `git-gui`. + +`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: + +[source,shell] +---- +$ gitk [git log options] +---- + +Gitk accepts many command-line options, most of which are passed through to the underlying `git log` action. +Probably one of the most useful is the `--all` flag, which tells gitk to show commits reachable from _any_ ref, not just HEAD. +Gitk's interface looks like <>. + +[[gitk]] +.The `gitk` history viewer. +image::images/gitk.png[The `gitk` history viewer.] + +On the top is something that looks a bit like the output of `git log --graph`; each dot represents a commit, the lines represent parent relationships, and refs are shown as colored boxes. +The yellow dot represents HEAD, and the red dot represents changes that are yet to become a commit. +At the bottom is a view of the selected commit; the comments and patch on the left, and a summary view on the right. +In between is a collection of controls used for searching history. + +`git-gui`, on the other hand, is primarily a tool for crafting commits. +It, too, is easiest to invoke from the command line: -==== GitHub for Windows/Mac +[source,shell] +----- +$ git gui +----- + +And it looks something like <>. + +[[git-gui]] +.The `git-gui` commit tool. +image::images/git-gui.png[The `git-gui` commit tool.] + +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. + + +==== GitHub Desktop + +**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 has been separated from this older feature, and the result is a much better fit between Studio and Git. + +To locate the feature, open a project that's controlled by Git (or just `git init` an existing project), and select View > Team Explorer from the menu. +You'll see the "Connect" view, which looks a bit like <>. + +[[vs_connect]] +.Connecting to a Git repository from Team Explorer. +image::images/vs-1.png[Connecting to a Git repository from Team Explorer.] + +Visual Studio remembers all of the projects you've opened that are Git-controlled, and they're available in the list at the bottom. +If you don't see the one you want there, click the "Add" link and type in the path to the working directory. +Double clicking on one of the local Git repositories leads you to the Home view, which looks like <>. +This is a hub for performing Git actions; when you're _writing_ code, you'll probably spend most of your time in the "Changes" view, but when it comes time to pull down changes made by your teammates, you'll use the "Unsynced Commits" and "Branches" views. + +[[vs_home]] +.The "Home" view for a Git repository in Visual Studio. +image::images/vs-2.png[The "Home" view for a Git repository in Visual Studio.] + +Visual Studio now has a powerful task-focused UI for Git. +It includes a linear history view, a diff viewer, remote commands, and many other capabilities. +For complete documentation of this feature (which doesn't fit here), go to http://msdn.microsoft.com/en-us/library/hh850437.aspx[]. + === Git in Eclipse +Eclipse ships with a plugin called Egit, which provides a fairly-complete interface to Git operations. +It's accessed by switching to the Git Perspective (Window > Open Perpective > Other…, and select "Git"). + +[[egit]] +.Eclipse's EGit environment. +image::images/egit.png[Eclipse's EGit environment.] + +EGit comes with plenty of great documentation, which you can find by going to Help > Help Contents, and choosing the "EGit Documentation" node from the contents listing. + === 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. + +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] +----- +. ~/git-completion.bash +----- + +Once that's done, change your directory to a git repository, and type: + +[source,shell] +---- +$ git chec +---- + +…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)")\$ ' +----- + +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 <> 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 +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 +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 a display of the current branch on the right-hand side of the terminal window, whenever your shell is inside a Git repository. It looks a bit like <>. + +[[zsh_git]] +.Customized `zsh` prompt. +image::images/zsh-prompt.png[Customized `zsh` prompt.] + +Zsh is powerful enough that there are entire frameworks dedicated to making it better. +One of them is called "oh-my-zsh", and it can be found at https://github.com/robbyrussell/oh-my-zsh[]. +oh-my-zsh's plugin system comes with powerful git tab-completion, and it has a variety of prompt "themes", many of which display version-control data. +<> is just one example of what can be done with this system. + +[[oh_my_zsh_git]] +.An example of an oh-my-zsh theme. +image::images/zsh-oh-my.png[An example of an oh-my-zsh theme.] + + === 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]] +.Powershell with Posh-git. +image::images/posh-git.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\\Documents\WindowsPowerShell`): + +[source,powershell] +----- +. (Resolve-Path "$env:LOCALAPPDATA\GitHub\shell.ps1") +. $env:github_posh_git\profile.example.ps1 +----- + +If you're not a GitHub for Windows user, just download a Posh-Git release from (https://github.com/dahlbyk/posh-git[]), and uncompress it to the `WindowsPowershell` directory. +Then open a Powershell prompt as the administrator, and do this: + +[source,powershell] +----- +> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Confirm +> cd ~\Documents\WindowsPowerShell\posh-git +> .\install.ps1 +----- + +This will add the proper line to your `profile.ps1` file, and posh-git will be active the next time you open your prompt. + === 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: + +[source,c] +----- +git_repository *repo; +int error = git_repository_open(&repo, "/path/to/repository"); + +git_object *head_commit; +error = git_revparse_single(&head_commit, repo, "HEAD^{commit}"); + +git_commit *commit = (git_commit*)head_commit; +printf("%s", git_commit_message); +----- + +Of course, it isn't very probable 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 (https://github.com/libgit2/libgit2sharp[]) 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: + +[source,csharp] +----- +new Repository(@"C:\path\to\repo").Head.Tip.Message; +----- + +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 (https://github.com/libgit2/objective-git[]) is the name of the Libgit2 bindings for that environment. +Again, here's how to read HEAD's commit message: + +[source,objc] +----- +GTRepository *repo = + [[GTRepository alloc] initWithURL:[NSURL fileURLWithPath: @"/path/to/repo"] error:NULL]; +NSString *msg = [[[repo headReferenceWithError:NULL] resolvedTarget] message]; +----- + +===== rugged + +For Ruby programs, Rugged (https://github.com/libgit2/rugged[]) is the library to use. +Once again, HEAD's commit message: + +[source,ruby] +---- +repo = Rugged::Repository.new('path/to/my/repository') +msg = repo.lookup(repo.head.resolve.target).message +---- + + +===== pygit2 + +The bindings for Libgit2 in Python are called Pygit2, and can be found at http://www.pygit2.org/[]. +As always, HEAD's commit message: -==== libgit2sharp +[source,python] +---- +pygit2.Repository("/path/to/repo").head.resolve().get_object().message +---- -==== objective-git -==== 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/[]. diff --git a/en/book/images/egit.png b/en/book/images/egit.png new file mode 100644 index 000000000..62796ae70 Binary files /dev/null and b/en/book/images/egit.png differ diff --git a/en/book/images/git-bash.png b/en/book/images/git-bash.png new file mode 100644 index 000000000..3987ec967 Binary files /dev/null and b/en/book/images/git-bash.png differ diff --git a/en/book/images/git-gui.png b/en/book/images/git-gui.png new file mode 100644 index 000000000..a6b7ca38f Binary files /dev/null and b/en/book/images/git-gui.png differ diff --git a/en/book/images/gitk.png b/en/book/images/gitk.png new file mode 100644 index 000000000..a7dda0f81 Binary files /dev/null and b/en/book/images/gitk.png differ diff --git a/en/book/images/posh-git.png b/en/book/images/posh-git.png new file mode 100644 index 000000000..5da5747b7 Binary files /dev/null and b/en/book/images/posh-git.png differ diff --git a/en/book/images/vs-1.png b/en/book/images/vs-1.png new file mode 100644 index 000000000..87613b8b8 Binary files /dev/null and b/en/book/images/vs-1.png differ diff --git a/en/book/images/vs-2.png b/en/book/images/vs-2.png new file mode 100644 index 000000000..8d08ea9ed Binary files /dev/null and b/en/book/images/vs-2.png differ diff --git a/en/book/images/zsh-oh-my.png b/en/book/images/zsh-oh-my.png new file mode 100644 index 000000000..a2eb7fa30 Binary files /dev/null and b/en/book/images/zsh-oh-my.png differ diff --git a/en/book/images/zsh-prompt.png b/en/book/images/zsh-prompt.png new file mode 100644 index 000000000..4ddefddcf Binary files /dev/null and b/en/book/images/zsh-prompt.png differ