diff --git a/A-git-in-other-environments.asc b/A-git-in-other-environments.asc index 5f7139dd..32d7f616 100644 --- a/A-git-in-other-environments.asc +++ b/A-git-in-other-environments.asc @@ -1,4 +1,4 @@ -[#A-git-in-other-environments] +[[A-git-in-other-environments]] [appendix] == Git in Other Environments @@ -11,8 +11,11 @@ include::book/A-git-in-other-environments/sections/guis.asc[] include::book/A-git-in-other-environments/sections/visualstudio.asc[] -include::book/A-git-in-other-environments/sections/eclipse.asc[] +include::book/A-git-in-other-environments/sections/visualstudiocode.asc[] +include::book/A-git-in-other-environments/sections/jetbrainsides.asc[] + +include::book/A-git-in-other-environments/sections/sublimetext.asc[] include::book/A-git-in-other-environments/sections/bash.asc[] diff --git a/B-embedding-git.asc b/B-embedding-git.asc index 85c46d50..782e177d 100644 --- a/B-embedding-git.asc +++ b/B-embedding-git.asc @@ -1,14 +1,20 @@ -[#B-embedding-git] +[[B-embedding-git-in-your-applications]] [appendix] == Embedding Git in your Applications If your application is for developers, chances are good that it could benefit from integration with source control. Even non-developer applications, such as document editors, could potentially benefit from version-control features, and Git's model works very well for many different scenarios. -If you need to integrate Git with your application, you have essentially three choices: spawning a shell and using the Git command-line tool; Libgit2; and JGit. +If you need to integrate Git with your application, you have essentially two options: spawn a shell and call the `git` command-line program, or embed a Git library into your application. +Here we'll cover command-line integration and several of the most popular embeddable Git libraries. include::book/B-embedding-git/sections/command-line.asc[] include::book/B-embedding-git/sections/libgit2.asc[] include::book/B-embedding-git/sections/jgit.asc[] + +include::book/B-embedding-git/sections/go-git.asc[] + +include::book/B-embedding-git/sections/dulwich.asc[] + diff --git a/C-git-commands.asc b/C-git-commands.asc index 50830d84..db01461f 100644 --- a/C-git-commands.asc +++ b/C-git-commands.asc @@ -1,4 +1,4 @@ -[#C-git-commands] +[[C-git-commands]] [appendix] == Git Commands @@ -8,6 +8,13 @@ However, this leaves us with examples of usage of the commands somewhat scattere In this appendix, we'll go through all the Git commands we addressed throughout the book, grouped roughly by what they're used for. We'll talk about what each command very generally does and then point out where in the book you can find us having used it. +[TIP] +==== +You can abbreviate long options. +For example, you can type in `git commit --a`, which acts as if you typed `git commit --amend`. +This only works when the letters after `--` are unique for one option. +Do use the full option when writing scripts. +==== === Setup and Config @@ -22,24 +29,61 @@ There are several files this command will read from and write to so you can set The `git config` command has been used in nearly every chapter of the book. -In <> we used it to specify our name, email address and editor preference before we even got started using Git. - -In <> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. - -In <> we used it to make `--rebase` the default when you run `git pull`. - -In <> we used it to set up a default store for your HTTP passwords. - -In <> we showed how to set up smudge and clean filters on content coming in and out of Git. - -Finally, basically the entirety of <> is dedicated to the command. +In <> we used it to specify our name, email address and editor preference before we even got started using Git. + +In <> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. + +In <> we used it to make `--rebase` the default when you run `git pull`. + +In <> we used it to set up a default store for your HTTP passwords. + +In <> we showed how to set up smudge and clean filters on content coming in and out of Git. + +Finally, basically the entirety of <> is dedicated to the command. + +[[ch_core_editor]] +==== git config core.editor commands + +Accompanying the configuration instructions in <>, many editors can be set as follows: + +.Exhaustive list of `core.editor` configuration commands +[cols="1,2",options="header"] +|============================== +|Editor | Configuration command +|Atom |`git config --global core.editor "atom --wait"` +|BBEdit (Mac, with command line tools) |`git config --global core.editor "bbedit -w"` +|Emacs |`git config --global core.editor emacs` +|Gedit (Linux) |`git config --global core.editor "gedit --wait --new-window"` +|Gvim (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Vim\vim72\gvim.exe' --nofork '%*'"` (Also see note below) +|Kate (Linux) |`git config --global core.editor "kate"` +|nano |`git config --global core.editor "nano -w"` +|Notepad (Windows 64-bit) |`git config core.editor notepad` +|Notepad++ (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` (Also see note below) +|Scratch (Linux)|`git config --global core.editor "scratch-text-editor"` +|Sublime Text (macOS) |`git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl --new-window --wait"` +|Sublime Text (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Sublime Text 3\sublime_text.exe' -w"` (Also see note below) +|TextEdit (macOS)|`git config --global core.editor "open --wait-apps --new -e"` +|Textmate |`git config --global core.editor "mate -w"` +|Textpad (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\TextPad 5\TextPad.exe' -m` (Also see note below) +|UltraEdit (Windows 64-bit) | `git config --global core.editor Uedit32` +|Vim |`git config --global core.editor "vim"` +|Visual Studio Code |`git config --global core.editor "code --wait"` +|VSCodium (Free/Libre Open Source Software Binaries of VSCode) | `git config --global core.editor "codium --wait"` +|WordPad |`git config --global core.editor '"C:\Program Files\Windows NT\Accessories\wordpad.exe"'"` +|Xi | `git config --global core.editor "xi --wait"` +|============================== + +[NOTE] +==== +If you have a 32-bit editor on a Windows 64-bit system, the program will be installed in `C:\Program Files (x86)\` rather than `C:\Program Files\` as in the table above. +==== ==== git help The `git help` command is used to show you all the documentation shipped with Git about any command. While we're giving a rough overview of most of the more popular ones in this appendix, for a full listing of all of the possible options and flags for every command, you can always run `git help `. -We introduced the `git help` command in <> and showed you how to use it to find more information about the `git shell` in <>. +We introduced the `git help` command in <> and showed you how to use it to find more information about the `git shell` in <>. === Getting and Creating Projects @@ -51,13 +95,13 @@ One is to copy it from an existing repository on the network or elsewhere and th To take a directory and turn it into a new Git repository so you can start version controlling it, you can simply run `git init`. -We first introduce this in <>, where we show creating a brand new repository to start working with. +We first introduce this in <>, where we show creating a brand new repository to start working with. -We talk briefly about how you can change the default branch from ``master'' in <>. +We talk briefly about how you can change the default branch name from "`master`" in <>. -We use this command to create an empty bare repository for a server in <>. +We use this command to create an empty bare repository for a server in <>. -Finally, we go through some of the details of what it actually does behind the scenes in <>. +Finally, we go through some of the details of what it actually does behind the scenes in <>. ==== git clone @@ -66,13 +110,13 @@ It creates a new directory, goes into it and runs `git init` to make it an empty The `git clone` command is used in dozens of places throughout the book, but we'll just list a few interesting places. -It's basically introduced and explained in <>, where we go through a few examples. +It's basically introduced and explained in <>, where we go through a few examples. -In <> we look at using the `--bare` option to create a copy of a Git repository with no working directory. +In <> we look at using the `--bare` option to create a copy of a Git repository with no working directory. -In <> we use it to unbundle a bundled Git repository. +In <> we use it to unbundle a bundled Git repository. -Finally, in <> we learn the `--recursive` option to make cloning a repository with submodules a little simpler. +Finally, in <> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler. Though it's used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different. @@ -83,19 +127,19 @@ For the basic workflow of staging content and committing it to your history, the ==== git add -The `git add` command adds content from the working directory into the staging area (or ``index'') for the next commit. +The `git add` command adds content from the working directory into the staging area (or "`index`") for the next commit. When the `git commit` command is run, by default it only looks at this staging area, so `git add` is used to craft what exactly you would like your next commit snapshot to look like. This command is an incredibly important command in Git and is mentioned or used dozens of times in this book. We'll quickly cover some of the unique uses that can be found. -We first introduce and explain `git add` in detail in <>. +We first introduce and explain `git add` in detail in <>. -We mention how to use it to resolve merge conflicts in <>. +We mention how to use it to resolve merge conflicts in <>. -We go over using it to interactively stage only specific parts of a modified file in <>. +We go over using it to interactively stage only specific parts of a modified file in <>. -Finally, we emulate it at a low level in <>, so you can get an idea of what it's doing behind the scenes. +Finally, we emulate it at a low level in <>, so you can get an idea of what it's doing behind the scenes. ==== git status @@ -103,7 +147,7 @@ The `git status` command will show you the different states of files in your wor Which files are modified and unstaged and which are staged but not yet committed. In its normal form, it also will show you some basic hints on how to move files between these stages. -We first cover `status` in <>, both in its basic and simplified forms. +We first cover `status` in <>, both in its basic and simplified forms. While we use it throughout the book, pretty much everything you can do with the `git status` command is covered there. ==== git diff @@ -111,36 +155,36 @@ While we use it throughout the book, pretty much everything you can do with the The `git diff` command is used when you want to see differences between any two trees. This could be the difference between your working environment and your staging area (`git diff` by itself), between your staging area and your last commit (`git diff --staged`), or between two commits (`git diff master branchB`). -We first look at the basic uses of `git diff` in <>, where we show how to see what changes are staged and which are not yet staged. +We first look at the basic uses of `git diff` in <>, where we show how to see what changes are staged and which are not yet staged. -We use it to look for possible whitespace issues before committing with the `--check` option in <>. +We use it to look for possible whitespace issues before committing with the `--check` option in <>. -We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <>. +We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <>. -We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <>. +We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <>. -Finally, we use it to effectively compare submodule changes with `--submodule` in <>. +Finally, we use it to effectively compare submodule changes with `--submodule` in <>. ==== git difftool The `git difftool` command simply launches an external tool to show you the difference between two trees in case you want to use something other than the built in `git diff` command. -We only briefly mention this in <>. +We only briefly mention this in <>. ==== git commit The `git commit` command takes all the file contents that have been staged with `git add` and records a new permanent snapshot in the database and then moves the branch pointer on the current branch up to it. -We first cover the basics of committing in <>. +We first cover the basics of committing in <>. There we also demonstrate how to use the `-a` flag to skip the `git add` step in daily workflows and how to use the `-m` flag to pass a commit message in on the command line instead of firing up an editor. -In <> we cover using the `--amend` option to redo the most recent commit. +In <> we cover using the `--amend` option to redo the most recent commit. -In <>, we go into much more detail about what `git commit` does and why it does it like that. +In <>, we go into much more detail about what `git commit` does and why it does it like that. -We looked at how to sign commits cryptographically with the `-S` flag in <>. +We looked at how to sign commits cryptographically with the `-S` flag in <>. -Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <>. +Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <>. ==== git reset @@ -148,34 +192,34 @@ The `git reset` command is primarily used to undo things, as you can possibly te It moves around the `HEAD` pointer and optionally changes the `index` or staging area and can also optionally change the working directory if you use `--hard`. This final option makes it possible for this command to lose your work if used incorrectly, so make sure you understand it before using it. -We first effectively cover the simplest use of `git reset` in <>, where we use it to unstage a file we had run `git add` on. +We first effectively cover the simplest use of `git reset` in <>, where we use it to unstage a file we had run `git add` on. -We then cover it in quite some detail in <>, which is entirely devoted to explaining this command. +We then cover it in quite some detail in <>, which is entirely devoted to explaining this command. -We use `git reset --hard` to abort a merge in <>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. +We use `git reset --hard` to abort a merge in <>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. ==== git rm The `git rm` command is used to remove files from the staging area and working directory for Git. It is similar to `git add` in that it stages a removal of a file for the next commit. -We cover the `git rm` command in some detail in <>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. +We cover the `git rm` command in some detail in <>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. -The only other differing use of `git rm` in the book is in <> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. +The only other differing use of `git rm` in the book is in <> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. This can be useful for scripting purposes. ==== git mv The `git mv` command is a thin convenience command to move a file and then run `git add` on the new file and `git rm` on the old file. -We only briefly mention this command in <>. +We only briefly mention this command in <>. ==== git clean The `git clean` command is used to remove unwanted files from your working directory. This could include removing temporary build artifacts or merge conflict files. -We cover many of the options and scenarios in which you might used the clean command in <>. +We cover many of the options and scenarios in which you might used the clean command in <>. === Branching and Merging @@ -187,47 +231,47 @@ The `git branch` command is actually something of a branch management tool. It can list the branches you have, create a new branch, delete branches and rename branches. Most of <> is dedicated to the `branch` command and it's used throughout the entire chapter. -We first introduce it in <> and we go through most of its other features (listing and deleting) in <>. +We first introduce it in <> and we go through most of its other features (listing and deleting) in <>. -In <> we use the `git branch -u` option to set up a tracking branch. +In <> we use the `git branch -u` option to set up a tracking branch. -Finally, we go through some of what it does in the background in <>. +Finally, we go through some of what it does in the background in <>. ==== git checkout The `git checkout` command is used to switch branches and check content out into your working directory. -We first encounter the command in <> along with the `git branch` command. +We first encounter the command in <> along with the `git branch` command. -We see how to use it to start tracking branches with the `--track` flag in <>. +We see how to use it to start tracking branches with the `--track` flag in <>. -We use it to reintroduce file conflicts with `--conflict=diff3` in <>. +We use it to reintroduce file conflicts with `--conflict=diff3` in <>. -We go into closer detail on its relationship with `git reset` in <>. +We go into closer detail on its relationship with `git reset` in <>. -Finally, we go into some implementation detail in <>. +Finally, we go into some implementation detail in <>. ==== git merge The `git merge` tool is used to merge one or more branches into the branch you have checked out. It will then advance the current branch to the result of the merge. -The `git merge` command was first introduced in <>. +The `git merge` command was first introduced in <>. Though it is used in various places in the book, there are very few variations of the `merge` command -- generally just `git merge ` with the name of the single branch you want to merge in. -We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <>. +We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <>. -We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <>. +We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <>. -We learned how to verify signatures before merging if your project is using GPG signing in <>. +We learned how to verify signatures before merging if your project is using GPG signing in <>. -Finally, we learned about Subtree merging in <>. +Finally, we learned about Subtree merging in <>. ==== git mergetool The `git mergetool` command simply launches an external merge helper in case you have issues with a merge in Git. -We mention it quickly in <> and go into detail on how to implement your own external merge tool in <>. +We mention it quickly in <> and go into detail on how to implement your own external merge tool in <>. ==== git log @@ -237,37 +281,37 @@ It is also often used to show differences between two or more branches at the co This command is used in nearly every chapter of the book to demonstrate the history of a project. -We introduce the command and cover it in some depth in <>. +We introduce the command and cover it in some depth in <>. There we look at the `-p` and `--stat` option to get an idea of what was introduced in each commit and the `--pretty` and `--oneline` options to view the history more concisely, along with some simple date and author filtering options. -In <> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. +In <> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. -In <> and <> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. -In <> we go through this fairly extensively. +In <> and <> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. +In <> we go through this fairly extensively. -In <> and <> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. -In <> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. +In <> and <> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. +In <> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. -In <> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. +In <> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. -In <> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. +In <> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. -In <> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. +In <> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. ==== git stash The `git stash` command is used to temporarily store uncommitted work in order to clean out your working directory without having to commit unfinished work on a branch. -This is basically entirely covered in <>. +This is basically entirely covered in <>. ==== git tag The `git tag` command is used to give a permanent bookmark to a specific point in the code history. Generally this is used for things like releases. -This command is introduced and covered in detail in <> and we use it in practice in <>. +This command is introduced and covered in detail in <> and we use it in practice in <>. -We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <>. +We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <>. === Sharing and Updating Projects @@ -279,54 +323,54 @@ When you are ready to share your work or pull changes from elsewhere, there are The `git fetch` command communicates with a remote repository and fetches down all the information that is in that repository that is not in your current one and stores it in your local database. -We first look at this command in <> and we continue to see examples of it use in <>. +We first look at this command in <> and we continue to see examples of its use in <>. -We also use it in several of the examples in <>. +We also use it in several of the examples in <>. -We use it to fetch a single specific reference that is outside of the default space in <> and we see how to fetch from a bundle in <>. +We use it to fetch a single specific reference that is outside of the default space in <> and we see how to fetch from a bundle in <>. -We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <>. +We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <>. ==== git pull The `git pull` command is basically a combination of the `git fetch` and `git merge` commands, where Git will fetch from the remote you specify and then immediately try to merge it into the branch you're on. -We introduce it quickly in <> and show how to see what it will merge if you run it in <>. +We introduce it quickly in <> and show how to see what it will merge if you run it in <>. -We also see how to use it to help with rebasing difficulties in <>. +We also see how to use it to help with rebasing difficulties in <>. -We show how to use it with a URL to pull in changes in a one-off fashion in <>. +We show how to use it with a URL to pull in changes in a one-off fashion in <>. -Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <>. +Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <>. ==== git push The `git push` command is used to communicate with another repository, calculate what your local database has that the remote one does not, and then pushes the difference into the other repository. It requires write access to the other repository and so normally is authenticated somehow. -We first look at the `git push` command in <>. +We first look at the `git push` command in <>. Here we cover the basics of pushing a branch to a remote repository. -In <> we go a little deeper into pushing specific branches and in <> we see how to set up tracking branches to automatically push to. -In <> we use the `--delete` flag to delete a branch on the server with `git push`. +In <> we go a little deeper into pushing specific branches and in <> we see how to set up tracking branches to automatically push to. +In <> we use the `--delete` flag to delete a branch on the server with `git push`. -Throughout <> we see several examples of using `git push` to share work on branches through multiple remotes. +Throughout <> we see several examples of using `git push` to share work on branches through multiple remotes. -We see how to use it to share tags that you have made with the `--tags` option in <>. +We see how to use it to share tags that you have made with the `--tags` option in <>. -In <> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. +In <> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. -In <> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. +In <> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. -Finally, in <> we look at pushing with a full refspec instead of the general shortcuts that are normally used. +Finally, in <> we look at pushing with a full refspec instead of the general shortcuts that are normally used. This can help you be very specific about what work you wish to share. ==== git remote The `git remote` command is a management tool for your record of remote repositories. -It allows you to save long URLs as short handles, such as ``origin'' so you don't have to type them out all the time. +It allows you to save long URLs as short handles, such as "`origin`" so you don't have to type them out all the time. You can have several of these and the `git remote` command is used to add, change and delete them. -This command is covered in detail in <>, including listing, adding, removing and renaming them. +This command is covered in detail in <>, including listing, adding, removing and renaming them. It is used in nearly every subsequent chapter in the book too, but always in the standard `git remote add ` format. @@ -334,7 +378,7 @@ It is used in nearly every subsequent chapter in the book too, but always in the The `git archive` command is used to create an archive file of a specific snapshot of the project. -We use `git archive` to create a tarball of a project for sharing in <>. +We use `git archive` to create a tarball of a project for sharing in <>. ==== git submodule @@ -342,7 +386,7 @@ The `git submodule` command is used to manage external repositories within a nor This could be for libraries or other types of shared resources. The `submodule` command has several sub-commands (`add`, `update`, `sync`, etc) for managing these resources. -This command is only mentioned and entirely covered in <>. +This command is only mentioned and entirely covered in <>. === Inspection and Comparison @@ -351,25 +395,25 @@ This command is only mentioned and entirely covered in <>. +We first use it to show annotated tag information in <>. -Later we use it quite a bit in <> to show the commits that our various revision selections resolve to. +Later we use it quite a bit in <> to show the commits that our various revision selections resolve to. -One of the more interesting things we do with `git show` is in <> to extract specific file contents of various stages during a merge conflict. +One of the more interesting things we do with `git show` is in <> to extract specific file contents of various stages during a merge conflict. ==== git shortlog The `git shortlog` command is used to summarize the output of `git log`. It will take many of the same options that the `git log` command will but instead of listing out all of the commits it will present a summary of the commits grouped by author. -We showed how to use it to create a nice changelog in <>. +We showed how to use it to create a nice changelog in <>. ==== git describe The `git describe` command is used to take anything that resolves to a commit and produces a string that is somewhat human-readable and will not change. It's a way to get a description of a commit that is as unambiguous as a commit SHA-1 but more understandable. -We use `git describe` in <> and <> to get a string to name our release file after. +We use `git describe` in <> and <> to get a string to name our release file after. === Debugging @@ -381,20 +425,20 @@ This ranges from figuring out where something was introduced to figuring out who The `git bisect` tool is an incredibly helpful debugging tool used to find which specific commit was the first one to introduce a bug or problem by doing an automatic binary search. -It is fully covered in <> and is only mentioned in that section. +It is fully covered in <> and is only mentioned in that section. ==== git blame The `git blame` command annotates the lines of any file with which commit was the last one to introduce a change to each line of the file and what person authored that commit. This is helpful in order to find the person to ask for more information about a specific section of your code. -It is covered in <> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. ==== git grep The `git grep` command can help you find any string or regular expression in any of the files in your source code, even older versions of your project. -It is covered in <> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. === Patching @@ -406,27 +450,27 @@ These commands help you manage your branches in this manner. The `git cherry-pick` command is used to take the change introduced in a single Git commit and try to re-introduce it as a new commit on the branch you're currently on. This can be useful to only take one or two commits from a branch individually rather than merging in the branch which takes all the changes. -Cherry picking is described and demonstrated in <>. +Cherry picking is described and demonstrated in <>. ==== git rebase The `git rebase` command is basically an automated `cherry-pick`. It determines a series of commits and then cherry-picks them one by one in the same order somewhere else. -Rebasing is covered in detail in <>, including covering the collaborative issues involved with rebasing branches that are already public. +Rebasing is covered in detail in <>, including covering the collaborative issues involved with rebasing branches that are already public. -We use it in practice during an example of splitting your history into two separate repositories in <>, using the `--onto` flag as well. +We use it in practice during an example of splitting your history into two separate repositories in <>, using the `--onto` flag as well. -We go through running into a merge conflict during rebasing in <>. +We go through running into a merge conflict during rebasing in <>. -We also use it in an interactive scripting mode with the `-i` option in <>. +We also use it in an interactive scripting mode with the `-i` option in <>. ==== git revert The `git revert` command is essentially a reverse `git cherry-pick`. It creates a new commit that applies the exact opposite of the change introduced in the commit you're targeting, essentially undoing or reverting it. -We use this in <> to undo a merge commit. +We use this in <> to undo a merge commit. === Email @@ -438,43 +482,43 @@ Git has a number of tools built into it that help make this process easier, from The `git apply` command applies a patch created with the `git diff` or even GNU diff command. It is similar to what the `patch` command might do with a few small differences. -We demonstrate using it and the circumstances in which you might do so in <>. +We demonstrate using it and the circumstances in which you might do so in <>. ==== git am The `git am` command is used to apply patches from an email inbox, specifically one that is mbox formatted. This is useful for receiving patches over email and applying them to your project easily. -We covered usage and workflow around `git am` in <> including using the `--resolved`, `-i` and `-3` options. +We covered usage and workflow around `git am` in <> including using the `--resolved`, `-i` and `-3` options. -There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <>. +There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <>. -We also use it to apply patch formatted GitHub Pull Request changes in <>. +We also use it to apply patch formatted GitHub Pull Request changes in <>. ==== git format-patch The `git format-patch` command is used to generate a series of patches in mbox format that you can use to send to a mailing list properly formatted. -We go through an example of contributing to a project using the `git format-patch` tool in <>. +We go through an example of contributing to a project using the `git format-patch` tool in <>. ==== git imap-send The `git imap-send` command uploads a mailbox generated with `git format-patch` into an IMAP drafts folder. -We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <>. +We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <>. ==== git send-email The `git send-email` command is used to send patches that are generated with `git format-patch` over email. -We go through an example of contributing to a project by sending patches with the `git send-email` tool in <>. +We go through an example of contributing to a project by sending patches with the `git send-email` tool in <>. ==== git request-pull The `git request-pull` command is simply used to generate an example message body to email to someone. If you have a branch on a public server and want to let someone know how to integrate those changes without sending the patches over email, you can run this command and send the output to the person you want to pull the changes in. -We demonstrate how to use `git request-pull` to generate a pull message in <>. +We demonstrate how to use `git request-pull` to generate a pull message in <>. === External Systems @@ -485,13 +529,13 @@ Git comes with a few commands to integrate with other version control systems. The `git svn` command is used to communicate with the Subversion version control system as a client. This means you can use Git to checkout from and commit to a Subversion server. -This command is covered in depth in <>. +This command is covered in depth in <>. ==== git fast-import For other version control systems or importing from nearly any format, you can use `git fast-import` to quickly map the other format to something Git can easily record. -This command is covered in depth in <>. +This command is covered in depth in <>. === Administration @@ -499,43 +543,43 @@ If you're administering a Git repository or need to fix something in a big way, ==== git gc -The `git gc` command runs ``garbage collection'' on your repository, removing unnecessary files in your database and packing up the remaining files into a more efficient format. +The `git gc` command runs "`garbage collection`" on your repository, removing unnecessary files in your database and packing up the remaining files into a more efficient format. This command normally runs in the background for you, though you can manually run it if you wish. -We go over some examples of this in <>. +We go over some examples of this in <>. ==== git fsck The `git fsck` command is used to check the internal database for problems or inconsistencies. -We only quickly use this once in <> to search for dangling objects. +We only quickly use this once in <> to search for dangling objects. ==== git reflog The `git reflog` command goes through a log of where all the heads of your branches have been as you work to find commits you may have lost through rewriting histories. -We cover this command mainly in <>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. +We cover this command mainly in <>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. -We also go through a practical example of recovering such a lost branch in <>. +We also go through a practical example of recovering such a lost branch in <>. ==== git filter-branch The `git filter-branch` command is used to rewrite loads of commits according to certain patterns, like removing a file everywhere or filtering the entire repository down to a single subdirectory for extracting a project. -In <> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. +In <> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. -In <> and <> we use it to fix up imported external repositories. +In <> we use it to fix up imported external repositories. === Plumbing Commands There were also quite a number of lower level plumbing commands that we encountered in the book. -The first one we encounter is `ls-remote` in <> which we use to look at the raw references on the server. +The first one we encounter is `ls-remote` in <> which we use to look at the raw references on the server. -We use `ls-files` in <>, <> and <> to take a more raw look at what your staging area looks like. +We use `ls-files` in <>, <> and <> to take a more raw look at what your staging area looks like. -We also mention `rev-parse` in <> to take just about any string and turn it into an object SHA-1. +We also mention `rev-parse` in <> to take just about any string and turn it into an object SHA-1. However, most of the low level plumbing commands we cover are in <>, which is more or less what the chapter is focused on. We tried to avoid use of them throughout most of the rest of the book. diff --git a/book/A-git-in-other-environments/sections/bash.asc b/book/A-git-in-other-environments/sections/bash.asc index e680b716..ad383947 100644 --- a/book/A-git-in-other-environments/sections/bash.asc +++ b/book/A-git-in-other-environments/sections/bash.asc @@ -8,9 +8,9 @@ First, you need to get a copy of the `contrib/completion/git-completion.bash` fi Copy it somewhere handy, like your home directory, and add this to your `.bashrc`: [source,console] ------ +---- . ~/git-completion.bash ------ +---- Once that's done, change your directory to a Git repository, and type: @@ -27,16 +27,16 @@ This can be as simple or complex as you want, but there are generally a few key 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,console] ------ +---- . ~/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 this when you're anywhere inside a Git-controlled project: -.Customized `bash` prompt. -image::images/git-bash.png[Customized `bash` prompt.] +.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. diff --git a/book/A-git-in-other-environments/sections/eclipse.asc b/book/A-git-in-other-environments/sections/eclipse.asc deleted file mode 100644 index 76cfd9c5..00000000 --- a/book/A-git-in-other-environments/sections/eclipse.asc +++ /dev/null @@ -1,10 +0,0 @@ -=== Git in Eclipse - -(((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 Perspective > Other…, and select "Git"). - -.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. diff --git a/book/A-git-in-other-environments/sections/guis.asc b/book/A-git-in-other-environments/sections/guis.asc index 45caba38..c4d06d1e 100644 --- a/book/A-git-in-other-environments/sections/guis.asc +++ b/book/A-git-in-other-environments/sections/guis.asc @@ -7,7 +7,7 @@ But plain text isn't the best choice for all tasks; sometimes a visual represent It's important to note that different interfaces are tailored for different workflows. Some clients 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. +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` @@ -31,8 +31,8 @@ Gitk accepts many command-line options, most of which are passed through to the 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 this: -.The `gitk` history viewer. -image::images/gitk.png[The `gitk` history viewer.] +.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. @@ -43,14 +43,14 @@ In between is a collection of controls used for searching history. It, too, is easiest to invoke from the command line: [source,console] ------ +---- $ git gui ------ +---- And it looks something like this: -.The `git-gui` commit tool. -image::images/git-gui.png[The `git-gui` commit tool.] +.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. @@ -59,35 +59,34 @@ At top right is the diff view, which shows the changes for the currently-selecte 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. +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 for macOS and Windows -==== GitHub for Mac and Windows - -(((GitHub for Mac)))(((GitHub for Windows))) -GitHub has created two workflow-oriented Git clients: one for Windows, and one for Mac. +(((GitHub for macOS)))(((GitHub for Windows))) +GitHub has created two workflow-oriented Git clients: one for Windows, and one for macOS. These clients are a good example of workflow-oriented tools – rather than expose _all_ of Git's functionality, they instead focus on a curated set of commonly-used features that work well together. They look like this: -.GitHub for Mac. -image::images/github_mac.png[GitHub for Mac.] +.GitHub for macOS +image::images/github_mac.png[GitHub for macOS] -.GitHub for Windows. -image::images/github_win.png[GitHub for Windows.] +.GitHub for Windows +image::images/github_win.png[GitHub for Windows] They are designed to look and work very much alike, so we'll treat them like a single product in this chapter. -We won't be doing a detailed rundown of these tools (they have their own documentation), but a quick tour of the ``changes'' view (which is where you'll spend most of your time) is in order. +We won't be doing a detailed rundown of these tools (they have their own documentation), but a quick tour of the "`changes`" view (which is where you'll spend most of your time) is in order. -* On the left is the list of repositories the client is tracking; you can add a repository (either by cloning or attaching locally) by clicking the ``+'' icon at the top of this area. +* On the left is the list of repositories the client is tracking; you can add a repository (either by cloning or attaching locally) by clicking the "`+`" icon at the top of this area. * In the center is a commit-input area, which lets you input a commit message, and select which files should be included. - (On Windows, the commit history is displayed directly below this; on Mac, it's on a separate tab.) + On Windows, the commit history is displayed directly below this; on macOS, it's on a separate tab. * On the right is a diff view, which shows what's changed in your working directory, or which changes were included in the selected commit. -* The last thing to notice is the ``Sync'' button at the top-right, which is the primary way you interact over the network. +* The last thing to notice is the "`Sync`" button at the top-right, which is the primary way you interact over the network. [NOTE] ==== @@ -97,12 +96,12 @@ While they're designed to highlight GitHub's service and recommended workflow, t ===== Installation -GitHub for Windows can be downloaded from https://windows.github.com[], and GitHub for Mac from https://mac.github.com[]. +GitHub for Windows can be downloaded from https://windows.github.com[], and GitHub for macOS from https://mac.github.com[]. When the applications are first run, they walk you through all the first-time Git setup, such as configuring your name and email address, and both set up sane defaults for many common configuration options, such as credential caches and CRLF behavior. -Both are ``evergreen'' – updates are downloaded and installed in the background while the applications are open. +Both are "`evergreen`" – updates are downloaded and installed in the background while the applications are open. This helpfully includes a bundled version of Git, which means you probably won't have to worry about manually updating it again. -On Windows, the client includes a shortcut to launch Powershell with Posh-git, which we'll talk more about later in this chapter. +On Windows, the client includes a shortcut to launch PowerShell with Posh-git, which we'll talk more about later in this chapter. The next step is to give the tool some repositories to work with. The client shows you a list of the repositories you have access to on GitHub, and can clone them in one step. @@ -111,25 +110,25 @@ If you already have a local repository, just drag its directory from the Finder ===== Recommended Workflow Once it's installed and configured, you can use the GitHub client for many common Git tasks. -The intended workflow for this tool is sometimes called the ``GitHub Flow.'' -We cover this in more detail in <>, but the general gist is that (a) you'll be committing to a branch, and (b) you'll be syncing up with a remote repository fairly regularly. +The intended workflow for this tool is sometimes called the "`GitHub Flow.`" +We cover this in more detail in <>, but the general gist is that (a) you'll be committing to a branch, and (b) you'll be syncing up with a remote repository fairly regularly. Branch management is one of the areas where the two tools diverge. -On Mac, there's a button at the top of the window for creating a new branch: +On macOS, there's a button at the top of the window for creating a new branch: -.``Create Branch'' button on Mac. -image::images/branch_widget_mac.png[``Create Branch'' button on Mac.] +."`Create Branch`" button on macOS +image::images/branch_widget_mac.png[“Create Branch” button on macOS] On Windows, this is done by typing the new branch's name in the branch-switching widget: -.Creating a branch on Windows. -image::images/branch_widget_win.png[Creating a branch on Windows.] +.Creating a branch on Windows +image::images/branch_widget_win.png[Creating a branch on Windows] Once your branch is created, making new commits is fairly straightforward. Make some changes in your working directory, and when you switch to the GitHub client window, it will show you which files changed. -Enter a commit message, select the files you'd like to include, and click the ``Commit'' button (ctrl-enter or ⌘-enter). +Enter a commit message, select the files you'd like to include, and click the "`Commit`" button (ctrl-enter or ⌘-enter). -The main way you interact with other repositories over the network is through the ``Sync'' feature. +The main way you interact with other repositories over the network is through the "`Sync`" feature. Git internally has separate operations for pushing, fetching, merging, and rebasing, but the GitHub clients collapse all of these into one multi-step feature. Here's what happens when you click the Sync button: @@ -149,5 +148,5 @@ However, if your workflow is different, or you want more control over how and wh ==== 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[]. +The official Git website has a curated list of the most popular clients at https://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[]. diff --git a/book/A-git-in-other-environments/sections/jetbrainsides.asc b/book/A-git-in-other-environments/sections/jetbrainsides.asc new file mode 100644 index 00000000..d6040ca7 --- /dev/null +++ b/book/A-git-in-other-environments/sections/jetbrainsides.asc @@ -0,0 +1,10 @@ +=== Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine + +JetBrains IDEs (such as IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, RubyMine, and others) ship with a Git Integration plugin. +It provides a dedicated view in the IDE to work with Git and GitHub Pull Requests. + +.Version Control ToolWindow in JetBrains IDEs +image::images/jb.png[Version Control ToolWindow in JetBrains IDEs] + +The integration relies on the command-line git client, and requires one to be installed. +The official documentation is available at https://www.jetbrains.com/help/idea/using-git-integration.html[]. diff --git a/book/A-git-in-other-environments/sections/powershell.asc b/book/A-git-in-other-environments/sections/powershell.asc index c93a1fd2..66f7c3cc 100644 --- a/book/A-git-in-other-environments/sections/powershell.asc +++ b/book/A-git-in-other-environments/sections/powershell.asc @@ -1,23 +1,86 @@ -[[r_git_powershell]] -=== Git in Powershell +[[_git_powershell]] +=== Git in PowerShell -(((powershell)))(((tab completion, powershell)))(((shell prompts, powershell))) +(((PowerShell)))(((tab completion, PowerShell)))(((shell prompts, PowerShell))) (((posh-git))) -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 (https://github.com/dahlbyk/posh-git[]) provides powerful tab-completion facilities, as well as an enhanced prompt to help you stay on top of your repository status. +The legacy 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. +This also works if you're running PowerShell Core on Linux or macOS. +A package called posh-git (https://github.com/dahlbyk/posh-git[]) provides powerful tab-completion facilities, as well as an enhanced prompt to help you stay on top of your repository status. It looks like this: -.Powershell with Posh-git. -image::images/posh-git.png[Powershell with Posh-git.] +.PowerShell with Posh-git +image::images/posh-git.png[PowerShell with Posh-git] -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: +==== Installation + +===== Prerequisites (Windows only) + +Before you're able to run PowerShell scripts on your machine, you need to set your local `ExecutionPolicy` to `RemoteSigned` (basically, anything except `Undefined` and `Restricted`). +If you choose `AllSigned` instead of `RemoteSigned`, also local scripts (your own) need to be digitally signed in order to be executed. +With `RemoteSigned`, only scripts having the `ZoneIdentifier` set to `Internet` (were downloaded from the web) need to be signed, others not. +If you're an administrator and want to set it for all users on that machine, use `-Scope LocalMachine`. +If you're a normal user, without administrative rights, you can use `-Scope CurrentUser` to set it only for you. + +More about PowerShell Scopes: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes[]. + +More about PowerShell ExecutionPolicy: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy[]. + +To set the value of `ExecutionPolicy` to `RemoteSigned` for all users use the next command: + +[source,powershell] +---- +> Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned -Force +---- + +===== PowerShell Gallery + +If you have at least PowerShell 5 or PowerShell 4 with PackageManagement installed, you can use the package manager to install posh-git for you. + +More information about PowerShell Gallery: https://docs.microsoft.com/en-us/powershell/scripting/gallery/overview[]. [source,powershell] ------ -> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Confirm -> cd ~\Documents\WindowsPowerShell\posh-git -> .\install.ps1 ------ +---- +> Install-Module posh-git -Scope CurrentUser -Force +> Install-Module posh-git -Scope CurrentUser -AllowPrerelease -Force # Newer beta version with PowerShell Core support +---- + +If you want to install posh-git for all users, use `-Scope AllUsers` instead and execute the command from an elevated PowerShell console. +If the second command fails with an error like `Module 'PowerShellGet' was not installed by using Install-Module`, you'll need to run another command first: + +[source,powershell] +---- +> Install-Module PowerShellGet -Force -SkipPublisherCheck +---- + +Then you can go back and try again. +This happens, because the modules that ship with Windows PowerShell are signed with a different publishment certificate. + +===== Update PowerShell Prompt + +To include git information in your prompt, the posh-git module needs to be imported. +To have posh-git imported every time PowerShell starts, execute the `Add-PoshGitToProfile` command which will add the import statement into your `$profile` script. +This script is executed everytime you open a new PowerShell console. +Keep in mind, that there are multiple `$profile` scripts. +E. g. one for the console and a separate one for the ISE. + +[source,powershell] +---- +> Import-Module posh-git +> Add-PoshGitToProfile -AllHosts +---- + +===== From Source + +Just download a posh-git release from https://github.com/dahlbyk/posh-git/releases[], and uncompress it. +Then import the module using the full path to the `posh-git.psd1` file: + +[source,powershell] +---- +> Import-Module \src\posh-git.psd1 +> Add-PoshGitToProfile -AllHosts +---- + +This will add the proper line to your `profile.ps1` file, and posh-git will be active the next time you open PowerShell. -This will add the proper line to your `profile.ps1` file, and posh-git will be active the next time you open your prompt. +For a description of the Git status summary information displayed in the prompt see: https://github.com/dahlbyk/posh-git/blob/master/README.md#git-status-summary-information[] +For more details on how to customize your posh-git prompt see: https://github.com/dahlbyk/posh-git/blob/master/README.md#customization-variables[]. diff --git a/book/A-git-in-other-environments/sections/sublimetext.asc b/book/A-git-in-other-environments/sections/sublimetext.asc new file mode 100644 index 00000000..eb774347 --- /dev/null +++ b/book/A-git-in-other-environments/sections/sublimetext.asc @@ -0,0 +1,14 @@ +=== Git in Sublime Text + +From version 3.2 onwards, Sublime Text has git integration in the editor. + +The features are: + +* The sidebar will show the git status of files and folders with a badge/icon. +* Files and folders that are in your .gitignore file will be faded out in the sidebar. +* In the status bar, you can see the current git branch and how many modifications you have made. +* All changes to a file are now visible via markers in the gutter. +* You can use part of the Sublime Merge git client functionality from within Sublime Text. + This requires that Sublime Merge is installed. See: https://www.sublimemerge.com/[]. + +The official documentation for Sublime Text can be found here: https://www.sublimetext.com/docs/3/git_integration.html[]. diff --git a/book/A-git-in-other-environments/sections/visualstudio.asc b/book/A-git-in-other-environments/sections/visualstudio.asc index be9fa8a0..c369e513 100644 --- a/book/A-git-in-other-environments/sections/visualstudio.asc +++ b/book/A-git-in-other-environments/sections/visualstudio.asc @@ -8,18 +8,18 @@ Visual Studio 2013's Git support has been separated from this older feature, and 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 this: -.Connecting to a Git repository from Team Explorer. -image::images/vs-1.png[Connecting to a Git repository from Team Explorer.] +.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 <>. +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. -[[rvs_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.] +[[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[]. +For more on using Git within Visual Studio go to: https://docs.microsoft.com/en-us/azure/devops/repos/git/command-prompt?view=azure-devops[]. diff --git a/book/A-git-in-other-environments/sections/visualstudiocode.asc b/book/A-git-in-other-environments/sections/visualstudiocode.asc new file mode 100644 index 00000000..1a53cb17 --- /dev/null +++ b/book/A-git-in-other-environments/sections/visualstudiocode.asc @@ -0,0 +1,21 @@ +=== Git in Visual Studio Code + +Visual Studio Code has git support built in. +You will need to have git version 2.0.0 (or newer) installed. + +The main features are: + +* See the diff of the file you are editing in the gutter. +* The Git Status Bar (lower left) shows the current branch, dirty indicators, incoming and outgoing commits. +* You can do the most common git operations from within the editor: +** Initialize a repository. +** Clone a repository. +** Create branches and tags. +** Stage and commit changes. +** Push/pull/sync with a remote branch. +** Resolve merge conflicts. +** View diffs. +* With an extension, you can also handle GitHub Pull Requests: + https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github[]. + +The official documentation can be found here: https://code.visualstudio.com/Docs/editor/versioncontrol[]. diff --git a/book/A-git-in-other-environments/sections/zsh.asc b/book/A-git-in-other-environments/sections/zsh.asc index ac7c1b54..a8b0bf31 100644 --- a/book/A-git-in-other-environments/sections/zsh.asc +++ b/book/A-git-in-other-environments/sections/zsh.asc @@ -34,24 +34,24 @@ zstyle ':vcs_info:git:*' formats '%b' ---- 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. -(The left side is supported as well, of course; just uncomment the assignment to PROMPT.) +The left side is supported as well, of course; just uncomment the assignment to PROMPT. It looks a bit like this: -.Customized `zsh` prompt. -image::images/zsh-prompt.png[Customized `zsh` prompt.] +.Customized `zsh` prompt +image::images/zsh-prompt.png[Customized `zsh` prompt] For more information on vcs_info, check out its documentation in the `zshcontrib(1)` manual page, or online at `http://zsh.sourceforge.net/Doc/Release/User-Contributions.html#Version-Control-Information`. -Instead of vcs_info, you might prefer the prompt customization script that ships with Git, called `git-prompt.sh`; see https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh[] for details. +Instead of `vcs_info`, you might prefer the prompt customization script that ships with Git, called `git-prompt.sh`; see https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh[] for details. `git-prompt.sh` is compatible with both Bash and Zsh. 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. +<> is just one example of what can be done with this system. -[[roh_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.] +[[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] diff --git a/book/B-embedding-git/sections/dulwich.asc b/book/B-embedding-git/sections/dulwich.asc new file mode 100644 index 00000000..90ff4a05 --- /dev/null +++ b/book/B-embedding-git/sections/dulwich.asc @@ -0,0 +1,44 @@ +=== Dulwich + +(((Dulwich)))(((Python))) +There is also a pure-Python Git implementation - Dulwich. +The project is hosted under https://www.dulwich.io/ +It aims to provide an interface to git repositories (both local and remote) that doesn't call out to git directly but instead uses pure Python. +It has an optional C extensions though, that significantly improve the performance. + +Dulwich follows git design and separate two basic levels of API: plumbing and porcelain. + +Here is an example of using the lower level API to access the commit message of the last commit: + +[source, python] +---- +from dulwich.repo import Repo +r = Repo('.') +r.head() +# '57fbe010446356833a6ad1600059d80b1e731e15' + +c = r[r.head()] +c +# + +c.message +# 'Add note about encoding.\n' +---- + +To print a commit log using high-level porcelain API, one can use: + +[source, python] +---- +from dulwich import porcelain +porcelain.log('.', max_entries=1) + +#commit: 57fbe010446356833a6ad1600059d80b1e731e15 +#Author: Jelmer Vernooij +#Date: Sat Apr 29 2017 23:57:34 +0000 +---- + + +==== Further Reading + + * The official API documentation is available at https://www.dulwich.io/docs/api/[]. + * Official tutorial at https://www.dulwich.io/docs/tutorial[] has many examples of how to do specific tasks with Dulwich. diff --git a/book/B-embedding-git/sections/go-git.asc b/book/B-embedding-git/sections/go-git.asc new file mode 100644 index 00000000..3335802b --- /dev/null +++ b/book/B-embedding-git/sections/go-git.asc @@ -0,0 +1,83 @@ +=== go-git + +(((go-git)))(((Go))) +In case you want to integrate Git into a service written in Golang, there also is a pure Go library implementation. +This implementation does not have any native dependencies and thus is not prone to manual memory management errors. +It is also transparent for the standard Golang performance analysis tooling like CPU, Memory profilers, race detector, etc. + +go-git is focused on extensibility, compatibility and supports most of the plumbing APIs, which is documented at https://github.com/go-git/go-git/blob/master/COMPATIBILITY.md[]. + +Here is a basic example of using Go APIs: + +[source, go] +---- +import "github.com/go-git/go-git/v5" + +r, err := git.PlainClone("/tmp/foo", false, &git.CloneOptions{ + URL: "https://github.com/go-git/go-git", + Progress: os.Stdout, +}) +---- + +As soon as you have a `Repository` instance, you can access information and perform mutations on it: + +[source, go] +---- +// retrieves the branch pointed by HEAD +ref, err := r.Head() + +// get the commit object, pointed by ref +commit, err := r.CommitObject(ref.Hash()) + +// retrieves the commit history +history, err := commit.History() + +// iterates over the commits and print each +for _, c := range history { + fmt.Println(c) +} +---- + +==== Advanced Functionality + +go-git has few notable advanced features, one of which is a pluggable storage system, which is similar to Libgit2 backends. +The default implementation is in-memory storage, which is very fast. + +[source, go] +---- +r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{ + URL: "https://github.com/go-git/go-git", +}) +---- + +Pluggable storage provides many interesting options. +For instance, https://github.com/go-git/go-git/tree/master/_examples/storage[] allows you to store references, objects, and configuration in an Aerospike database. + +Another feature is a flexible filesystem abstraction. +Using https://pkg.go.dev/github.com/go-git/go-billy/v5?tab=doc#Filesystem[] it is easy to store all the files in different way i.e by packing all of them to a single archive on disk or by keeping them all in-memory. + +Another advanced use-case includes a fine-tunable HTTP client, such as the one found at https://github.com/go-git/go-git/blob/master/_examples/custom_http/main.go[]. + +[source, go] +---- +customClient := &http.Client{ + Transport: &http.Transport{ // accept any certificate (might be useful for testing) + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Timeout: 15 * time.Second, // 15 second timeout + CheckRedirect: func(req *http.Request, via []*http.Request) error { + return http.ErrUseLastResponse // don't follow redirect + }, +} + +// Override http(s) default protocol to use our custom client +client.InstallProtocol("https", githttp.NewClient(customClient)) + +// Clone repository using the new client if the protocol is https:// +r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{URL: url}) +---- + +==== Further Reading + +A full treatment of go-git's capabilities is outside the scope of this book. +If you want more information on go-git, there's API documentation at https://pkg.go.dev/github.com/go-git/go-git/v5[], and a set of usage examples at https://github.com/go-git/go-git/tree/master/_examples[]. diff --git a/book/B-embedding-git/sections/jgit.asc b/book/B-embedding-git/sections/jgit.asc index 72d5e712..9e416173 100644 --- a/book/B-embedding-git/sections/jgit.asc +++ b/book/B-embedding-git/sections/jgit.asc @@ -1,9 +1,9 @@ === JGit -(((jgit)))(((java))) +(((jgit)))(((Java))) If you want to use Git from within a Java program, there is a fully featured Git library called JGit. JGit is a relatively full-featured implementation of Git written natively in Java, and is widely used in the Java community. -The JGit project is under the Eclipse umbrella, and its home can be found at http://www.eclipse.org/jgit[]. +The JGit project is under the Eclipse umbrella, and its home can be found at https://www.eclipse.org/jgit/[]. ==== Getting Set Up @@ -19,10 +19,10 @@ Probably the easiest is to use Maven – the integration is accomplished by addi ---- -The `version` will most likely have advanced by the time you read this; check http://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgit[] for updated repository information. +The `version` will most likely have advanced by the time you read this; check https://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgit[] for updated repository information. Once this step is done, Maven will automatically acquire and use the JGit libraries that you'll need. -If you would rather manage the binary dependencies yourself, pre-built JGit binaries are available from http://www.eclipse.org/jgit/download[]. +If you would rather manage the binary dependencies yourself, pre-built JGit binaries are available from https://www.eclipse.org/jgit/download[]. You can build them into your project by running a command like this: [source,console] @@ -91,13 +91,13 @@ String name = cfg.getString("user", null, "name"); There's quite a bit going on here, so let's go through it one section at a time. The first line gets a pointer to the `master` reference. -JGit automatically grabs the _actual_ master ref, which lives at `refs/heads/master`, and returns an object that lets you fetch information about the reference. +JGit automatically grabs the _actual_ `master` ref, which lives at `refs/heads/master`, and returns an object that lets you fetch information about the reference. You can get the name (`.getName()`), and either the target object of a direct reference (`.getObjectId()`) or the reference pointed to by a symbolic ref (`.getTarget()`). -Ref objects are also used to represent tag refs and objects, so you can ask if the tag is ``peeled,'' meaning that it points to the final target of a (potentially long) string of tag objects. +Ref objects are also used to represent tag refs and objects, so you can ask if the tag is "`peeled,`" meaning that it points to the final target of a (potentially long) string of tag objects. The second line gets the target of the `master` reference, which is returned as an ObjectId instance. ObjectId represents the SHA-1 hash of an object, which might or might not exist in Git's object database. -The third line is similar, but shows how JGit handles the rev-parse syntax (for more on this, see <>); you can pass any object specifier that Git understands, and JGit will return either a valid ObjectId for that object, or `null`. +The third line is similar, but shows how JGit handles the rev-parse syntax (for more on this, see <>); you can pass any object specifier that Git understands, and JGit will return either a valid ObjectId for that object, or `null`. The next two lines show how to load the raw contents of an object. In this example, we call `ObjectLoader.copyTo()` to stream the contents of the object directly to stdout, but ObjectLoader also has methods to read the type and size of an object, as well as return it as a byte array. @@ -128,7 +128,7 @@ Git git = new Git(repo); ---- The Git class has a nice set of high-level _builder_-style methods that can be used to construct some pretty complex behavior. -Let's take a look at an example – doing something like `git ls-remote`: +Let's take a look at an example -- doing something like `git ls-remote`: [source,java] ---- diff --git a/book/B-embedding-git/sections/libgit2.asc b/book/B-embedding-git/sections/libgit2.asc index 9f6bfc3b..9edca885 100644 --- a/book/B-embedding-git/sections/libgit2.asc +++ b/book/B-embedding-git/sections/libgit2.asc @@ -3,13 +3,13 @@ (((libgit2)))((("C"))) Another 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. -You can find it at http://libgit2.github.com[]. +You can find it at https://libgit2.org[]. First, let's take a look at what the C API looks like. Here's a whirlwind tour: [source,c] ------ +---- // Open a repository git_repository *repo; int error = git_repository_open(&repo, "/path/to/repository"); @@ -28,16 +28,16 @@ const git_oid *tree_id = git_commit_tree_id(commit); // Cleanup git_commit_free(commit); git_repository_free(repo); ------ +---- The first couple of lines open a Git repository. The `git_repository` type represents a handle to a repository with a cache in memory. This is the simplest method, for when you know the exact path to a repository's working directory or `.git` folder. There's also the `git_repository_open_ext` which includes options for searching, `git_clone` and friends for making a local clone of a remote repository, and `git_repository_init` for creating an entirely new repository. -The second chunk of code uses rev-parse syntax (see <> for more on this) to get the commit that HEAD eventually points to. +The second chunk of code uses rev-parse syntax (see <> for more on this) to get the commit that HEAD eventually points to. The type returned is a `git_object` pointer, which represents something that exists in the Git object database for a repository. -`git_object` is actually a ``parent'' type for several different kinds of objects; the memory layout for each of the ``child'' types is the same as for `git_object`, so you can safely cast to the right one. +`git_object` is actually a "`parent`" type for several different kinds of objects; the memory layout for each of the "`child`" types is the same as for `git_object`, so you can safely cast to the right one. In this case, `git_object_type(commit)` would return `GIT_OBJ_COMMIT`, so it's safe to cast to a `git_commit` pointer. The next chunk shows how to access the commit's properties. @@ -66,7 +66,7 @@ tree = commit.tree ---- As you can see, the code is much less cluttered. -Firstly, Rugged uses exceptions; it can raise things like `ConfigError` or `ObjectError` to signal error conditions. +Firstly, Rugged uses exceptions; it can raise things like `ConfigError` or `ObjectError` to signal error conditions. Secondly, there's no explicit freeing of resources, since Ruby is garbage-collected. Let's take a look at a slightly more complicated example: crafting a commit from scratch @@ -106,13 +106,12 @@ commit = repo.lookup(commit_id) # <8> <8> The return value is the SHA-1 hash of a new commit object, which you can then use to get a `Commit` object. The Ruby code is nice and clean, but since Libgit2 is doing the heavy lifting, this code will run pretty fast, too. -If you're not a rubyist, we touch on some other bindings in <>. - +If you're not a rubyist, we touch on some other bindings in <<_libgit2_bindings>>. ==== Advanced Functionality Libgit2 has a couple of capabilities that are outside the scope of core Git. -One example is pluggability: Libgit2 allows you to provide custom ``backends'' for several types of operation, so you can store things in a different way than stock Git does. +One example is pluggability: Libgit2 allows you to provide custom "`backends`" for several types of operation, so you can store things in a different way than stock Git does. Libgit2 allows custom backends for configuration, ref storage, and the object database, among other things. Let's take a look at how this works. @@ -131,12 +130,12 @@ error = git_odb_add_backend(odb, my_backend, 1); // <3> git_repository *repo; error = git_repository_open(&repo, "some-path"); -error = git_repository_set_odb(odb); // <4> +error = git_repository_set_odb(repo, odb); // <4> ---- -_(Note that errors are captured, but not handled. We hope your code is better than ours.)_ +_Note that errors are captured, but not handled. We hope your code is better than ours._ -<1> Initialize an empty object database (ODB) ``frontend,'' which will act as a container for the ``backends'' which are the ones doing the real work. +<1> Initialize an empty object database (ODB) "`frontend,`" which will act as a container for the "`backends`" which are the ones doing the real work. <2> Initialize a custom ODB backend. <3> Add the backend to the frontend. <4> Open a repository, and set it to use our ODB to look up objects. @@ -179,7 +178,7 @@ The rest of it is arbitrary; this structure can be as large or small as you need The initialization function allocates some memory for the structure, sets up the custom context, and then fills in the members of the `parent` structure that it supports. Take a look at the `include/git2/sys/odb_backend.h` file in the Libgit2 source for a complete set of call signatures; your particular use case will help determine which of these you'll want to support. -[[r_libgit2_bindings]] +[[_libgit2_bindings]] ==== Other Bindings Libgit2 has bindings for many languages. @@ -187,7 +186,6 @@ Here we show a small example using a few of the more complete bindings packages The official collection of bindings can be found by browsing the repositories at https://github.com/libgit2[]. The code we'll write will return the commit message from the commit eventually pointed to by HEAD (sort of like `git log -1`). - ===== LibGit2Sharp (((.NET)))(((C#)))(((Mono))) @@ -196,9 +194,9 @@ The bindings are written in C#, and great care has been taken to wrap the raw Li Here's what our example program looks like: [source,csharp] ------ +---- new Repository(@"C:\path\to\repo").Head.Tip.Message; ------ +---- For desktop Windows applications, there's even a NuGet package that will help you get started quickly. @@ -210,19 +208,18 @@ Objective-Git (https://github.com/libgit2/objective-git[]) is the name of the Li The example program looks like this: [source,objc] ------ +---- GTRepository *repo = [[GTRepository alloc] initWithURL:[NSURL fileURLWithPath: @"/path/to/repo"] error:NULL]; NSString *msg = [[[repo headReferenceWithError:NULL] resolvedTarget] message]; ------ +---- Objective-git is fully interoperable with Swift, so don't fear if you've left Objective-C behind. - ===== pygit2 (((Python))) -The bindings for Libgit2 in Python are called Pygit2, and can be found at http://www.pygit2.org/[]. +The bindings for Libgit2 in Python are called Pygit2, and can be found at https://www.pygit2.org[]. Our example program: [source,python] @@ -233,7 +230,6 @@ pygit2.Repository("/path/to/repo") # open repository .message # read the message ---- - ==== Further Reading Of course, a full treatment of Libgit2's capabilities is outside the scope of this book.