From aedb755f3e0c6c61e262e9598b8976f0ac8a0473 Mon Sep 17 00:00:00 2001 From: Scott Chacon Date: Thu, 12 Jun 2014 11:05:21 -0700 Subject: [PATCH 01/11] some ch1, ch2 indexing --- book/01-introduction/1-introduction.asc | 2 +- book/02-git-basics/1-git-basics.asc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/01-introduction/1-introduction.asc b/book/01-introduction/1-introduction.asc index 96602d13f..c72e24f31 100644 --- a/book/01-introduction/1-introduction.asc +++ b/book/01-introduction/1-introduction.asc @@ -248,7 +248,7 @@ Note that this is a project called Git for Windows (also called msysGit), which Another easy way to get Git installed is by installing GitHub for Windows. The installer includes a command line version of Git as well as the GUI. -It also works well with Powershell, and sets up solid credential caching and sane CRLF settings. +It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.((Powershell))((CRLF))((credential caching)) We'll learn more about those things a little later, but suffice it to say they're things you want. ==== Installing from Source diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index 850e36562..22c64e389 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -23,7 +23,7 @@ $ git init This creates a new subdirectory named `.git` that contains all of your necessary repository files – a Git repository skeleton. At this point, nothing in your project is tracked yet. -(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.) +(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)((git, initializing)) If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit. You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`: @@ -46,7 +46,7 @@ This is an important distinction – instead of getting just a working copy, Git Every version of every file for the history of the project is pulled down by default when you run `git clone`. In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there – see <<_git_on_the_server>> for more details). -You clone a repository with `git clone [url]`. +You clone a repository with `git clone [url]`.((git, clone)) For example, if you want to clone the Git linkable library called libgit2, you can do so like this: [source,shell] From f5aba99646f63f01ce60dd89d60bb3dc1647875e Mon Sep 17 00:00:00 2001 From: Scott Chacon Date: Thu, 12 Jun 2014 12:57:46 -0700 Subject: [PATCH 02/11] first pass at more ch2 indexes --- book/02-git-basics/1-git-basics.asc | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index 22c64e389..0b19ef4b9 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -106,7 +106,7 @@ For now, that branch is always ``master'', which is the default; you won’t wor <<_git_branching>> will go over branches and references in detail. Let’s say you add a new file to your project, a simple README file. -If the file didn’t exist before, and you run `git status`, you see your untracked file like so: +If the file didn’t exist before, and you run `git status`, you see your untracked file like so:((git, status)) [source,shell] ---- @@ -177,7 +177,7 @@ Changes not staged for commit: ---- The ``benchmarks.rb'' file appears under a section named ``Changed but not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged. -To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''. +To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.((git, add)) Let’s run `git add` now to stage the ``benchmarks.rb'' file, and then run `git status` again: [source,shell] @@ -196,7 +196,7 @@ Changes to be committed: Both files are staged and will go into your next commit. At this point, suppose you remember one little change that you want to make in `benchmarks.rb` before you commit it. You open it again and make that change, and you’re ready to commit. -However, let’s run `git status` one more time: +However, let’s run `git status` one more time:((git, status)) [source,shell] ---- @@ -256,7 +256,7 @@ New files that aren't tracked have a `??` next to them, new files that have been Often, you’ll have a class of files that you don’t want Git to automatically add or even show you as being untracked. These are generally automatically generated files such as log files or files produced by your build system. -In such cases, you can create a file listing patterns to match them named `.gitignore`. +In such cases, you can create a file listing patterns to match them named `.gitignore`.((ignoring files)) Here is an example `.gitignore` file: [source,shell] @@ -301,7 +301,7 @@ GitHub maintains a fairly comprehensive list of good `.gitignore` file examples ==== Viewing Your Staged and Unstaged Changes -If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command. +If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.((git, status))((git, diff)) We’ll cover `git diff` in more detail later, but you’ll probably use it most often to answer these two questions: What have you changed but not yet staged? And what have you staged that you are about to commit? Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were. @@ -443,7 +443,7 @@ $ git commit ---- Doing so launches your editor of choice. -(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>). +(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).((editor, changing default)) The editor displays the following text (this example is a Vim screen): @@ -486,7 +486,7 @@ Remember that the commit records the snapshot you set up in your staging area. Anything you didn’t stage is still sitting there modified; you can do another commit to add it to your history. Every time you perform a commit, you’re recording a snapshot of your project that you can revert to or compare to later. -==== Skipping the Staging Area +==== Skipping the Staging Area((staging area, skipping)) Although it can be amazingly useful for crafting commits exactly how you want them, the staging area is sometimes a bit more complex than you need in your workflow. If you want to skip the staging area, Git provides a simple shortcut. @@ -510,7 +510,7 @@ $ git commit -a -m 'added new benchmarks' Notice how you don’t have to run `git add` on the ``benchmarks.rb'' file in this case before you commit. -==== Removing Files +==== Removing Files((files, removing)) To remove a file from Git, you have to remove it from your tracked files (more accurately, remove it from your staging area) and then commit. The `git rm` command does that, and also removes the file from your working directory so you don’t see it as an untracked file the next time around. @@ -579,7 +579,7 @@ $ git rm \*~ This command removes all files that end with `~`. -==== Moving Files +==== Moving Files((files, moving)) Unlike many other VCS systems, Git doesn’t explicitly track file movement. If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file. @@ -633,7 +633,7 @@ To get the project, run git clone https://github.com/schacon/simplegit-progit ---- -When you run `git log` in this project, you should get output that looks something like this: +When you run `git log` in this project, you should get output that looks something like this:((git, log)) [source,shell] ---- @@ -767,7 +767,7 @@ a11bef06a3f659402fe7563abf99ad00de2209e6 first commit ---- The most interesting option is `format`, which allows you to specify your own log output format. -This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git: +This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git:((git, log formatting)) [source,shell] ---- @@ -893,7 +893,7 @@ In <> we’ll list these and a few other common options for your | `-S` | Only show commits adding or removing code matching the string |================================ -For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this: +For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:((git, log filtering)) [source,shell] ---- @@ -1050,7 +1050,7 @@ In this section, we’ll cover some of these remote-management skills. ==== Showing Your Remotes -To see which remote servers you have configured, you can run the `git remote` command. +To see which remote servers you have configured, you can run the `git remote` command.((git, remote)) It lists the shortnames of each remote handle you’ve specified. If you’ve cloned your repository, you should at least see origin – that is the default name Git gives to the server you cloned from: @@ -1102,7 +1102,7 @@ Notice that these remotes use a variety of protocols; we’ll cover why more abo ==== Adding Remote Repositories -I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly. +I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.((git, remote)) To add a new remote Git repository as a shortname you can reference easily, run `git remote add [shortname] [url]`: [source,shell] From f2bef3f85b7e70e3da4085be649ddcb8ee3a4ae9 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Thu, 10 Jul 2014 20:45:06 -0700 Subject: [PATCH 03/11] Tweak existing index entries --- book/01-introduction/1-introduction.asc | 6 ++-- book/02-git-basics/1-git-basics.asc | 42 ++++++++++++------------- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/book/01-introduction/1-introduction.asc b/book/01-introduction/1-introduction.asc index c72e24f31..e9c7d3255 100644 --- a/book/01-introduction/1-introduction.asc +++ b/book/01-introduction/1-introduction.asc @@ -16,7 +16,7 @@ It allows you to revert files back to a previous state, revert the entire projec Using a VCS also generally means that if you screw things up or lose files, you can easily recover. In addition, you get all this for very little overhead. -==== Local Version Control Systems (((version control,local version control))) +==== Local Version Control Systems (((version control,local))) Many people’s version-control method of choice is to copy files into another directory (perhaps a time-stamped directory, if they’re clever). This approach is very common because it is so simple, but it is also incredibly error prone. @@ -31,7 +31,7 @@ One of the more popular VCS tools was a system called RCS, which is still distri Even the popular Mac OS X operating system includes the `rcs` command when you install the Developer Tools. RCS works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches. -==== Centralized Version Control Systems (((version control,centralized version control))) +==== Centralized Version Control Systems (((version control,centralized))) The next major issue that people encounter is that they need to collaborate with developers on other systems. To deal with this problem, Centralized Version Control Systems (CVCSs) were developed. @@ -51,7 +51,7 @@ If that server goes down for an hour, then during that hour nobody can collabora If the hard disk the central database is on becomes corrupted, and proper backups haven’t been kept, you lose absolutely everything – the entire history of the project except whatever single snapshots people happen to have on their local machines. Local VCS systems suffer from this same problem – whenever you have the entire history of the project in a single place, you risk losing everything. -==== Distributed Version Control Systems (((version control,distributed version control))) +==== Distributed Version Control Systems (((version control,distributed))) This is where Distributed Version Control Systems (DVCSs) step in. In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don’t just check out the latest snapshot of the files: they fully mirror the repository. diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index 0b19ef4b9..9761d8f88 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -23,7 +23,7 @@ $ git init This creates a new subdirectory named `.git` that contains all of your necessary repository files – a Git repository skeleton. At this point, nothing in your project is tracked yet. -(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)((git, initializing)) +(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)((("git commands", init))) If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit. You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`: @@ -46,7 +46,7 @@ This is an important distinction – instead of getting just a working copy, Git Every version of every file for the history of the project is pulled down by default when you run `git clone`. In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there – see <<_git_on_the_server>> for more details). -You clone a repository with `git clone [url]`.((git, clone)) +You clone a repository with `git clone [url]`.((("git commands", clone))) For example, if you want to clone the Git linkable library called libgit2, you can do so like this: [source,shell] @@ -89,7 +89,7 @@ image::images/18333fig0201-tn.png[The lifecycle of the status of your files.] ==== Checking the Status of Your Files -The main tool you use to determine which files are in which state is the `git status` command.(((git, status))) +The main tool you use to determine which files are in which state is the `git status` command.((("git commands", status))) If you run this command directly after a clone, you should see something like this: [source,shell] @@ -106,7 +106,7 @@ For now, that branch is always ``master'', which is the default; you won’t wor <<_git_branching>> will go over branches and references in detail. Let’s say you add a new file to your project, a simple README file. -If the file didn’t exist before, and you run `git status`, you see your untracked file like so:((git, status)) +If the file didn’t exist before, and you run `git status`, you see your untracked file like so:((("git commands", status))) [source,shell] ---- @@ -128,7 +128,7 @@ You do want to start including README, so let’s start tracking the file. ==== Tracking New Files -In order to begin tracking a new file, you use the command `git add`.(((git, add))) +In order to begin tracking a new file, you use the command `git add`.((("git commands", add))) To begin tracking the README file, you can run this: [source,shell] @@ -151,7 +151,7 @@ Changes to be committed: You can tell that it’s staged because it’s under the ``Changes to be committed'' heading. If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot. -You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.(((git, init)))(((git, add))) +You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.((("git commands", init)))((("git commands", add))) The `git add` command takes a path name for either a file or a directory; if it’s a directory, the command adds all the files in that directory recursively. ==== Staging Modified Files @@ -177,7 +177,7 @@ Changes not staged for commit: ---- The ``benchmarks.rb'' file appears under a section named ``Changed but not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged. -To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.((git, add)) +To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.((("git commands", add))) Let’s run `git add` now to stage the ``benchmarks.rb'' file, and then run `git status` again: [source,shell] @@ -196,7 +196,7 @@ Changes to be committed: Both files are staged and will go into your next commit. At this point, suppose you remember one little change that you want to make in `benchmarks.rb` before you commit it. You open it again and make that change, and you’re ready to commit. -However, let’s run `git status` one more time:((git, status)) +However, let’s run `git status` one more time:((("git commands", status))) [source,shell] ---- @@ -256,7 +256,7 @@ New files that aren't tracked have a `??` next to them, new files that have been Often, you’ll have a class of files that you don’t want Git to automatically add or even show you as being untracked. These are generally automatically generated files such as log files or files produced by your build system. -In such cases, you can create a file listing patterns to match them named `.gitignore`.((ignoring files)) +In such cases, you can create a file listing patterns to match them named `.gitignore`.(((ignoring files))) Here is an example `.gitignore` file: [source,shell] @@ -301,7 +301,7 @@ GitHub maintains a fairly comprehensive list of good `.gitignore` file examples ==== Viewing Your Staged and Unstaged Changes -If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.((git, status))((git, diff)) +If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.((("git commands", status)))((("git commands", diff))) We’ll cover `git diff` in more detail later, but you’ll probably use it most often to answer these two questions: What have you changed but not yet staged? And what have you staged that you are about to commit? Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were. @@ -434,8 +434,8 @@ index 3cb747f..e445e28 100644 Now that your staging area is set up the way you want it, you can commit your changes. Remember that anything that is still unstaged – any files you have created or modified that you haven’t run `git add` on since you edited them – won’t go into this commit. They will stay as modified files on your disk. -In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.(((git, status))) -The simplest way to commit is to type `git commit`:(((git, commit))) +In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.((("git commands", status))) +The simplest way to commit is to type `git commit`:((("git commands", commit))) [source,shell] ---- @@ -443,7 +443,7 @@ $ git commit ---- Doing so launches your editor of choice. -(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).((editor, changing default)) +(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).(((editor, changing default))) The editor displays the following text (this example is a Vim screen): @@ -486,7 +486,7 @@ Remember that the commit records the snapshot you set up in your staging area. Anything you didn’t stage is still sitting there modified; you can do another commit to add it to your history. Every time you perform a commit, you’re recording a snapshot of your project that you can revert to or compare to later. -==== Skipping the Staging Area((staging area, skipping)) +==== Skipping the Staging Area(((staging area, skipping))) Although it can be amazingly useful for crafting commits exactly how you want them, the staging area is sometimes a bit more complex than you need in your workflow. If you want to skip the staging area, Git provides a simple shortcut. @@ -510,7 +510,7 @@ $ git commit -a -m 'added new benchmarks' Notice how you don’t have to run `git add` on the ``benchmarks.rb'' file in this case before you commit. -==== Removing Files((files, removing)) +==== Removing Files(((files, removing))) To remove a file from Git, you have to remove it from your tracked files (more accurately, remove it from your staging area) and then commit. The `git rm` command does that, and also removes the file from your working directory so you don’t see it as an untracked file the next time around. @@ -579,7 +579,7 @@ $ git rm \*~ This command removes all files that end with `~`. -==== Moving Files((files, moving)) +==== Moving Files(((files, moving))) Unlike many other VCS systems, Git doesn’t explicitly track file movement. If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file. @@ -633,7 +633,7 @@ To get the project, run git clone https://github.com/schacon/simplegit-progit ---- -When you run `git log` in this project, you should get output that looks something like this:((git, log)) +When you run `git log` in this project, you should get output that looks something like this:((("git commands", log))) [source,shell] ---- @@ -767,7 +767,7 @@ a11bef06a3f659402fe7563abf99ad00de2209e6 first commit ---- The most interesting option is `format`, which allows you to specify your own log output format. -This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git:((git, log formatting)) +This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git:((("git commands", log formatting))) [source,shell] ---- @@ -893,7 +893,7 @@ In <> we’ll list these and a few other common options for your | `-S` | Only show commits adding or removing code matching the string |================================ -For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:((git, log filtering)) +For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:((("git commands", log filtering))) [source,shell] ---- @@ -1050,7 +1050,7 @@ In this section, we’ll cover some of these remote-management skills. ==== Showing Your Remotes -To see which remote servers you have configured, you can run the `git remote` command.((git, remote)) +To see which remote servers you have configured, you can run the `git remote` command.((("git commands", remote))) It lists the shortnames of each remote handle you’ve specified. If you’ve cloned your repository, you should at least see origin – that is the default name Git gives to the server you cloned from: @@ -1102,7 +1102,7 @@ Notice that these remotes use a variety of protocols; we’ll cover why more abo ==== Adding Remote Repositories -I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.((git, remote)) +I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.((("git commands", remote))) To add a new remote Git repository as a shortname you can reference easily, run `git remote add [shortname] [url]`: [source,shell] From 29560f26dc9a0fd5c4c030c72c0a74b0b995e205 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Thu, 10 Jul 2014 20:49:09 -0700 Subject: [PATCH 04/11] Finish indexing chapter 2 --- book/02-git-basics/1-git-basics.asc | 30 ++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index 9761d8f88..c0eb7f76e 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -1138,7 +1138,7 @@ Paul’s master branch is now accessible locally as `pb/master` – you can merg ==== Fetching and Pulling from Your Remotes -As you just saw, to get data from your remote projects, you can run: +As you just saw, to get data from your remote projects, you can run:((("git commands", fetch))) [source,shell] ---- @@ -1160,7 +1160,7 @@ Running `git pull` generally fetches data from the server you originally cloned ==== Pushing to Your Remotes When you have your project at a point that you want to share, you have to push it upstream. -The command for this is simple: `git push [remote-name] [branch-name]`. +The command for this is simple: `git push [remote-name] [branch-name]`.((("git commands", push))) If you want to push your master branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server: [source,shell] @@ -1175,7 +1175,7 @@ See <<_git_branching>> for more detailed information on how to push to remote se ==== Inspecting a Remote -If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command. +If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.((("git commands", remote))) If you run this command with a particular shortname, such as `origin`, you get something like this: [source,shell] @@ -1220,7 +1220,7 @@ $ git remote show origin dev-branch merges with remote dev-branch master merges with remote master Local refs configured for 'git push': - dev-branch pushes to dev-branch (up to date) + dev-branch pushes to dev-branch (up to date) markdown-strip pushes to markdown-strip (up to date) master pushes to master (up to date) ---- @@ -1230,7 +1230,7 @@ It also shows you which remote branches on the server you don’t yet have, whic ==== Removing and Renaming Remotes -If you want to rename a reference you can run `git remote rename` to change a remote’s shortname. +If you want to rename a reference you can run `git remote rename` to change a remote’s shortname.((("git commands", remote))) For instance, if you want to rename `pb` to `paul`, you can do so with `git remote rename`: [source,shell] @@ -1253,7 +1253,7 @@ $ git remote origin ---- -=== Tagging +=== Tagging (((tags))) Like most VCSs, Git has the ability to tag specific points in history as being important. Typically people use this functionality to mark release points (v1.0, and so on). @@ -1262,7 +1262,7 @@ In this section, you’ll learn how to list the available tags, how to create ne ==== Listing Your Tags Listing the available tags in Git is straightforward. -Just type `git tag`: +Just type `git tag`:((("git commands", tag))) [source,shell] ---- @@ -1302,10 +1302,10 @@ Annotated tags, however, are stored as full objects in the Git database. They’re checksummed; contain the tagger name, e-mail, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG). It’s generally recommended that you create annotated tags so you can have all this information; but if you want a temporary tag or for some reason don’t want to keep the other information, lightweight tags are available too. -==== Annotated Tags +==== Annotated Tags (((tags, annotated))) Creating an annotated tag in Git is simple. -The easiest way is to specify `-a` when you run the `tag` command: +The easiest way is to specify `-a` when you run the `tag` command:((("git commands", tag))) [source,shell] ---- @@ -1339,7 +1339,7 @@ Date: Mon Mar 17 21:52:11 2008 -0700 That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information. -==== Lightweight Tags +==== Lightweight Tags (((tags, lightweight))) Another way to tag commits is with a lightweight tag. This is basically the commit checksum stored in a file – no other information is kept. @@ -1356,7 +1356,7 @@ v1.4-lw v1.5 ---- -This time, if you run `git show` on the tag, you don’t see the extra tag information. +This time, if you run `git show` on the tag, you don’t see the extra tag information.((("git commands", show))) The command just shows the commit: [source,shell] @@ -1398,7 +1398,7 @@ To tag that commit, you specify the commit checksum (or part of it) at the end o $ git tag -a v1.2 9fceb02 ---- -You can see that you’ve tagged the commit: +You can see that you’ve tagged the commit:((("git commands", tag))) [source,shell] ---- @@ -1426,7 +1426,7 @@ Date: Sun Apr 27 20:43:35 2008 -0700 ==== Sharing Tags -By default, the `git push` command doesn’t transfer tags to remote servers. +By default, the `git push` command doesn’t transfer tags to remote servers.((("git commands", push))) You will have to explicitly push tags to a shared server after you have created them. This process is just like sharing remote branches – you can run `git push origin [tagname]`. @@ -1459,13 +1459,13 @@ To git@github.com:schacon/simplegit.git Now, when someone else clones or pulls from your repository, they will get all your tags as well. -=== Git Aliases +=== Git Aliases(((aliases))) Before we finish this chapter on basic Git, there's just one little tip that can make your Git experience simpler, easier, and more familiar: aliases. We won’t refer to them or assume you’ve used them later in the book, but you should probably know how to use them. Git doesn’t automatically infer your command if you type it in partially. -If you don’t want to type the entire text of each of the Git commands, you can easily set up an alias for each command using `git config`. +If you don’t want to type the entire text of each of the Git commands, you can easily set up an alias for each command using `git config`.((("git commands", config))) Here are a couple of examples you may want to set up: [source,shell] From 94a43263db1972c5a413938c2ba0dccd034ecf39 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Thu, 10 Jul 2014 20:51:04 -0700 Subject: [PATCH 05/11] Simplify index terms --- book/02-git-basics/1-git-basics.asc | 52 ++++++++++++++--------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index c0eb7f76e..4eabe1854 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -23,7 +23,7 @@ $ git init This creates a new subdirectory named `.git` that contains all of your necessary repository files – a Git repository skeleton. At this point, nothing in your project is tracked yet. -(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)((("git commands", init))) +(See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)(((git commands, init))) If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit. You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`: @@ -46,7 +46,7 @@ This is an important distinction – instead of getting just a working copy, Git Every version of every file for the history of the project is pulled down by default when you run `git clone`. In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there – see <<_git_on_the_server>> for more details). -You clone a repository with `git clone [url]`.((("git commands", clone))) +You clone a repository with `git clone [url]`.(((git commands, clone))) For example, if you want to clone the Git linkable library called libgit2, you can do so like this: [source,shell] @@ -89,7 +89,7 @@ image::images/18333fig0201-tn.png[The lifecycle of the status of your files.] ==== Checking the Status of Your Files -The main tool you use to determine which files are in which state is the `git status` command.((("git commands", status))) +The main tool you use to determine which files are in which state is the `git status` command.(((git commands, status))) If you run this command directly after a clone, you should see something like this: [source,shell] @@ -106,7 +106,7 @@ For now, that branch is always ``master'', which is the default; you won’t wor <<_git_branching>> will go over branches and references in detail. Let’s say you add a new file to your project, a simple README file. -If the file didn’t exist before, and you run `git status`, you see your untracked file like so:((("git commands", status))) +If the file didn’t exist before, and you run `git status`, you see your untracked file like so:(((git commands, status))) [source,shell] ---- @@ -128,7 +128,7 @@ You do want to start including README, so let’s start tracking the file. ==== Tracking New Files -In order to begin tracking a new file, you use the command `git add`.((("git commands", add))) +In order to begin tracking a new file, you use the command `git add`.(((git commands, add))) To begin tracking the README file, you can run this: [source,shell] @@ -151,7 +151,7 @@ Changes to be committed: You can tell that it’s staged because it’s under the ``Changes to be committed'' heading. If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot. -You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.((("git commands", init)))((("git commands", add))) +You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add))) The `git add` command takes a path name for either a file or a directory; if it’s a directory, the command adds all the files in that directory recursively. ==== Staging Modified Files @@ -177,7 +177,7 @@ Changes not staged for commit: ---- The ``benchmarks.rb'' file appears under a section named ``Changed but not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged. -To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.((("git commands", add))) +To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.(((git commands, add))) Let’s run `git add` now to stage the ``benchmarks.rb'' file, and then run `git status` again: [source,shell] @@ -196,7 +196,7 @@ Changes to be committed: Both files are staged and will go into your next commit. At this point, suppose you remember one little change that you want to make in `benchmarks.rb` before you commit it. You open it again and make that change, and you’re ready to commit. -However, let’s run `git status` one more time:((("git commands", status))) +However, let’s run `git status` one more time:(((git commands, status))) [source,shell] ---- @@ -301,7 +301,7 @@ GitHub maintains a fairly comprehensive list of good `.gitignore` file examples ==== Viewing Your Staged and Unstaged Changes -If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.((("git commands", status)))((("git commands", diff))) +If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.(((git commands, status)))(((git commands, diff))) We’ll cover `git diff` in more detail later, but you’ll probably use it most often to answer these two questions: What have you changed but not yet staged? And what have you staged that you are about to commit? Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were. @@ -434,8 +434,8 @@ index 3cb747f..e445e28 100644 Now that your staging area is set up the way you want it, you can commit your changes. Remember that anything that is still unstaged – any files you have created or modified that you haven’t run `git add` on since you edited them – won’t go into this commit. They will stay as modified files on your disk. -In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.((("git commands", status))) -The simplest way to commit is to type `git commit`:((("git commands", commit))) +In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.(((git commands, status))) +The simplest way to commit is to type `git commit`:(((git commands, commit))) [source,shell] ---- @@ -633,7 +633,7 @@ To get the project, run git clone https://github.com/schacon/simplegit-progit ---- -When you run `git log` in this project, you should get output that looks something like this:((("git commands", log))) +When you run `git log` in this project, you should get output that looks something like this:(((git commands, log))) [source,shell] ---- @@ -767,7 +767,7 @@ a11bef06a3f659402fe7563abf99ad00de2209e6 first commit ---- The most interesting option is `format`, which allows you to specify your own log output format. -This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git:((("git commands", log formatting))) +This is especially useful when you’re generating output for machine parsing – because you specify the format explicitly, you know it won’t change with updates to Git:(((log formatting))) [source,shell] ---- @@ -893,7 +893,7 @@ In <> we’ll list these and a few other common options for your | `-S` | Only show commits adding or removing code matching the string |================================ -For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:((("git commands", log filtering))) +For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:(((log filtering))) [source,shell] ---- @@ -1050,7 +1050,7 @@ In this section, we’ll cover some of these remote-management skills. ==== Showing Your Remotes -To see which remote servers you have configured, you can run the `git remote` command.((("git commands", remote))) +To see which remote servers you have configured, you can run the `git remote` command.(((git commands, remote))) It lists the shortnames of each remote handle you’ve specified. If you’ve cloned your repository, you should at least see origin – that is the default name Git gives to the server you cloned from: @@ -1102,7 +1102,7 @@ Notice that these remotes use a variety of protocols; we’ll cover why more abo ==== Adding Remote Repositories -I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.((("git commands", remote))) +I’ve mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.(((git commands, remote))) To add a new remote Git repository as a shortname you can reference easily, run `git remote add [shortname] [url]`: [source,shell] @@ -1138,7 +1138,7 @@ Paul’s master branch is now accessible locally as `pb/master` – you can merg ==== Fetching and Pulling from Your Remotes -As you just saw, to get data from your remote projects, you can run:((("git commands", fetch))) +As you just saw, to get data from your remote projects, you can run:(((git commands, fetch))) [source,shell] ---- @@ -1160,7 +1160,7 @@ Running `git pull` generally fetches data from the server you originally cloned ==== Pushing to Your Remotes When you have your project at a point that you want to share, you have to push it upstream. -The command for this is simple: `git push [remote-name] [branch-name]`.((("git commands", push))) +The command for this is simple: `git push [remote-name] [branch-name]`.(((git commands, push))) If you want to push your master branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server: [source,shell] @@ -1175,7 +1175,7 @@ See <<_git_branching>> for more detailed information on how to push to remote se ==== Inspecting a Remote -If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.((("git commands", remote))) +If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.(((git commands, remote))) If you run this command with a particular shortname, such as `origin`, you get something like this: [source,shell] @@ -1230,7 +1230,7 @@ It also shows you which remote branches on the server you don’t yet have, whic ==== Removing and Renaming Remotes -If you want to rename a reference you can run `git remote rename` to change a remote’s shortname.((("git commands", remote))) +If you want to rename a reference you can run `git remote rename` to change a remote’s shortname.(((git commands, remote))) For instance, if you want to rename `pb` to `paul`, you can do so with `git remote rename`: [source,shell] @@ -1262,7 +1262,7 @@ In this section, you’ll learn how to list the available tags, how to create ne ==== Listing Your Tags Listing the available tags in Git is straightforward. -Just type `git tag`:((("git commands", tag))) +Just type `git tag`:(((git commands, tag))) [source,shell] ---- @@ -1305,7 +1305,7 @@ It’s generally recommended that you create annotated tags so you can have all ==== Annotated Tags (((tags, annotated))) Creating an annotated tag in Git is simple. -The easiest way is to specify `-a` when you run the `tag` command:((("git commands", tag))) +The easiest way is to specify `-a` when you run the `tag` command:(((git commands, tag))) [source,shell] ---- @@ -1356,7 +1356,7 @@ v1.4-lw v1.5 ---- -This time, if you run `git show` on the tag, you don’t see the extra tag information.((("git commands", show))) +This time, if you run `git show` on the tag, you don’t see the extra tag information.(((git commands, show))) The command just shows the commit: [source,shell] @@ -1398,7 +1398,7 @@ To tag that commit, you specify the commit checksum (or part of it) at the end o $ git tag -a v1.2 9fceb02 ---- -You can see that you’ve tagged the commit:((("git commands", tag))) +You can see that you’ve tagged the commit:(((git commands, tag))) [source,shell] ---- @@ -1426,7 +1426,7 @@ Date: Sun Apr 27 20:43:35 2008 -0700 ==== Sharing Tags -By default, the `git push` command doesn’t transfer tags to remote servers.((("git commands", push))) +By default, the `git push` command doesn’t transfer tags to remote servers.(((git commands, push))) You will have to explicitly push tags to a shared server after you have created them. This process is just like sharing remote branches – you can run `git push origin [tagname]`. @@ -1465,7 +1465,7 @@ Before we finish this chapter on basic Git, there's just one little tip that can We won’t refer to them or assume you’ve used them later in the book, but you should probably know how to use them. Git doesn’t automatically infer your command if you type it in partially. -If you don’t want to type the entire text of each of the Git commands, you can easily set up an alias for each command using `git config`.((("git commands", config))) +If you don’t want to type the entire text of each of the Git commands, you can easily set up an alias for each command using `git config`.(((git commands, config))) Here are a couple of examples you may want to set up: [source,shell] From 07aa0f8b9db8fbd2cdf076344dc6239c548b7236 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Thu, 10 Jul 2014 21:13:35 -0700 Subject: [PATCH 06/11] Add index entries for chapter 3 --- book/03-git-branching/1-git-branching.asc | 68 ++++++++++++----------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/book/03-git-branching/1-git-branching.asc b/book/03-git-branching/1-git-branching.asc index 931fa3851..142115c0c 100644 --- a/book/03-git-branching/1-git-branching.asc +++ b/book/03-git-branching/1-git-branching.asc @@ -1,5 +1,5 @@ [[_git_branching]] -== Git Branching(((git, branching))) +== Git Branching(((branches))) Nearly every VCS has some form of branching support. Branching means you diverge from the main line of development and continue to do work without messing with that main line. @@ -30,7 +30,7 @@ $ git commit -m 'initial commit of my project' ---- When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores those tree objects in the Git repository. -Git then creates a commit object that has the metadata and a pointer to the root project tree so it can re-create that snapshot when needed. +Git then creates a commit object that has the metadata and a pointer to the root project tree so it can re-create that snapshot when needed.(((git commands, commit))) Your Git repository now contains five objects: one blob for the contents of each of your three files, one tree that lists the contents of the directory and specifies which file names are stored as which blobs, and one commit with the pointer to that root tree and all the commit metadata. @@ -49,18 +49,20 @@ Every time you commit, it moves forward automatically. [NOTE] ==== -The ``master'' branch in Git is not a special branch. It is exactly like any other branch. The only reason nearly every repository has one is that the `git init` command creates it by default and most people don't bother to change it. +The ``master'' branch in Git is not a special branch.(((master))) +It is exactly like any other branch. +The only reason nearly every repository has one is that the `git init` command creates it by default and most people don't bother to change it. ==== .A branch and its commit history image::images/branch-and-history.png[A branch and its commit history.] -==== Creating a new branch +==== Creating a new branch(((branches, creating))) What happens if you create a new branch? Well, doing so creates a new pointer for you to move around. Let's say you create a new branch called testing. -You do this with the `git branch` command: +You do this with the `git branch` command:(((git commands, branch))) [source,shell] ---- @@ -94,9 +96,9 @@ f30ab (HEAD, master, testing) add feature #32 - ability to add new formats to th You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit. -==== Switching branches +==== Switching branches(((branches, switching))) -To switch to an existing branch, you run the `git checkout` command. +To switch to an existing branch, you run the `git checkout` command.(((git commands, checkout))) Let's switch to the new testing branch: [source,shell] @@ -140,7 +142,9 @@ It essentially rewinds the work you've done in your testing branch so you can go [NOTE] .Switching branches changes files in your working directory ==== -It's important to note that when you switch branches in Git, files in your working directory will change. If you switch to an older branch, your working directory will be reverted to look like it did the last time you committed on that branch. If Git cannot do it cleanly, it will not let you switch at all. +It's important to note that when you switch branches in Git, files in your working directory will change. +If you switch to an older branch, your working directory will be reverted to look like it did the last time you committed on that branch. +If Git cannot do it cleanly, it will not let you switch at all. ==== Let's make a few changes and commit again: @@ -151,15 +155,17 @@ $ vim test.rb $ git commit -a -m 'made other changes' ---- -Now your project history has diverged (see Figure 3-9). +Now your project history has diverged (see <>). You created and switched to a branch, did some work on it, and then switched back to your main branch and did other work. Both of those changes are isolated in separate branches: you can switch back and forth between the branches and merge them together when you're ready. And you did all that with simple `branch`, `checkout`, and `commit` commands. +[[divergent_history]] .Divergent history image::images/advance-master.png[Divergent history.] -You can also see this easily with the `git log` command. If you run `git log --oneline --decorate --graph --all` it will print out the history of your commits, showing where your branch pointers are and how your history has diverged. +You can also see this easily with the `git log` command. +If you run `git log --oneline --decorate --graph --all` it will print out the history of your commits, showing where your branch pointers are and how your history has diverged. [source,shell] ---- @@ -199,7 +205,7 @@ You'll do the following: . After it's tested, merge the hotfix branch, and push to production. . Switch back to your original story and continue working. -==== Basic Branching +==== Basic Branching(((branches, basic workflow))) First, let's say you're working on your project and have a couple of commits already. @@ -274,7 +280,7 @@ $ git commit -a -m 'fixed the broken email address' image::images/basic-branching-4.png[Hotfix branch based on `master`.] You can run your tests, make sure the hotfix is what you want, and merge it back into your master branch to deploy to production. -You do this with the `git merge` command: +You do this with the `git merge` command:(((git commands, merge))) [source,shell] ---- @@ -323,7 +329,7 @@ image::images/basic-branching-6.png[Work continues on `iss53`.] It's worth noting here that the work you did in your `hotfix` branch is not contained in the files in your `iss53` branch. If you need to pull it in, you can merge your `master` branch into your `iss53` branch by running `git merge master`, or you can wait to integrate those changes until you decide to pull the `iss53` branch back into `master` later. -==== Basic Merging +==== Basic Merging(((branches, merging)))(((merging))) Suppose you've decided that your issue #53 work is complete and ready to be merged into your `master` branch. In order to do that, you'll merge in your `iss53` branch, much like you merged in your `hotfix` branch earlier. @@ -364,7 +370,7 @@ You can close the ticket in your ticket-tracking system, and delete the branch: $ git branch -d iss53 ---- -==== Basic Merge Conflicts +==== Basic Merge Conflicts(((merging, conflicts))) Occasionally, this process doesn't go smoothly. If you changed the same part of the same file differently in the two branches you're merging together, Git won't be able to merge them cleanly. @@ -426,7 +432,7 @@ please contact us at email.support@github.com This resolution has a little of each section, and the `<<<<<<<`, `=======`, and `>>>>>>>` lines have been completely removed. After you've resolved each of these sections in each conflicted file, run `git add` on each file to mark it as resolved. Staging the file marks it as resolved in Git. -If you want to use a graphical tool to resolve these issues, you can run `git mergetool`, which fires up an appropriate visual merge tool and walks you through the conflicts: +If you want to use a graphical tool to resolve these issues, you can run `git mergetool`, which fires up an appropriate visual merge tool and walks you through the conflicts:(((git commands, mergetool))) [source,shell] ---- @@ -493,11 +499,11 @@ Conflicts: You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future – why you did what you did, if it's not obvious. -=== Branch Management +=== Branch Management(((branches, managing))) Now that you've created, merged, and deleted some branches, let's look at some branch-management tools that will come in handy when you begin using branches all the time. -The `git branch` command does more than just create and delete branches. +The `git branch` command does more than just create and delete branches.(((git commands, branch))) If you run it with no arguments, you get a simple listing of your current branches: [source,shell] @@ -558,7 +564,7 @@ If you really do want to delete the branch and lose that work, you can force it Now that you have the basics of branching and merging down, what can or should you do with them? In this section, we'll cover some common workflows that this lightweight branching makes possible, so you can decide if you would like to incorporate it into your own development cycle. -==== Long-Running Branches +==== Long-Running Branches(((branches, long-running))) Because Git uses a simple three-way merge, merging from one branch into another multiple times over a long period is generally easy to do. This means you can have several branches that are always open and that you use for different stages of your development cycle; you can merge regularly from some of them into others. @@ -585,7 +591,7 @@ The idea is that your branches are at various levels of stability; when they rea Again, having multiple long-running branches isn't necessary, but it's often helpful, especially when you're dealing with very large or complex projects. [[_topic_branches]] -==== Topic Branches +==== Topic Branches(((branches, topic))) Topic branches, however, are useful in projects of any size. A topic branch is a short-lived branch that you create and use for a single particular feature or related work. @@ -615,7 +621,7 @@ We will go into more detail about the various possible workflows for your Git pr It's important to remember when you're doing all this that these branches are completely local. When you're branching and merging, everything is being done only in your Git repository – no server communication is happening. -=== Remote Branches +=== Remote Branches(((branches, remote)))(((references, remote))) Remote branches are references (pointers) to the state of branches in your remote repositories. They're local branches that you can't move; they're moved automatically for you whenever you do any network communication. @@ -633,7 +639,7 @@ Git also gives you your own local `master` branch starting at the same place as [NOTE] .``origin'' is not special ==== -Just like the branch name ``master'' does not have any special meaning in Git, neither does ``origin''. While ``master'' is the default name for a starting branch when you run `git init` which is the only reason it's widely used, ``origin'' is the default name for a remote when you run `git clone`. If you run `git clone -o booyah` instead, then you will have `booyah/master` as your default remote branch. +Just like the branch name ``master'' does not have any special meaning in Git, neither does ``origin''. While ``master'' is the default name for a starting branch when you run `git init` which is the only reason it's widely used, ``origin'' is the default name for a remote when you run `git clone`. If you run `git clone -o booyah` instead, then you will have `booyah/master` as your default remote branch.(((origin))) ==== .Server and local repositories after cloning @@ -665,14 +671,14 @@ Because that server is a subset of the data your `origin` server has right now, .Remote tracking branch for `teamone/master` image::images/remote-branches-5.png[Remote tracking branch for `teamone/master`.] -==== Pushing +==== Pushing(((pushing))) When you want to share a branch with the world, you need to push it up to a remote that you have write access to. Your local branches aren't automatically synchronized to the remotes you write to – you have to explicitly push the branches you want to share. That way, you can use private branches for work you don't want to share, and push up only the topic branches you want to collaborate on. If you have a branch named `serverfix` that you want to work on with others, you can push it up the same way you pushed your first branch. -Run `git push (remote) (branch)`: +Run `git push (remote) (branch)`:(((git commands, push))) [source,shell] ---- @@ -721,7 +727,7 @@ Switched to a new branch 'serverfix' This gives you a local branch that you can work on that starts where `origin/serverfix` is. -==== Tracking Branches +==== Tracking Branches(((branches, tracking)))(((branches, upstream))) Checking out a local branch from a remote branch automatically creates what is called a ``tracking branch'' (or sometimes an ``upstream branch''). Tracking branches are local branches that have a direct relationship to a remote branch. @@ -763,7 +769,7 @@ Branch serverfix set up to track remote branch serverfix from origin. [NOTE] .Upstream shorthand ==== -When you have an tracking branch set up, you can reference it with the `@{upstream}` or `@{u}` shorthand. So if you're on the `master` branch and it's tracking `origin/master`, you can say something like `git merge @{u}` instead of `git merge origin/master` if you wish. +When you have an tracking branch set up, you can reference it with the `@{upstream}` or `@{u}` shorthand. So if you're on the `master` branch and it's tracking `origin/master`, you can say something like `git merge @{u}` instead of `git merge origin/master` if you wish.(((+++@{u}+++)))(((+++@{upstream}+++))) ==== If you want to see what tracking branches you have set up, you can use the `-vv` option to `git branch`. This will list out your local branches with more information including what each branch is tracking and if your local branch is ahead, behind or both. @@ -781,7 +787,7 @@ So here we can see that our `iss53` branch is tracking `origin/iss53` and is ``a It's important to note that these numbers are only since the last time you fetched from each server. This command does not reach out to the servers, it's telling you about what it has cached from these servers locally. If you want totally up to date ahead and behind numbers, you'll need to fetch from all your remotes right before running this. You could do that like this: `$ git fetch --all; git branch -vv` -==== Pulling +==== Pulling(((pulling))) While the `git fetch` command will fetch down all the changes on the server that you don't have yet, it will not modify your working directory at all. It will simply get the data for you and let you merge it yourself. @@ -790,7 +796,7 @@ If you have a tracking branch set up as demonstrated in the last section, either There are other uses of the `pull` command that we'll address in [[_git_tools]], but generally it's better to simply use the `fetch` and `merge` commands explicitly as the magic of `git pull` can often be confusing. -==== Deleting Remote Branches +==== Deleting Remote Branches(((branches, deleting remote))) Suppose you're done with a remote branch – say you and your collaborators are finished with a feature and have merged it into your remote's `master` branch (or whatever branch your stable codeline is in). You can delete a remote branch using the `--delete` option to `git push`. @@ -806,7 +812,7 @@ To https://github.com/schacon/simplegit Basically all this does is remove the pointer from the server. The Git server will generally keep the data there for a while until a garbage collection runs, so if it was accidentally deleted, it's often easy to recover. [[_rebasing]] -=== Rebasing +=== Rebasing(((rebasing))) In Git, there are two main ways to integrate changes from one branch into another: the `merge` and the `rebase`. In this section you'll learn what rebasing is, how to do it, why it's a pretty amazing tool, and in what cases you won't want to use it. @@ -826,7 +832,7 @@ image::images/basic-rebase-2.png[Merging to integrate diverged work history.] However, there is another way: you can take the patch of the change that was introduced in `C3` and reapply it on top of `C4`. In Git, this is called _rebasing_. -With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one. +With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.(((git commands, rebase))) In this example, you'd run the following: @@ -932,7 +938,7 @@ $ git branch -d server image::images/interesting-rebase-5.png[Final commit history.] [[_rebase_peril]] -==== The Perils of Rebasing +==== The Perils of Rebasing(((rebasing, perils of))) Ahh, but the bliss of rebasing isn't without its drawbacks, which can be summed up in a single line: @@ -987,7 +993,7 @@ So don't do it. But if you do, tell everyone who's working on that branch to `git pull --rebase`. -==== Rebase vs. Merge +==== Rebase vs. Merge(((rebasing, vs. merging)))(((merging, vs. rebasing))) Now that you've seen rebasing and merging in action, you may be wondering which one is better. Before we can answer this, let's step back a bit and talk about what history means. From b66651fd7bdf4d80edfc2ad4c81b5115a61f9239 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Fri, 11 Jul 2014 18:39:11 -0700 Subject: [PATCH 07/11] Fix messed-up index entries --- book/01-introduction/1-introduction.asc | 24 +++++++---- book/03-git-branching/1-git-branching.asc | 51 +++++++++++++++-------- 2 files changed, 49 insertions(+), 26 deletions(-) diff --git a/book/01-introduction/1-introduction.asc b/book/01-introduction/1-introduction.asc index f1ea77eab..0477ba165 100644 --- a/book/01-introduction/1-introduction.asc +++ b/book/01-introduction/1-introduction.asc @@ -5,8 +5,9 @@ This chapter will be about getting started with Git. We will begin at the beginning by explaining some background on version control tools, then move on to how to get Git running on your system and finally how to get it setup to start working with. At the end of this chapter you should understand why Git is around, why you should use it and you should be all setup to do so. -=== About Version Control (((version control))) +=== About Version Control +(((version control))) What is "version control", and why should you care? Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. For the examples in this book you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer. @@ -16,8 +17,9 @@ It allows you to revert files back to a previous state, revert the entire projec Using a VCS also generally means that if you screw things up or lose files, you can easily recover. In addition, you get all this for very little overhead. -==== Local Version Control Systems (((version control,local))) +==== Local Version Control Systems +(((version control,local))) Many people’s version-control method of choice is to copy files into another directory (perhaps a time-stamped directory, if they’re clever). This approach is very common because it is so simple, but it is also incredibly error prone. It is easy to forget which directory you’re in and accidentally write to the wrong file or copy over files you don’t mean to. @@ -31,8 +33,9 @@ One of the more popular VCS tools was a system called RCS, which is still distri Even the popular Mac OS X operating system includes the `rcs` command when you install the Developer Tools. RCS works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches. -==== Centralized Version Control Systems (((version control,centralized))) +==== Centralized Version Control Systems +(((version control,centralized))) The next major issue that people encounter is that they need to collaborate with developers on other systems. To deal with this problem, Centralized Version Control Systems (CVCSs) were developed. These systems, such as CVS, Subversion, and Perforce, have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce))) @@ -51,8 +54,9 @@ If that server goes down for an hour, then during that hour nobody can collabora If the hard disk the central database is on becomes corrupted, and proper backups haven’t been kept, you lose absolutely everything – the entire history of the project except whatever single snapshots people happen to have on their local machines. Local VCS systems suffer from this same problem – whenever you have the entire history of the project in a single place, you risk losing everything. -==== Distributed Version Control Systems (((version control,distributed))) +==== Distributed Version Control Systems +(((version control,distributed))) This is where Distributed Version Control Systems (DVCSs) step in. In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don’t just check out the latest snapshot of the files: they fully mirror the repository. Thus if any server dies, and these systems were collaborating via it, any of the client repositories can be copied back up to the server to restore it. @@ -209,8 +213,9 @@ Before you start using Git, you have to make it available on your computer. Even if it's already installed, it's probably a good idea to update to the latest version. You can either install it as a package or via another installer, or download the source code and compile it yourself. -==== Installing on Linux(((Linux, installing))) +==== Installing on Linux +(((Linux, installing))) If you want to install Git on Linux via a binary installer, you can generally do so through the basic package-management tool that comes with your distribution. If you’re on Fedora for example, you can use yum: @@ -222,8 +227,9 @@ If you’re on a Debian-based distribution like Ubuntu, try apt-get: For more options, there are instructions for installing on several different Unix flavors on the Git website, at http://git-scm.com/download/linux[]. -==== Installing on Mac(((Mac, installing))) +==== Installing on Mac +(((Mac, installing))) There are several ways to install Git on a Mac. The easiest is probably to install the Xcode Command Line Tools.(((Xcode))) On Mavericks (10.9) or above you can do this simply by trying to run 'git' from the Terminal the very first time. @@ -289,7 +295,7 @@ Now that you have Git on your system, you’ll want to do a few things to custom You should have to do these things only once on any given computer; they’ll stick around between upgrades. You can also change them at any time by running through the commands again. -Git comes with a tool called `git config` that lets you get and set configuration variables that control all aspects of how Git looks and operates.(((git, config))) +Git comes with a tool called `git config` that lets you get and set configuration variables that control all aspects of how Git looks and operates.(((git commands, config))) These variables can be stored in three different places: 1. `/etc/gitconfig` file: Contains values for every user on the system and all their repositories. @@ -345,7 +351,7 @@ If you want to check your settings, you can use the `git config --list` command You may see keys more than once, because Git reads the same key from different files (`/etc/gitconfig` and `~/.gitconfig`, for example). In this case, Git uses the last value for each unique key it sees. -You can also check what Git thinks a specific key’s value is by typing `git config `:(((git, config))) +You can also check what Git thinks a specific key’s value is by typing `git config `:(((git commands, config))) $ git config user.name John Doe @@ -358,7 +364,7 @@ If you ever need help while using Git, there are three ways to get the manual pa $ git --help $ man git- -For example, you can get the manpage help for the config command by running(((git, help))) +For example, you can get the manpage help for the config command by running(((git commands, help))) $ git help config diff --git a/book/03-git-branching/1-git-branching.asc b/book/03-git-branching/1-git-branching.asc index 142115c0c..9737bdcc8 100644 --- a/book/03-git-branching/1-git-branching.asc +++ b/book/03-git-branching/1-git-branching.asc @@ -1,6 +1,7 @@ [[_git_branching]] -== Git Branching(((branches))) +== Git Branching +(((branches))) Nearly every VCS has some form of branching support. Branching means you diverge from the main line of development and continue to do work without messing with that main line. In many VCS tools, this is a somewhat expensive process, often requiring you to create a new copy of your source code directory, which can take a long time for large projects. @@ -57,8 +58,9 @@ The only reason nearly every repository has one is that the `git init` command c .A branch and its commit history image::images/branch-and-history.png[A branch and its commit history.] -==== Creating a new branch(((branches, creating))) +==== Creating a new branch +(((branches, creating))) What happens if you create a new branch? Well, doing so creates a new pointer for you to move around. Let's say you create a new branch called testing. @@ -96,8 +98,9 @@ f30ab (HEAD, master, testing) add feature #32 - ability to add new formats to th You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit. -==== Switching branches(((branches, switching))) +==== Switching branches +(((branches, switching))) To switch to an existing branch, you run the `git checkout` command.(((git commands, checkout))) Let's switch to the new testing branch: @@ -205,8 +208,9 @@ You'll do the following: . After it's tested, merge the hotfix branch, and push to production. . Switch back to your original story and continue working. -==== Basic Branching(((branches, basic workflow))) +==== Basic Branching +(((branches, basic workflow))) First, let's say you're working on your project and have a couple of commits already. .A simple commit history @@ -329,8 +333,9 @@ image::images/basic-branching-6.png[Work continues on `iss53`.] It's worth noting here that the work you did in your `hotfix` branch is not contained in the files in your `iss53` branch. If you need to pull it in, you can merge your `master` branch into your `iss53` branch by running `git merge master`, or you can wait to integrate those changes until you decide to pull the `iss53` branch back into `master` later. -==== Basic Merging(((branches, merging)))(((merging))) +==== Basic Merging +(((branches, merging)))(((merging))) Suppose you've decided that your issue #53 work is complete and ready to be merged into your `master` branch. In order to do that, you'll merge in your `iss53` branch, much like you merged in your `hotfix` branch earlier. All you have to do is check out the branch you wish to merge into and then run the `git merge` command: @@ -370,8 +375,9 @@ You can close the ticket in your ticket-tracking system, and delete the branch: $ git branch -d iss53 ---- -==== Basic Merge Conflicts(((merging, conflicts))) +==== Basic Merge Conflicts +(((merging, conflicts))) Occasionally, this process doesn't go smoothly. If you changed the same part of the same file differently in the two branches you're merging together, Git won't be able to merge them cleanly. If your fix for issue #53 modified the same part of a file as the `hotfix`, you'll get a merge conflict that looks something like this: @@ -499,8 +505,9 @@ Conflicts: You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future – why you did what you did, if it's not obvious. -=== Branch Management(((branches, managing))) +=== Branch Management +(((branches, managing))) Now that you've created, merged, and deleted some branches, let's look at some branch-management tools that will come in handy when you begin using branches all the time. The `git branch` command does more than just create and delete branches.(((git commands, branch))) @@ -564,8 +571,9 @@ If you really do want to delete the branch and lose that work, you can force it Now that you have the basics of branching and merging down, what can or should you do with them? In this section, we'll cover some common workflows that this lightweight branching makes possible, so you can decide if you would like to incorporate it into your own development cycle. -==== Long-Running Branches(((branches, long-running))) +==== Long-Running Branches +(((branches, long-running))) Because Git uses a simple three-way merge, merging from one branch into another multiple times over a long period is generally easy to do. This means you can have several branches that are always open and that you use for different stages of your development cycle; you can merge regularly from some of them into others. @@ -591,8 +599,9 @@ The idea is that your branches are at various levels of stability; when they rea Again, having multiple long-running branches isn't necessary, but it's often helpful, especially when you're dealing with very large or complex projects. [[_topic_branches]] -==== Topic Branches(((branches, topic))) +==== Topic Branches +(((branches, topic))) Topic branches, however, are useful in projects of any size. A topic branch is a short-lived branch that you create and use for a single particular feature or related work. This is something you've likely never done with a VCS before because it's generally too expensive to create and merge branches. @@ -621,8 +630,9 @@ We will go into more detail about the various possible workflows for your Git pr It's important to remember when you're doing all this that these branches are completely local. When you're branching and merging, everything is being done only in your Git repository – no server communication is happening. -=== Remote Branches(((branches, remote)))(((references, remote))) +=== Remote Branches +(((branches, remote)))(((references, remote))) Remote branches are references (pointers) to the state of branches in your remote repositories. They're local branches that you can't move; they're moved automatically for you whenever you do any network communication. Remote branches act as bookmarks to remind you where the branches on your remote repositories were the last time you connected to them. @@ -671,8 +681,9 @@ Because that server is a subset of the data your `origin` server has right now, .Remote tracking branch for `teamone/master` image::images/remote-branches-5.png[Remote tracking branch for `teamone/master`.] -==== Pushing(((pushing))) +==== Pushing +(((pushing))) When you want to share a branch with the world, you need to push it up to a remote that you have write access to. Your local branches aren't automatically synchronized to the remotes you write to – you have to explicitly push the branches you want to share. That way, you can use private branches for work you don't want to share, and push up only the topic branches you want to collaborate on. @@ -727,8 +738,9 @@ Switched to a new branch 'serverfix' This gives you a local branch that you can work on that starts where `origin/serverfix` is. -==== Tracking Branches(((branches, tracking)))(((branches, upstream))) +==== Tracking Branches +(((branches, tracking)))(((branches, upstream))) Checking out a local branch from a remote branch automatically creates what is called a ``tracking branch'' (or sometimes an ``upstream branch''). Tracking branches are local branches that have a direct relationship to a remote branch. If you're on a tracking branch and type `git push`, Git automatically knows which server and branch to push to. @@ -787,8 +799,9 @@ So here we can see that our `iss53` branch is tracking `origin/iss53` and is ``a It's important to note that these numbers are only since the last time you fetched from each server. This command does not reach out to the servers, it's telling you about what it has cached from these servers locally. If you want totally up to date ahead and behind numbers, you'll need to fetch from all your remotes right before running this. You could do that like this: `$ git fetch --all; git branch -vv` -==== Pulling(((pulling))) +==== Pulling +(((pulling))) While the `git fetch` command will fetch down all the changes on the server that you don't have yet, it will not modify your working directory at all. It will simply get the data for you and let you merge it yourself. However, there is a command called `git pull` which is essentially a `git fetch` immediately followed by a `git merge` in most cases. @@ -796,8 +809,9 @@ If you have a tracking branch set up as demonstrated in the last section, either There are other uses of the `pull` command that we'll address in [[_git_tools]], but generally it's better to simply use the `fetch` and `merge` commands explicitly as the magic of `git pull` can often be confusing. -==== Deleting Remote Branches(((branches, deleting remote))) +==== Deleting Remote Branches +(((branches, deleting remote))) Suppose you're done with a remote branch – say you and your collaborators are finished with a feature and have merged it into your remote's `master` branch (or whatever branch your stable codeline is in). You can delete a remote branch using the `--delete` option to `git push`. If you want to delete your `serverfix` branch from the server, you run the following: @@ -812,8 +826,9 @@ To https://github.com/schacon/simplegit Basically all this does is remove the pointer from the server. The Git server will generally keep the data there for a while until a garbage collection runs, so if it was accidentally deleted, it's often easy to recover. [[_rebasing]] -=== Rebasing(((rebasing))) +=== Rebasing +(((rebasing))) In Git, there are two main ways to integrate changes from one branch into another: the `merge` and the `rebase`. In this section you'll learn what rebasing is, how to do it, why it's a pretty amazing tool, and in what cases you won't want to use it. @@ -938,8 +953,9 @@ $ git branch -d server image::images/interesting-rebase-5.png[Final commit history.] [[_rebase_peril]] -==== The Perils of Rebasing(((rebasing, perils of))) +==== The Perils of Rebasing +(((rebasing, perils of))) Ahh, but the bliss of rebasing isn't without its drawbacks, which can be summed up in a single line: **Do not rebase commits that exist outside your repository.** @@ -993,8 +1009,9 @@ So don't do it. But if you do, tell everyone who's working on that branch to `git pull --rebase`. -==== Rebase vs. Merge(((rebasing, vs. merging)))(((merging, vs. rebasing))) +==== Rebase vs. Merge +(((rebasing, vs. merging)))(((merging, vs. rebasing))) Now that you've seen rebasing and merging in action, you may be wondering which one is better. Before we can answer this, let's step back a bit and talk about what history means. From 1c8b76027fab51967387b3076103dc2c317eaf53 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Fri, 11 Jul 2014 18:58:02 -0700 Subject: [PATCH 08/11] Add index entries for Chapter 4 --- book/04-git-server/1-git-server.asc | 34 +++++++++++++++++++---------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/book/04-git-server/1-git-server.asc b/book/04-git-server/1-git-server.asc index cbc6c27c9..1a0d3bfdb 100644 --- a/book/04-git-server/1-git-server.asc +++ b/book/04-git-server/1-git-server.asc @@ -1,5 +1,6 @@ == Git on the Server +(((serving repositories))) At this point, you should be able to do most of the day-to-day tasks for which you’ll be using Git. However, in order to do any collaboration in Git, you’ll need to have a remote Git repository. Although you can technically push changes to and pull changes from individuals’ repositories, doing so is discouraged because you can fairly easily confuse what they’re working on if you’re not careful. @@ -25,6 +26,7 @@ Here we’ll discuss what they are and in what basic circumstances you would wan ==== Local Protocol +(((protocols, local))) The most basic is the _Local protocol_, in which the remote repository is in another directory on disk. This is often used if everyone on your team has access to a shared filesystem such as an NFS mount, or in the less likely case that everyone logs in to the same computer. The latter wouldn’t be ideal, because all your code repository instances would reside on the same computer, making a catastrophic loss much more likely. @@ -90,6 +92,7 @@ We'll cover the newer ``smart'' HTTP protocol first. ===== Smart HTTP +(((protocols, smart HTTP))) The ``smart'' HTTP protocol operates very similarly to the SSH or Git protocols but runs over standard HTTP/S ports and can use various HTTP authentication mechanisms, meaning it's often easier on the user than something like SSH, since you can use things like username/password basic authentication rather than having to set up SSH keys. It has probably become the most popular way to use Git now, since it can be set up to both serve anonymously like the `git://` protocol, and can also be pushed over with authentication like the SSH protocol. Instead of having to set up different URLs for these things, you can now use a single URL for both. If you try to push and the repository requires authentication (which it normally should), the server can prompt for a username and password. The same goes for read access. @@ -98,6 +101,7 @@ In fact, for services like GitHub, the URL you use to view the repository online ===== Dumb HTTP +(((protocols, dumb HTTP))) If the server does not respond with a Git HTTP smart service, the Git client will try to fall back to the simpler ``dumb'' HTTP protocol. The Dumb protocol expects the bare Git repository to be served like normal files from the web server. The beauty of the Dumb HTTP protocol is the simplicity of setting it up. @@ -114,7 +118,7 @@ $ mv hooks/post-update.sample hooks/post-update $ chmod a+x hooks/post-update ---- -That’s all. +That’s all.(((hooks, post-update))) The `post-update` hook that comes with Git by default runs the appropriate command (`git update-server-info`) to make HTTP fetching and cloning work properly. This command is run when you push to this repository (over SSH perhaps); then, other people can clone via something like @@ -150,6 +154,7 @@ If you're using HTTP for authenticated pushing, providing your credentials is so ==== The SSH Protocol +(((protocols, SSH))) A common transport protocol for Git when self-hosting is over SSH. This is because SSH access to servers is already set up in most places – and if it isn’t, it’s easy to do. SSH is also an authenticated network protocol; and because it’s ubiquitous, it’s generally easy to set up and use. @@ -186,6 +191,7 @@ If you want to allow anonymous read-only access to your projects and also want t ==== The Git Protocol +(((protocols, git))) Next is the Git protocol. This is a special daemon that comes packaged with Git; it listens on a dedicated port (9418) that provides a service similar to the SSH protocol, but with absolutely no authentication. In order for a repository to be served over the Git protocol, you must create the `git-export-daemon-ok` file – the daemon won’t serve a repository without that file in it – but other than that there is no security. @@ -222,7 +228,7 @@ Actually setting up a production server within your infrastructure will certainl In order to initially set up any Git server, you have to export an existing repository into a new bare repository – a repository that doesn’t contain a working directory. This is generally straightforward to do. -In order to clone your repository to create a new bare repository, you run the clone command with the `--bare` option. +In order to clone your repository to create a new bare repository, you run the clone command with the `--bare` option.(((git commands, clone, bare))) By convention, bare repository directories end in `.git`, like so: [source,shell] @@ -264,7 +270,7 @@ $ git clone user@git.example.com:/opt/git/my_project.git If a user SSHs into a server and has write access to the `/opt/git/my_project.git` directory, they will also automatically have push access. -Git will automatically add group write permissions to a repository properly if you run the `git init` command with the `--shared` option. +Git will automatically add group write permissions to a repository properly if you run the `git init` command with the `--shared` option.(((git commands, init, bare))) [source,shell] ---- @@ -291,6 +297,7 @@ If you want some repositories to be read-only to certain users and read/write to ===== SSH Access +(((serving repositories, SSH))) If you have a server to which all your developers already have SSH access, it’s generally easiest to set up your first repository there, because you have to do almost no work (as we covered in the last section). If you want more complex access control type permissions on your repositories, you can handle them with the normal filesystem permissions of the operating system your server runs. @@ -311,6 +318,7 @@ As long as each user can get shell access on the machine, any SSH authentication [[_generate_ssh_key]] === Generating Your SSH Public Key +(((SSH keys))) That being said, many Git servers authenticate using SSH public keys. In order to provide a public key, each user in your system must generate one if they don’t already have one. This process is similar across all operating systems. @@ -402,7 +410,7 @@ $ cat /tmp/id_rsa.josie.pub >> ~/.ssh/authorized_keys $ cat /tmp/id_rsa.jessica.pub >> ~/.ssh/authorized_keys ---- -Now, you can set up an empty repository for them by running `git init` with the `--bare` option, which initializes the repository without a working directory: +Now, you can set up an empty repository for them by running `git init` with the `--bare` option, which initializes the repository without a working directory:(((git commands, init, bare))) [source,shell] ---- @@ -460,7 +468,7 @@ At the bottom, you should find a line that looks something like this: git:x:1000:1000::/home/git:/bin/sh ---- -Change `/bin/sh` to `/usr/bin/git-shell` (or run `which git-shell` to see where it’s installed). +Change `/bin/sh` to `/usr/bin/git-shell` (or run `which git-shell` to see where it’s installed).(((git-shell))) The line should look something like this: [source,shell] @@ -482,17 +490,18 @@ Connection to gitserver closed. Now Git network commands will still work just fine but the users won't be able to get a shell. As the output states, you can also set up a directory in the ``git'' user's home directory that customizes the `git-shell` command a bit. For instance, you can restrict the Git commands that the server will accept or you can customize the message that users see if they try to SSH in like that. -Run `git help shell` for more information on customizing the shell. +Run `git help shell` for more information on customizing the shell.(((git commands, help))) === Git Daemon +(((serving repositories, git protocol))) Next we'll set up a daemon serving repositories over the ``Git'' protocol. This is common choice for fast, unauthenticated access to your Git data. Remember that since it's not an authenticated service, anything you serve over this protocol is public within it's network. If you’re running this on a server outside your firewall, it should only be used for projects that are publicly visible to the world. If the server you’re running it on is inside your firewall, you might use it for projects that a large number of people or computers (continuous integration or build servers) have read-only access to, when you don’t want to have to add an SSH key for each. In any case, the Git protocol is relatively easy to set up. -Basically, you need to run this command in a daemonized manner: +Basically, you need to run this command in a daemonized manner:(((git commands, daemon))) [source,shell] ---- @@ -550,12 +559,13 @@ The presence of that file tells Git that it’s OK to serve this project without === Smart HTTP +(((serving repositories, HTTP))) We now have authenticated access though SSH and unauthenticated access through `git://`, but there is also a protocol that can do both at the same time. -Setting up Smart HTTP is basically just enabling a CGI script that is provided with Git called `git-http-backend` on the server.((git, http-backend)) +Setting up Smart HTTP is basically just enabling a CGI script that is provided with Git called `git-http-backend` on the server.((git commands, http-backend)) This CGI will read the path and headers sent by a `git fetch` or `git push` to an HTTP URL and determine if the client can communicate over HTTP (which is true for any client since version 1.6.6). If the CGI sees that the client is smart, it will communicate smartly with it, otherwise it will fall back to the dumb behavior (so it is backward compatible for reads with older clients). -Let's walk though a very basic setup. We'll set this up with Apache as the CGI server. If you don't have Apache setup, you can do so on a Linux box with something like this: +Let's walk though a very basic setup. We'll set this up with Apache as the CGI server. If you don't have Apache setup, you can do so on a Linux box with something like this:(((Apache))) [source,shell] ---- @@ -619,6 +629,7 @@ For more information on configuring authentication in Apache, check out the Apac === GitWeb +(((serving repositories, GitWeb)))(((GitWeb))) Now that you have basic read/write and read-only access to your project, you may want to set up a simple web-based visualizer. Git comes with a CGI script called GitWeb that is sometimes used for this. @@ -629,7 +640,7 @@ image::images/git-instaweb.png[The GitWeb web-based user interface.] If you want to check out what GitWeb would look like for your project, Git comes with a command to fire up a temporary instance if you have a lightweight server on your system like `lighttpd` or `webrick`. On Linux machines, `lighttpd` is often installed, so you may be able to get it to run by typing `git instaweb` in your project directory. If you’re running a Mac, Leopard comes preinstalled with Ruby, so `webrick` may be your best bet. -To start `instaweb` with a non-lighttpd handler, you can run it with the `--httpd` option. +To start `instaweb` with a non-lighttpd handler, you can run it with the `--httpd` option.(((git commands, instaweb))) [source,shell] ---- @@ -690,6 +701,7 @@ At this point, you should be able to visit `http://gitserver/` to view your repo === GitLab +(((serving repositories, GitLab)))(((GitLab))) GitWeb is pretty simplistic though. If you're looking for a more modern, fully featured Git server, there are some several open source solutions out there that you can install instead. As GitLab is one of the more popular ones, we'll cover installing and using it as an example. @@ -701,7 +713,7 @@ GitLab is a database-backed web application, so its installation is a bit more i Fortunately, this process is very well-documented and supported. There are a few methods you can pursue to install GitLab. -To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab[], and tweak the configuration to match your particular environment. +To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab[], and tweak the configuration to match your particular environment.(((bitnami))) One nice touch Bitnami has included is the login screen (accessed by typing alt-→); it tells you the IP address and default username and password for the installed GitLab. [[bitnami]] From 841a53ef237cbcc01652e9bf473de21542c35e4f Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Fri, 11 Jul 2014 19:02:07 -0700 Subject: [PATCH 09/11] Fix broken index entry? --- book/04-git-server/1-git-server.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/04-git-server/1-git-server.asc b/book/04-git-server/1-git-server.asc index 1a0d3bfdb..73ce60355 100644 --- a/book/04-git-server/1-git-server.asc +++ b/book/04-git-server/1-git-server.asc @@ -561,7 +561,7 @@ The presence of that file tells Git that it’s OK to serve this project without (((serving repositories, HTTP))) We now have authenticated access though SSH and unauthenticated access through `git://`, but there is also a protocol that can do both at the same time. -Setting up Smart HTTP is basically just enabling a CGI script that is provided with Git called `git-http-backend` on the server.((git commands, http-backend)) +Setting up Smart HTTP is basically just enabling a CGI script that is provided with Git called `git-http-backend` on the server.((git commands, "http-backend")) This CGI will read the path and headers sent by a `git fetch` or `git push` to an HTTP URL and determine if the client can communicate over HTTP (which is true for any client since version 1.6.6). If the CGI sees that the client is smart, it will communicate smartly with it, otherwise it will fall back to the dumb behavior (so it is backward compatible for reads with older clients). From 0d904ed2635bda0b279624d6d845e24407e5827d Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Fri, 11 Jul 2014 19:16:02 -0700 Subject: [PATCH 10/11] Tweak index entries --- book/01-introduction/1-introduction.asc | 2 +- book/02-git-basics/1-git-basics.asc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/01-introduction/1-introduction.asc b/book/01-introduction/1-introduction.asc index 0477ba165..a808aa90b 100644 --- a/book/01-introduction/1-introduction.asc +++ b/book/01-introduction/1-introduction.asc @@ -84,7 +84,7 @@ Some of the goals of the new system were as follows: * Simple design * Strong support for non-linear development (thousands of parallel branches) * Fully distributed -* Able to handle large projects like the Linux kernel efficiently (speed and data size)(((Linux))) +* Able to handle large projects like the Linux kernel efficiently (speed and data size) Since its birth in 2005, Git has evolved and matured to be easy to use and yet retain these initial qualities. It’s incredibly fast, it’s very efficient with large projects, and it has an incredible branching system for non-linear development (See <<_git_branching>>). diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index bafbca3ba..1ebc3ef0a 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -1152,7 +1152,7 @@ So, `git fetch origin` fetches any new work that has been pushed to that server It’s important to note that the `git fetch` command pulls the data to your local repository – it doesn’t automatically merge it with any of your work or modify what you’re currently working on. You have to merge it manually into your work when you’re ready. -If you have a branch set up to track a remote branch (see the next section and <<_git_branching>> for more information), you can use the `git pull` command to automatically fetch and then merge a remote branch into your current branch. +If you have a branch set up to track a remote branch (see the next section and <<_git_branching>> for more information), you can use the `git pull` command to automatically fetch and then merge a remote branch into your current branch.(((git commands, pull))) This may be an easier or more comfortable workflow for you; and by default, the `git clone` command automatically sets up your local master branch to track the remote master branch (or whatever the default branch is called) on the server you cloned from. Running `git pull` generally fetches data from the server you originally cloned from and automatically tries to merge it into the code you’re currently working on. From b62ddbec65f1d459ddecbbd18557ca5ff3b2e625 Mon Sep 17 00:00:00 2001 From: Ben Straub Date: Fri, 11 Jul 2014 19:23:47 -0700 Subject: [PATCH 11/11] Index entries should point to text, not TOC entry Also, clean up some duplicate or unhelpful entries for git commands. --- book/02-git-basics/1-git-basics.asc | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc index 1ebc3ef0a..395bdf682 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/book/02-git-basics/1-git-basics.asc @@ -104,7 +104,7 @@ For now, that branch is always ``master'', which is the default; you won’t wor <<_git_branching>> will go over branches and references in detail. Let’s say you add a new file to your project, a simple README file. -If the file didn’t exist before, and you run `git status`, you see your untracked file like so:(((git commands, status))) +If the file didn’t exist before, and you run `git status`, you see your untracked file like so: [source,shell] ---- @@ -194,7 +194,7 @@ Changes to be committed: Both files are staged and will go into your next commit. At this point, suppose you remember one little change that you want to make in `benchmarks.rb` before you commit it. You open it again and make that change, and you’re ready to commit. -However, let’s run `git status` one more time:(((git commands, status))) +However, let’s run `git status` one more time: [source,shell] ---- @@ -299,7 +299,7 @@ GitHub maintains a fairly comprehensive list of good `.gitignore` file examples ==== Viewing Your Staged and Unstaged Changes -If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.(((git commands, status)))(((git commands, diff))) +If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.(((git commands, diff))) We’ll cover `git diff` in more detail later, but you’ll probably use it most often to answer these two questions: What have you changed but not yet staged? And what have you staged that you are about to commit? Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were. @@ -441,7 +441,7 @@ $ git commit ---- Doing so launches your editor of choice. -(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).(((editor, changing default))) +(This is set by your shell’s `$EDITOR` environment variable – usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).(((editor, changing default)))(((git commands, config))) The editor displays the following text (this example is a Vim screen): @@ -484,8 +484,9 @@ Remember that the commit records the snapshot you set up in your staging area. Anything you didn’t stage is still sitting there modified; you can do another commit to add it to your history. Every time you perform a commit, you’re recording a snapshot of your project that you can revert to or compare to later. -==== Skipping the Staging Area(((staging area, skipping))) +==== Skipping the Staging Area +(((staging area, skipping))) Although it can be amazingly useful for crafting commits exactly how you want them, the staging area is sometimes a bit more complex than you need in your workflow. If you want to skip the staging area, Git provides a simple shortcut. Adding the `-a` option to the `git commit` command makes Git automatically stage every file that is already tracked before doing the commit, letting you skip the `git add` part: @@ -508,8 +509,9 @@ $ git commit -a -m 'added new benchmarks' Notice how you don’t have to run `git add` on the ``benchmarks.rb'' file in this case before you commit. -==== Removing Files(((files, removing))) +==== Removing Files +(((files, removing))) To remove a file from Git, you have to remove it from your tracked files (more accurately, remove it from your staging area) and then commit. The `git rm` command does that, and also removes the file from your working directory so you don’t see it as an untracked file the next time around. @@ -577,8 +579,9 @@ $ git rm \*~ This command removes all files that end with `~`. -==== Moving Files(((files, moving))) +==== Moving Files +(((files, moving))) Unlike many other VCS systems, Git doesn’t explicitly track file movement. If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file. However, Git is pretty smart about figuring that out after the fact – we’ll deal with detecting file movement a bit later. @@ -1252,8 +1255,9 @@ $ git remote origin ---- -=== Tagging (((tags))) +=== Tagging +(((tags))) Like most VCSs, Git has the ability to tag specific points in history as being important. Typically people use this functionality to mark release points (v1.0, and so on). In this section, you’ll learn how to list the available tags, how to create new tags, and what the different types of tags are. @@ -1301,8 +1305,9 @@ Annotated tags, however, are stored as full objects in the Git database. They’re checksummed; contain the tagger name, e-mail, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG). It’s generally recommended that you create annotated tags so you can have all this information; but if you want a temporary tag or for some reason don’t want to keep the other information, lightweight tags are available too. -==== Annotated Tags (((tags, annotated))) +==== Annotated Tags +(((tags, annotated))) Creating an annotated tag in Git is simple. The easiest way is to specify `-a` when you run the `tag` command:(((git commands, tag))) @@ -1338,8 +1343,9 @@ Date: Mon Mar 17 21:52:11 2008 -0700 That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information. -==== Lightweight Tags (((tags, lightweight))) +==== Lightweight Tags +(((tags, lightweight))) Another way to tag commits is with a lightweight tag. This is basically the commit checksum stored in a file – no other information is kept. To create a lightweight tag, don’t supply the `-a`, `-s`, or `-m` option: @@ -1458,8 +1464,9 @@ To git@github.com:schacon/simplegit.git Now, when someone else clones or pulls from your repository, they will get all your tags as well. -=== Git Aliases(((aliases))) +=== Git Aliases +(((aliases))) Before we finish this chapter on basic Git, there's just one little tip that can make your Git experience simpler, easier, and more familiar: aliases. We won’t refer to them or assume you’ve used them later in the book, but you should probably know how to use them.