diff --git a/C-git-commands.asc b/C-git-commands.asc index 65077c192..9d0027f83 100644 --- a/C-git-commands.asc +++ b/C-git-commands.asc @@ -41,7 +41,7 @@ In <> we showed how to set up smudge an Finally, basically the entirety of <> is dedicated to the command. -[[_core_editor]] +[[ch_core_editor]] ==== git config core.editor commands Accompanying the configuration instructions in <>, many editors can be set as follows: @@ -97,7 +97,7 @@ To take a directory and turn it into a new Git repository so you can start versi We first introduce this in <>, where we show creating a brand new repository to start working with. -We talk briefly about how you can change the default branch name from ``master'' in <>. +We talk briefly about how you can change the default branch name from "`master`" in <>. We use this command to create an empty bare repository for a server in <>. @@ -127,7 +127,7 @@ For the basic workflow of staging content and committing it to your history, the ==== git add -The `git add` command adds content from the working directory into the staging area (or ``index'') for the next commit. +The `git add` command adds content from the working directory into the staging area (or "`index`") for the next commit. When the `git commit` command is run, by default it only looks at this staging area, so `git add` is used to craft what exactly you would like your next commit snapshot to look like. This command is an incredibly important command in Git and is mentioned or used dozens of times in this book. @@ -367,7 +367,7 @@ This can help you be very specific about what work you wish to share. ==== git remote The `git remote` command is a management tool for your record of remote repositories. -It allows you to save long URLs as short handles, such as ``origin'' so you don't have to type them out all the time. +It allows you to save long URLs as short handles, such as "`origin`" so you don't have to type them out all the time. You can have several of these and the `git remote` command is used to add, change and delete them. This command is covered in detail in <>, including listing, adding, removing and renaming them. @@ -543,7 +543,7 @@ If you're administering a Git repository or need to fix something in a big way, ==== git gc -The `git gc` command runs ``garbage collection'' on your repository, removing unnecessary files in your database and packing up the remaining files into a more efficient format. +The `git gc` command runs "`garbage collection`" on your repository, removing unnecessary files in your database and packing up the remaining files into a more efficient format. This command normally runs in the background for you, though you can manually run it if you wish. We go over some examples of this in <>. diff --git a/Gemfile b/Gemfile index de8b738a6..041300665 100644 --- a/Gemfile +++ b/Gemfile @@ -1,15 +1,15 @@ source 'https://rubygems.org' -gem 'rake' -gem 'asciidoctor', '1.5.6.2' +gem 'rake', ' 13.0.1' +gem 'asciidoctor', '2.0.10' -gem 'json' -gem 'awesome_print' +gem 'json', '2.3.1' +gem 'awesome_print', '1.8.0' -gem 'asciidoctor-epub3', '~> 1.5.0.alpha.9' -gem 'asciidoctor-pdf', '~> 1.5.0.beta.8' +gem 'asciidoctor-epub3', '1.5.0.alpha.18' +gem 'asciidoctor-pdf', '1.5.3' -gem 'coderay' -gem 'pygments.rb' -gem 'thread_safe' -gem 'epubcheck' +gem 'coderay', '1.1.3' +gem 'pygments.rb', '1.2.1' +gem 'thread_safe', '0.3.6' +gem 'epubcheck', '3.0.1' diff --git a/TRANSLATING.md b/TRANSLATING.md index 2620528c1..65515479d 100644 --- a/TRANSLATING.md +++ b/TRANSLATING.md @@ -59,7 +59,7 @@ If there is no project for your language, you can start your own translation. Base your work on the second edition of the book, available [here](https://github.com/progit/progit2). To do so: 1. Pick the correct [ISO 639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language. 1. Create a [GitHub organization](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch), for example: `progit2-[your code]` on GitHub. - 1. Create a project ``progit2``. + 1. Create a project "`progit2"`. 1. Copy the structure of progit/progit2 (this project) in your project and start translating. ### Updating the status of your translation diff --git a/book/01-introduction/sections/about-version-control.asc b/book/01-introduction/sections/about-version-control.asc index 630ee2345..c4859fced 100644 --- a/book/01-introduction/sections/about-version-control.asc +++ b/book/01-introduction/sections/about-version-control.asc @@ -1,7 +1,7 @@ === About Version Control (((version control))) -What is ``version control'', and why should you care? +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. diff --git a/book/01-introduction/sections/first-time-setup.asc b/book/01-introduction/sections/first-time-setup.asc index 0f70a3dc3..4f5e29ebb 100644 --- a/book/01-introduction/sections/first-time-setup.asc +++ b/book/01-introduction/sections/first-time-setup.asc @@ -75,7 +75,7 @@ $ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -m [NOTE] ==== Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix-based systems like Linux and macOS or a Windows system. -If you are using another editor, or a 32-bit version, please find specific instructions for how to set up your favorite editor with Git in <>. +If you are using another editor, or a 32-bit version, please find specific instructions for how to set up your favorite editor with Git in <>. ==== [WARNING] diff --git a/book/01-introduction/sections/help.asc b/book/01-introduction/sections/help.asc index d5331d835..731ea5ff4 100644 --- a/book/01-introduction/sections/help.asc +++ b/book/01-introduction/sections/help.asc @@ -21,7 +21,7 @@ These commands are nice because you can access them anywhere, even offline. If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server, which can be found at https://freenode.net[]. These channels are regularly filled with hundreds of people who are all very knowledgeable about Git and are often willing to help.(((IRC))) -In addition, if you don't need the full-blown manpage help, but just need a quick refresher on the available options for a Git command, you can ask for the more concise ``help'' output with the `-h` option, as in: +In addition, if you don't need the full-blown manpage help, but just need a quick refresher on the available options for a Git command, you can ask for the more concise "`help`" output with the `-h` option, as in: [source,console] ---- diff --git a/book/01-introduction/sections/what-is-git.asc b/book/01-introduction/sections/what-is-git.asc index 8ad20e862..23769b95b 100644 --- a/book/01-introduction/sections/what-is-git.asc +++ b/book/01-introduction/sections/what-is-git.asc @@ -92,7 +92,7 @@ The working tree is a single checkout of one version of the project. These files are pulled out of the compressed database in the Git directory and placed on disk for you to use or modify. The staging area is a file, generally contained in your Git directory, that stores information about what will go into your next commit. -Its technical name in Git parlance is the ``index'', but the phrase ``staging area'' works just as well. +Its technical name in Git parlance is the "`index`", but the phrase "`staging area`" works just as well. The Git directory is where Git stores the metadata and object database for your project. This is the most important part of Git, and it is what is copied when you _clone_ a repository from another computer. diff --git a/book/02-git-basics/sections/recording-changes.asc b/book/02-git-basics/sections/recording-changes.asc index eb53cd8e0..9187bdaba 100644 --- a/book/02-git-basics/sections/recording-changes.asc +++ b/book/02-git-basics/sections/recording-changes.asc @@ -53,7 +53,7 @@ Untracked files: nothing added to commit but untracked files present (use "git add" to track) ---- -You can see that your new `README` file is untracked, because it's under the ``Untracked files'' heading in your status output. +You can see that your new `README` file is untracked, because it's under the "`Untracked files`" heading in your status output. Untracked basically means that Git sees a file you didn't have in the previous snapshot (commit); Git won't start including it in your commit snapshots until you explicitly tell it to do so. It does this so you don't accidentally begin including generated binary files or other files that you did not mean to include. You do want to start including `README`, so let's start tracking the file. @@ -83,7 +83,7 @@ Changes to be committed: ---- -You can tell that it's staged because it's under the ``Changes to be committed'' heading. +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 subsequent historical snapshot. You may recall that when you ran `git init` earlier, you then ran `git add ` -- 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. @@ -111,10 +111,10 @@ Changes not staged for commit: ---- -The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' -- which means that a file that is tracked has been modified in the working directory but not yet staged. +The `CONTRIBUTING.md` file appears under a section named "`Changes 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 precisely this content to the next commit'' rather than ``add this file to the project''.(((git commands, add))) +It may be helpful to think of it more as "`add precisely 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 `CONTRIBUTING.md` file, and then run `git status` again: [source,console] @@ -212,7 +212,7 @@ $ cat .gitignore *~ ---- -The first line tells Git to ignore any files ending in ``.o'' or ``.a'' -- object and archive files that may be the product of building your code. +The first line tells Git to ignore any files ending in "`.o`" or "`.a`" -- object and archive files that may be the product of building your code. The second line tells Git to ignore all files whose names end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files. You may also include a log, tmp, or pid directory; automatically generated documentation; and so on. Setting up a `.gitignore` file for your new repository before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository. @@ -509,7 +509,7 @@ This is convenient, but be careful; sometimes this flag will cause you to includ 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. -If you simply remove the file from your working directory, it shows up under the ``Changes not staged for commit'' (that is, _unstaged_) area of your `git status` output: +If you simply remove the file from your working directory, it shows up under the "`Changes not staged for commit`" (that is, _unstaged_) area of your `git status` output: [source,console] ---- diff --git a/book/02-git-basics/sections/remotes.asc b/book/02-git-basics/sections/remotes.asc index 4165b0a79..b785ce4bb 100644 --- a/book/02-git-basics/sections/remotes.asc +++ b/book/02-git-basics/sections/remotes.asc @@ -11,8 +11,8 @@ In this section, we'll cover some of these remote-management skills. [NOTE] .Remote repositories can be on your local machine. ==== -It is entirely possible that you can be working with a ``remote'' repository that is, in fact, on the same host you are. -The word ``remote'' does not necessarily imply that the repository is somewhere else on the network or Internet, only that it is elsewhere. +It is entirely possible that you can be working with a "`remote`" repository that is, in fact, on the same host you are. +The word "`remote`" does not necessarily imply that the repository is somewhere else on the network or Internet, only that it is elsewhere. Working with such a remote repository would still involve all the standard pushing, pulling and fetching operations as with any other remote. ==== @@ -118,7 +118,7 @@ $ git fetch The command goes out to that remote project and pulls down all the data from that remote project that you don't have yet. After you do this, you should have references to all the branches from that remote, which you can merge in or inspect at any time. -If you clone a repository, the command automatically adds that remote repository under the name ``origin''. +If you clone a repository, the command automatically adds that remote repository under the name "`origin`". So, `git fetch origin` fetches any new work that has been pushed to that server since you cloned (or last fetched from) it. It's important to note that the `git fetch` command only downloads 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. diff --git a/book/02-git-basics/sections/tagging.asc b/book/02-git-basics/sections/tagging.asc index bb67429ac..34604c573 100644 --- a/book/02-git-basics/sections/tagging.asc +++ b/book/02-git-basics/sections/tagging.asc @@ -147,7 +147,7 @@ a6b4c97498bd301d84096da251c98a07c7723e65 Create write support 8a5cbc430f1a9c3d00faaeffd07798508422908a Update readme ---- -Now, suppose you forgot to tag the project at v1.2, which was at the ``Update rakefile'' commit. +Now, suppose you forgot to tag the project at v1.2, which was at the "`Update rakefile`" commit. You can add it after the fact. To tag that commit, you specify the commit checksum (or part of it) at the end of the command: @@ -258,7 +258,7 @@ $ git push origin --delete ==== Checking out Tags -If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in ``detached HEAD'' state, which has some ill side effects: +If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in "`detached HEAD`" state, which has some ill side effects: [source,console] ---- @@ -287,7 +287,7 @@ Previous HEAD position was 99ada87... Merge pull request #89 from schacon/append HEAD is now at df3f601... Add atlas.json and cover image ---- -In ``detached HEAD'' state, if you make changes and then create a commit, the tag will stay the same, but your new commit won't belong to any branch and will be unreachable, except by the exact commit hash. +In "`detached HEAD`" state, if you make changes and then create a commit, the tag will stay the same, but your new commit won't belong to any branch and will be unreachable, except by the exact commit hash. Thus, if you need to make changes -- say you're fixing a bug on an older version, for instance -- you will generally want to create a branch: [source,console] diff --git a/book/02-git-basics/sections/undoing.asc b/book/02-git-basics/sections/undoing.asc index 957cefd7a..7d101ff8f 100644 --- a/book/02-git-basics/sections/undoing.asc +++ b/book/02-git-basics/sections/undoing.asc @@ -36,7 +36,7 @@ You end up with a single commit -- the second commit replaces the results of the It's important to understand that when you're amending your last commit, you're not so much fixing it as _replacing_ it entirely with a new, improved commit that pushes the old commit out of the way and puts the new commit in its place. Effectively, it's as if the previous commit never happened, and it won't show up in your repository history. -The obvious value to amending commits is to make minor improvements to your last commit, without cluttering your repository history with commit messages of the form, ``Oops, forgot to add a file'' or ``Darn, fixing a typo in last commit''. +The obvious value to amending commits is to make minor improvements to your last commit, without cluttering your repository history with commit messages of the form, "`Oops, forgot to add a file`" or "`Darn, fixing a typo in last commit`". ==== [NOTE] @@ -67,7 +67,7 @@ Changes to be committed: modified: CONTRIBUTING.md ---- -Right below the ``Changes to be committed'' text, it says use `git reset HEAD ...` to unstage. +Right below the "`Changes to be committed`" text, it says use `git reset HEAD ...` to unstage. So, let's use that advice to unstage the `CONTRIBUTING.md` file: [source,console] diff --git a/book/02-git-basics/sections/viewing-history.asc b/book/02-git-basics/sections/viewing-history.asc index 72a5117ea..cfddeead0 100644 --- a/book/02-git-basics/sections/viewing-history.asc +++ b/book/02-git-basics/sections/viewing-history.asc @@ -4,7 +4,7 @@ After you have created several commits, or if you have cloned a repository with an existing commit history, you'll probably want to look back to see what has happened. The most basic and powerful tool to do this is the `git log` command. -These examples use a very simple project called ``simplegit''. +These examples use a very simple project called "`simplegit`". To get the project, run: [source,console] @@ -218,7 +218,7 @@ Those are only some simple output-formatting options to `git log` -- there are m | `--name-only` | Show the list of files modified after the commit information. | `--name-status` | Show the list of files affected with added/modified/deleted information as well. | `--abbrev-commit` | Show only the first few characters of the SHA-1 checksum instead of all 40. -| `--relative-date` | Display the date in a relative format (for example, ``2 weeks ago'') instead of using the full date format. +| `--relative-date` | Display the date in a relative format (for example, "`2 weeks ago`") instead of using the full date format. | `--graph` | Display an ASCII graph of the branch and merge history beside the log output. | `--pretty` | Show commits in an alternate format. Option values include oneline, short, full, fuller, and format (where you specify your own format). | `--oneline` | Shorthand for `--pretty=oneline --abbrev-commit` used together. @@ -252,7 +252,7 @@ of the `--grep` patterns; however, adding the `--all-match` option further limit just those commits that match _all_ `--grep` patterns. ==== -Another really helpful filter is the `-S` option (colloquially referred to as Git's ``pickaxe'' option), which takes a string and shows only those commits that changed the number of occurrences of that string. +Another really helpful filter is the `-S` option (colloquially referred to as Git's "`pickaxe`" option), which takes a string and shows only those commits that changed the number of occurrences of that string. For instance, if you wanted to find the last commit that added or removed a reference to a specific function, you could call: [source,console] diff --git a/book/03-git-branching/sections/basic-branching-and-merging.asc b/book/03-git-branching/sections/basic-branching-and-merging.asc index 49f446146..a1aa01795 100644 --- a/book/03-git-branching/sections/basic-branching-and-merging.asc +++ b/book/03-git-branching/sections/basic-branching-and-merging.asc @@ -104,9 +104,9 @@ Fast-forward 1 file changed, 2 insertions(+) ---- -You'll notice the phrase ``fast-forward'' in that merge. +You'll notice the phrase "`fast-forward`" in that merge. Because the commit `C4` pointed to by the branch `hotfix` you merged in was directly ahead of the commit `C2` you're on, Git simply moves the pointer forward. -To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together -- this is called a ``fast-forward.'' +To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together -- this is called a "`fast-forward.`" Your change is now in the snapshot of the commit pointed to by the `master` branch, and you can deploy the fix. @@ -265,7 +265,7 @@ Normal merge conflict for 'index.html': Hit return to start merge resolution tool (opendiff): ---- -If you want to use a merge tool other than the default (Git chose `opendiff` in this case because the command was run on a Mac), you can see all the supported tools listed at the top after ``one of the following tools.'' +If you want to use a merge tool other than the default (Git chose `opendiff` in this case because the command was run on a Mac), you can see all the supported tools listed at the top after "`one of the following tools.`" Just type the name of the tool you'd rather use. [NOTE] diff --git a/book/03-git-branching/sections/nutshell.asc b/book/03-git-branching/sections/nutshell.asc index 3818d939a..e4e983a1d 100644 --- a/book/03-git-branching/sections/nutshell.asc +++ b/book/03-git-branching/sections/nutshell.asc @@ -37,7 +37,7 @@ Every time you commit, the `master` branch pointer moves forward automatically. [NOTE] ==== -The ``master'' branch in Git is not a special branch.(((master))) +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. ==== diff --git a/book/03-git-branching/sections/rebasing.asc b/book/03-git-branching/sections/rebasing.asc index 8856f7d05..dfc18dc50 100644 --- a/book/03-git-branching/sections/rebasing.asc +++ b/book/03-git-branching/sections/rebasing.asc @@ -80,7 +80,7 @@ You can take the changes on `client` that aren't on `server` (`C8` and `C9`) and $ git rebase --onto master server client ---- -This basically says, ``Take the `client` branch, figure out the patches since it diverged from the `server` branch, and replay these patches in the `client` branch as if it was based directly off the `master` branch instead.'' +This basically says, "`Take the `client` branch, figure out the patches since it diverged from the `server` branch, and replay these patches in the `client` branch as if it was based directly off the `master` branch instead.`" It's a bit complex, but the result is pretty cool. .Rebasing a topic branch off another topic branch @@ -184,7 +184,7 @@ If you *do* find yourself in a situation like this, Git has some further magic t If someone on your team force pushes changes that overwrite work that you've based work on, your challenge is to figure out what is yours and what they've rewritten. It turns out that in addition to the commit SHA-1 checksum, Git also calculates a checksum that is based just on the patch introduced with the commit. -This is called a ``patch-id''. +This is called a "`patch-id`". If you pull down work that was rewritten and rebase it on top of the new commits from your partner, Git can often successfully figure out what is uniquely yours and apply them back on top of the new branch. diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc index 4062663c9..6885f322b 100644 --- a/book/03-git-branching/sections/remote-branches.asc +++ b/book/03-git-branching/sections/remote-branches.asc @@ -20,10 +20,10 @@ If you clone from this, Git's `clone` command automatically names it `origin` fo Git also gives you your own local `master` branch starting at the same place as origin's `master` branch, so you have something to work from. [NOTE] -.``origin'' is not special +."`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`. +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))) ==== @@ -37,7 +37,7 @@ Also, as long as you stay out of contact with your `origin` server, your `origin image::images/remote-branches-2.png[Local and remote work can diverge] To synchronize your work with a given remote, you run a `git fetch ` command (in our case, `git fetch origin`). -This command looks up which server ``origin'' is (in this case, it's `git.ourcompany.com`), fetches any data from it that you don't yet have, and updates your local database, moving your `origin/master` pointer to its new, more up-to-date position. +This command looks up which server "`origin`" is (in this case, it's `git.ourcompany.com`), fetches any data from it that you don't yet have, and updates your local database, moving your `origin/master` pointer to its new, more up-to-date position. .`git fetch` updates your remote-tracking branches image::images/remote-branches-3.png[`git fetch` updates your remote references] @@ -80,9 +80,9 @@ To https://github.com/schacon/simplegit ---- This is a bit of a shortcut. -Git automatically expands the `serverfix` branchname out to `refs/heads/serverfix:refs/heads/serverfix`, which means, ``Take my `serverfix` local branch and push it to update the remote's `serverfix` branch.'' +Git automatically expands the `serverfix` branchname out to `refs/heads/serverfix:refs/heads/serverfix`, which means, "`Take my `serverfix` local branch and push it to update the remote's `serverfix` branch.`" We'll go over the `refs/heads/` part in detail in <>, but you can generally leave it off. -You can also do `git push origin serverfix:serverfix`, which does the same thing -- it says, ``Take my serverfix and make it the remote's serverfix.'' +You can also do `git push origin serverfix:serverfix`, which does the same thing -- it says, "`Take my serverfix and make it the remote's serverfix.`" You can use this format to push a local branch into a remote branch that is named differently. If you didn't want it to be called `serverfix` on the remote, you could instead run `git push origin serverfix:awesomebranch` to push your local `serverfix` branch to the `awesomebranch` branch on the remote project. @@ -92,7 +92,7 @@ If you didn't want it to be called `serverfix` on the remote, you could instead If you're using an HTTPS URL to push over, the Git server will ask you for your username and password for authentication. By default it will prompt you on the terminal for this information so the server can tell if you're allowed to push. -If you don't want to type it every single time you push, you can set up a ``credential cache''. +If you don't want to type it every single time you push, you can set up a "`credential cache`". The simplest is just to keep it in memory for a few minutes, which you can easily set up by running `git config --global credential.helper cache`. For more information on the various credential caching options available, see <>. @@ -130,7 +130,7 @@ This gives you a local branch that you can work on that starts where `origin/ser ==== Tracking Branches (((branches, tracking)))(((branches, upstream))) -Checking out a local branch from a remote-tracking branch automatically creates what is called a ``tracking branch'' (and the branch it tracks is called an ``upstream branch''). +Checking out a local branch from a remote-tracking branch automatically creates what is called a "`tracking branch`" (and the branch it tracks is called 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 pull`, Git automatically knows which server to fetch from and which branch to merge in. @@ -194,7 +194,7 @@ $ git branch -vv testing 5ea463a Try something new ---- -So here we can see that our `iss53` branch is tracking `origin/iss53` and is ``ahead'' by two, meaning that we have two commits locally that are not pushed to the server. +So here we can see that our `iss53` branch is tracking `origin/iss53` and is "`ahead`" by two, meaning that we have two commits locally that are not pushed to the server. We can also see that our `master` branch is tracking `origin/master` and is up to date. Next we can see that our `serverfix` branch is tracking the `server-fix-good` branch on our `teamone` server and is ahead by three and behind by one, meaning that there is one commit on the server we haven't merged in yet and three commits locally that we haven't pushed. Finally we can see that our `testing` branch is not tracking any remote branch. diff --git a/book/03-git-branching/sections/workflows.asc b/book/03-git-branching/sections/workflows.asc index 0c2387016..b2063a827 100644 --- a/book/03-git-branching/sections/workflows.asc +++ b/book/03-git-branching/sections/workflows.asc @@ -22,8 +22,8 @@ image::images/lr-branches-1.png[A linear view of progressive-stability branching It's generally easier to think about them as work silos, where sets of commits graduate to a more stable silo when they're fully tested. [[lrbranch_b]] -.A ``silo'' view of progressive-stability branching -image::images/lr-branches-2.png[A ``silo'' view of progressive-stability branching] +.A "`silo`" view of progressive-stability branching +image::images/lr-branches-2.png[A "`silo`" view of progressive-stability branching] You can keep doing this for several levels of stability. Some larger projects also have a `proposed` or `pu` (proposed updates) branch that has integrated branches that may not be ready to go into the `next` or `master` branch. diff --git a/book/04-git-server/sections/git-daemon.asc b/book/04-git-server/sections/git-daemon.asc index 1bc425770..1fe172375 100644 --- a/book/04-git-server/sections/git-daemon.asc +++ b/book/04-git-server/sections/git-daemon.asc @@ -1,7 +1,7 @@ === Git Daemon (((serving repositories, git protocol))) -Next we'll set up a daemon serving repositories using the ``Git'' protocol. +Next we'll set up a daemon serving repositories using the "`Git`" protocol. This is a common choice for fast, unauthenticated access to your Git data. Remember that since this is not an authenticated service, anything you serve over this protocol is public within its network. diff --git a/book/04-git-server/sections/gitlab.asc b/book/04-git-server/sections/gitlab.asc index b88024cb7..d81f60b46 100644 --- a/book/04-git-server/sections/gitlab.asc +++ b/book/04-git-server/sections/gitlab.asc @@ -26,11 +26,11 @@ For more information read the https://gitlab.com/gitlab-org/gitlab-foss/-/blob/m GitLab's administration interface is accessed over the web. Simply point your browser to the hostname or IP address where GitLab is installed, and log in as the admin user. The default username is `admin@local.host`, and the default password is `5iveL!fe` (which you must change right away). -After you've logged in, click the ``Admin area'' icon in the menu at the top right. +After you've logged in, click the "`Admin area`" icon in the menu at the top right. [[gitlab_menu]] -.The ``Admin area'' item in the GitLab menu -image::images/gitlab-menu.png[The ``Admin area'' item in the GitLab menu] +.The "`Admin area`" item in the GitLab menu +image::images/gitlab-menu.png[The `"Admin area`" item in the GitLab menu] ===== Users @@ -44,9 +44,9 @@ If the user +jane+ had a project named +project+, that project's url would be `h image::images/gitlab-users.png[The GitLab user administration screen] You can remove a user account in two ways: -``Blocking'' a user prevents them from logging into the GitLab instance, but all of the data under that user's namespace will be preserved, and commits signed with that user's email address will still link back to their profile. +"`Blocking`" a user prevents them from logging into the GitLab instance, but all of the data under that user's namespace will be preserved, and commits signed with that user's email address will still link back to their profile. -``Destroying'' a user, on the other hand, completely removes them from the database and filesystem. +"`Destroying`" a user, on the other hand, completely removes them from the database and filesystem. All projects and data in their namespace is removed, and any groups they own will also be removed. This is obviously a much more permanent and destructive action, and you will rarely need it. @@ -61,7 +61,7 @@ Each group has a project namespace (the same way that users do), so if the group image::images/gitlab-groups.png[The GitLab group administration screen] Each group is associated with a number of users, each of which has a level of permissions for the group's projects and the group itself. -These range from ``Guest'' (issues and chat only) to ``Owner'' (full control of the group, its members, and its projects). +These range from "`Guest`" (issues and chat only) to "`Owner`" (full control of the group, its members, and its projects). The types of permissions are too numerous to list here, but GitLab has a helpful link on the administration screen. ===== Projects @@ -84,10 +84,10 @@ This is a great way to connect your Git repositories and GitLab instance to the ==== Basic Usage The first thing you'll want to do with GitLab is create a new project. -You can do this by clicking on the ``+'' icon on the toolbar. +You can do this by clicking on the "`+`" icon on the toolbar. You'll be asked for the project's name, which namespace it should belong to, and what its visibility level should be. Most of what you specify here isn't permanent, and can be changed later through the settings interface. -Click ``Create Project'', and you're done. +Click "`Create Project`", and you're done. Once the project exists, you'll probably want to connect it with a local Git repository. Each project is accessible over HTTPS or SSH, either of which can be used to configure a Git remote. @@ -112,13 +112,13 @@ Each project's home page shows recent activity, and links along the top will lea ==== Working Together The simplest way of working together on a GitLab project is by giving each user direct push access to the Git repository. -You can add a user to a project by going to the ``Members'' section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>). -By giving a user an access level of ``Developer'' or above, that user can push commits and branches directly to the repository. +You can add a user to a project by going to the "`Members`" section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>). +By giving a user an access level of "`Developer`" or above, that user can push commits and branches directly to the repository. Another, more decoupled way of collaboration is by using merge requests. This feature enables any user that can see a project to contribute to it in a controlled way. Users with direct access can simply create a branch, push commits to it, and open a merge request from their branch back into `master` or any other branch. -Users who don't have push permissions for a repository can ``fork'' it to create their own copy, push commits to _their_ copy, and open a merge request from their fork back to the main project. +Users who don't have push permissions for a repository can "`fork`" it to create their own copy, push commits to _their_ copy, and open a merge request from their fork back to the main project. This model allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users. Merge requests and issues are the main units of long-lived discussion in GitLab. diff --git a/book/04-git-server/sections/protocols.asc b/book/04-git-server/sections/protocols.asc index 99d232a72..be0f46e68 100644 --- a/book/04-git-server/sections/protocols.asc +++ b/book/04-git-server/sections/protocols.asc @@ -61,7 +61,7 @@ A local repository is fast only if you have fast access to the data. A repository on NFS is often slower than the repository over SSH on the same server, allowing Git to run off local disks on each system. Finally, this protocol does not protect the repository against accidental damage. -Every user has full shell access to the ``remote'' directory, and there is nothing preventing them from changing or removing internal Git files and corrupting the repository. +Every user has full shell access to the "`remote`" directory, and there is nothing preventing them from changing or removing internal Git files and corrupting the repository. ==== The HTTP Protocols diff --git a/book/04-git-server/sections/smart-http.asc b/book/04-git-server/sections/smart-http.asc index 60bdd3097..3e6cc8771 100644 --- a/book/04-git-server/sections/smart-http.asc +++ b/book/04-git-server/sections/smart-http.asc @@ -50,7 +50,7 @@ Finally you'll want to tell Apache to allow requests to `git-http-backend` and m ---- That will require you to create a `.htpasswd` file containing the passwords of all the valid users. -Here is an example of adding a ``schacon'' user to the file: +Here is an example of adding a "`schacon`" user to the file: [source,console] ---- diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc index 7eec6edd6..7ca870032 100644 --- a/book/05-distributed-git/sections/contributing.asc +++ b/book/05-distributed-git/sections/contributing.asc @@ -103,7 +103,7 @@ In short, do as we say, not as we do. (((contributing, private small team))) The simplest setup you're likely to encounter is a private project with one or two other developers. -``Private,'' in this context, means closed-source -- not accessible to the outside world. +"`Private,`" in this context, means closed-source -- not accessible to the outside world. You and the other developers all have push access to the repository. In this environment, you can follow a workflow similar to what you might do when using Subversion or another centralized system. @@ -330,7 +330,7 @@ image::images/small-team-flow.png[General sequence of events for a simple multip In this next scenario, you'll look at contributor roles in a larger private group. You'll learn how to work in an environment where small groups collaborate on features, after which those team-based contributions are integrated by another party. -Let's say that John and Jessica are working together on one feature (call this ``featureA''), while Jessica and a third developer, Josie, are working on a second (say, ``featureB''). +Let's say that John and Jessica are working together on one feature (call this "`featureA`"), while Jessica and a third developer, Josie, are working on a second (say, "`featureB`"). In this case, the company is using a type of integration-manager workflow where the work of the individual groups is integrated only by certain engineers, and the `master` branch of the main repo can be updated only by those engineers. In this scenario, all work is done in team-based branches and pulled together by the integrators later. @@ -391,7 +391,7 @@ Jessica's repository now looks like this: .Jessica's initial commit history image::images/managed-team-1.png[Jessica's initial commit history] -She's ready to push her work, but gets an email from Josie that a branch with some initial ``featureB'' work on it was already pushed to the server as the `featureBee` branch. +She's ready to push her work, but gets an email from Josie that a branch with some initial "`featureB`" work on it was already pushed to the server as the `featureBee` branch. Jessica needs to merge those changes with her own before she can push her work to the server. Jessica first fetches Josie's changes with `git fetch`: @@ -414,7 +414,7 @@ Merge made by the 'recursive' strategy. 1 files changed, 4 insertions(+), 0 deletions(-) ---- -At this point, Jessica wants to push all of this merged ``featureB'' work back to the server, but she doesn't want to simply push her own `featureB` branch. +At this point, Jessica wants to push all of this merged "`featureB`" work back to the server, but she doesn't want to simply push her own `featureB` branch. Rather, since Josie has already started an upstream `featureBee` branch, Jessica wants to push to _that_ branch, which she does with: [source,console] @@ -525,7 +525,7 @@ $ git commit You may want to use `rebase -i` to squash your work down to a single commit, or rearrange the work in the commits to make the patch easier for the maintainer to review -- see <> for more information about interactive rebasing. ==== -When your branch work is finished and you're ready to contribute it back to the maintainers, go to the original project page and click the ``Fork'' button, creating your own writable fork of the project. +When your branch work is finished and you're ready to contribute it back to the maintainers, go to the original project page and click the "`Fork`" button, creating your own writable fork of the project. You then need to add this repository URL as a new remote of your local repository; in this example, let's call it `myfork`: [source,console] @@ -547,7 +547,7 @@ $ git push -u myfork featureA (((git commands, request-pull))) Once your work has been pushed to your fork of the repository, you need to notify the maintainers of the original project that you have work you'd like them to merge. -This is often called a _pull request_, and you typically generate such a request either via the website -- GitHub has its own ``Pull Request'' mechanism that we'll go over in <> -- or you can run the `git request-pull` command and email the subsequent output to the project maintainer manually. +This is often called a _pull request_, and you typically generate such a request either via the website -- GitHub has its own "`Pull Request`" mechanism that we'll go over in <> -- or you can run the `git request-pull` command and email the subsequent output to the project maintainer manually. The `git request-pull` command takes the base branch into which you want your topic branch pulled and the Git repository URL you want them to pull from, and produces a summary of all the changes you're asking to be pulled. For instance, if Jessica wants to send John a pull request, and she's done two commits on the topic branch she just pushed, she can run this: @@ -706,7 +706,7 @@ You can also edit these patch files to add more information for the email list t If you add text between the `---` line and the beginning of the patch (the `diff --git` line), the developers can read it, but that content is ignored by the patching process. To email this to a mailing list, you can either paste the file into your email program or send it via a command-line program. -Pasting the text often causes formatting issues, especially with ``smarter'' clients that don't preserve newlines and other whitespace appropriately. +Pasting the text often causes formatting issues, especially with "`smarter`" clients that don't preserve newlines and other whitespace appropriately. Luckily, Git provides a tool to help you send properly formatted patches via IMAP, which may be easier for you. We'll demonstrate how to send a patch via Gmail, which happens to be the email agent we know best; you can read detailed instructions for a number of mail programs at the end of the aforementioned `Documentation/SubmittingPatches` file in the Git source code. diff --git a/book/05-distributed-git/sections/distributed-workflows.asc b/book/05-distributed-git/sections/distributed-workflows.asc index 3ee8a99eb..657692c3c 100644 --- a/book/05-distributed-git/sections/distributed-workflows.asc +++ b/book/05-distributed-git/sections/distributed-workflows.asc @@ -38,7 +38,7 @@ With Git's branching model, it's possible for hundreds of developers to successf (((workflows, integration manager))) Because Git allows you to have multiple remote repositories, it's possible to have a workflow where each developer has write access to their own public repository and read access to everyone else's. -This scenario often includes a canonical repository that represents the ``official'' project. +This scenario often includes a canonical repository that represents the "`official`" project. To contribute to that project, you create your own public clone of the project and push your changes to it. Then, you can send a request to the maintainer of the main project to pull in your changes. The maintainer can then add your repository as a remote, test your changes locally, merge them into their branch, and push back to their repository. diff --git a/book/05-distributed-git/sections/maintaining.asc b/book/05-distributed-git/sections/maintaining.asc index 016b25916..b5762aaa6 100644 --- a/book/05-distributed-git/sections/maintaining.asc +++ b/book/05-distributed-git/sections/maintaining.asc @@ -49,7 +49,7 @@ $ git apply /tmp/patch-ruby-client.patch This modifies the files in your working directory. It's almost identical to running a `patch -p1` command to apply the patch, although it's more paranoid and accepts fewer fuzzy matches than patch. It also handles file adds, deletes, and renames if they're described in the `git diff` format, which `patch` won't do. -Finally, `git apply` is an ``apply all or abort all'' model where either everything is applied or nothing is, whereas `patch` can partially apply patchfiles, leaving your working directory in a weird state. +Finally, `git apply` is an "`apply all or abort all`" model where either everything is applied or nothing is, whereas `patch` can partially apply patchfiles, leaving your working directory in a weird state. `git apply` is overall much more conservative than `patch`. It won't create a commit for you -- after running it, you must stage and commit the changes introduced manually. @@ -405,9 +405,9 @@ Now you can remove your topic branch and drop the commits you didn't want to pul ===== Rerere (((git commands, rerere)))(((rerere))) -If you're doing lots of merging and rebasing, or you're maintaining a long-lived topic branch, Git has a feature called ``rerere'' that can help. +If you're doing lots of merging and rebasing, or you're maintaining a long-lived topic branch, Git has a feature called "`rerere`" that can help. -Rerere stands for ``reuse recorded resolution'' -- it's a way of shortcutting manual conflict resolution. +Rerere stands for "`reuse recorded resolution`" -- it's a way of shortcutting manual conflict resolution. When rerere is enabled, Git will keep a set of pre- and post-images from successful merges, and if it notices that there's a conflict that looks exactly like one you've already fixed, it'll just use the fix from last time, without bothering you with it. This feature comes in two parts: a configuration setting and a command. diff --git a/book/06-github/sections/1-setting-up-account.asc b/book/06-github/sections/1-setting-up-account.asc index 6596aef9b..6380420de 100644 --- a/book/06-github/sections/1-setting-up-account.asc +++ b/book/06-github/sections/1-setting-up-account.asc @@ -2,7 +2,7 @@ (((GitHub, user accounts))) The first thing you need to do is set up a free user account. -Simply visit https://github.com[], choose a user name that isn't already taken, provide an email address and a password, and click the big green ``Sign up for GitHub'' button. +Simply visit https://github.com[], choose a user name that isn't already taken, provide an email address and a password, and click the big green "`Sign up for GitHub`" button. .The GitHub sign-up form image::images/signup.png[The GitHub sign-up form] @@ -32,15 +32,15 @@ If you'd like to use SSH remotes, you'll need to configure a public key. If you don't already have one, see <>. Open up your account settings using the link at the top-right of the window: -.The ``Account settings'' link -image::images/account-settings.png[The ``Account settings'' link] +.The "`Account settings`" link +image::images/account-settings.png[The "`Account settings`" link] -Then select the ``SSH keys'' section along the left-hand side. +Then select the "`SSH keys`" section along the left-hand side. -.The ``SSH keys'' link -image::images/ssh-keys.png[The ``SSH keys'' link] +.The "`SSH keys`" link. +image::images/ssh-keys.png[The "`SSH keys`" link] -From there, click the "`Add an SSH key`" button, give your key a name, paste the contents of your `~/.ssh/id_rsa.pub` (or whatever you named it) public-key file into the text area, and click ``Add key''. +From there, click the "`Add an SSH key`" button, give your key a name, paste the contents of your `~/.ssh/id_rsa.pub` (or whatever you named it) public-key file into the text area, and click "`Add key`". [NOTE] ==== @@ -52,10 +52,10 @@ You can name each of your keys (e.g. "My Laptop" or "Work Account") so that if y ==== Your Avatar Next, if you wish, you can replace the avatar that is generated for you with an image of your choosing. -First go to the ``Profile'' tab (above the SSH Keys tab) and click ``Upload new picture''. +First go to the "`Profile`" tab (above the SSH Keys tab) and click "`Upload new picture`". -.The ``Profile'' link -image::images/your-profile.png[The ``Profile'' link] +.The "`Profile`" link +image::images/your-profile.png[The "`Profile`" link] We'll choose a copy of the Git logo that is on our hard drive and then we get a chance to crop it. @@ -83,7 +83,7 @@ If GitHub sees any of these in commit messages in any repository on the site, it ==== Two Factor Authentication -Finally, for extra security, you should definitely set up Two-factor Authentication or ``2FA''. +Finally, for extra security, you should definitely set up Two-factor Authentication or "`2FA`". Two-factor Authentication is an authentication mechanism that is becoming more and more popular recently to mitigate the risk of your account being compromised if your password is stolen somehow. Turning it on will make GitHub ask you for two different methods of authentication, so that if one of them is compromised, an attacker will not be able to access your account. @@ -92,6 +92,6 @@ You can find the Two-factor Authentication setup under the Security tab of your .2FA in the Security Tab image::images/2fa-1.png[2FA in the Security Tab] -If you click on the ``Set up two-factor authentication'' button, it will take you to a configuration page where you can choose to use a phone app to generate your secondary code (a ``time based one-time password''), or you can have GitHub send you a code via SMS each time you need to log in. +If you click on the "`Set up two-factor authentication`" button, it will take you to a configuration page where you can choose to use a phone app to generate your secondary code (a "`time based one-time password`"), or you can have GitHub send you a code via SMS each time you need to log in. After you choose which method you prefer and follow the instructions for setting up 2FA, your account will then be a little more secure and you will have to provide a code in addition to your password whenever you log into GitHub. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index e39d5d4eb..67f1e2e67 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -5,23 +5,23 @@ Now that our account is set up, let's walk through some details that could be us ==== Forking Projects (((forking))) -If you want to contribute to an existing project to which you don't have push access, you can ``fork'' the project. -When you ``fork'' a project, GitHub will make a copy of the project that is entirely yours; it lives in your namespace, and you can push to it. +If you want to contribute to an existing project to which you don't have push access, you can "`fork`" the project. +When you "`fork`" a project, GitHub will make a copy of the project that is entirely yours; it lives in your namespace, and you can push to it. [NOTE] ==== -Historically, the term ``fork'' has been somewhat negative in context, meaning that someone took an open source project in a different direction, sometimes creating a competing project and splitting the contributors. -In GitHub, a ``fork'' is simply the same project in your own namespace, allowing you to make changes to a project publicly as a way to contribute in a more open manner. +Historically, the term "`fork`" has been somewhat negative in context, meaning that someone took an open source project in a different direction, sometimes creating a competing project and splitting the contributors. +In GitHub, a "`fork`" is simply the same project in your own namespace, allowing you to make changes to a project publicly as a way to contribute in a more open manner. ==== This way, projects don't have to worry about adding users as collaborators to give them push access. People can fork a project, push to it, and contribute their changes back to the original repository by creating what's called a Pull Request, which we'll cover next. This opens up a discussion thread with code review, and the owner and the contributor can then communicate about the change until the owner is happy with it, at which point the owner can merge it in. -To fork a project, visit the project page and click the ``Fork'' button at the top-right of the page. +To fork a project, visit the project page and click the "`Fork`" button at the top-right of the page. -.The ``Fork'' button -image::images/forkbutton.png[The ``Fork'' button] +.The "`Fork`" button +image::images/forkbutton.png[The "`Fork`" button] After a few seconds, you'll be taken to your new project page, with your own writeable copy of the code. @@ -68,7 +68,7 @@ We think it's much nicer to wait 3 seconds instead of 1 in between each state ch So let's improve the program and submit it back to the project as a proposed change. First, we click the 'Fork' button as mentioned earlier to get our own copy of the project. -Our user name here is ``tonychacon'' so our copy of this project is at `https://github.com/tonychacon/blink` and that's where we can edit it. +Our user name here is "`tonychacon`" so our copy of this project is at `https://github.com/tonychacon/blink` and that's where we can edit it. We will clone it locally, create a topic branch, make the code change and finally push that change back up to GitHub. [source,console] @@ -123,7 +123,7 @@ To https://github.com/tonychacon/blink Now if we go back to our fork on GitHub, we can see that GitHub noticed that we pushed a new topic branch up and presents us with a big green button to check out our changes and open a Pull Request to the original project. -You can alternatively go to the ``Branches'' page at `https://github.com///branches` to locate your branch and open a new Pull Request from there. +You can alternatively go to the "`Branches`" page at `https://github.com///branches` to locate your branch and open a new Pull Request from there. .Pull Request button image::images/blink-02-pr.png[Pull Request button] @@ -132,7 +132,7 @@ image::images/blink-02-pr.png[Pull Request button] If we click that green button, we'll see a screen that asks us to give our Pull Request a title and description. It is almost always worthwhile to put some effort into this, since a good description helps the owner of the original project determine what you were trying to do, whether your proposed changes are correct, and whether accepting the changes would improve the original project. -We also see a list of the commits in our topic branch that are ``ahead'' of the `master` branch (in this case, just the one) and a unified diff of all the changes that will be made should this branch get merged by the project owner. +We also see a list of the commits in our topic branch that are "`ahead`" of the `master` branch (in this case, just the one) and a unified diff of all the changes that will be made should this branch get merged by the project owner. .Pull Request creation page image::images/blink-03-pull-request-open.png[Pull Request creation] @@ -182,13 +182,13 @@ Adding commits to an existing Pull Request doesn't trigger a notification, so on .Pull Request final image::images/blink-06-final.png[PR final] -An interesting thing to notice is that if you click on the ``Files Changed'' tab on this Pull Request, you'll get the ``unified'' diff -- that is, the total aggregate difference that would be introduced to your main branch if this topic branch was merged in. +An interesting thing to notice is that if you click on the "`Files Changed`" tab on this Pull Request, you'll get the "`unified`" diff -- that is, the total aggregate difference that would be introduced to your main branch if this topic branch was merged in. In `git diff` terms, it basically automatically shows you `git diff master...` for the branch this Pull Request is based on. See <> for more about this type of diff. The other thing you'll notice is that GitHub checks to see if the Pull Request merges cleanly and provides a button to do the merge for you on the server. This button only shows up if you have write access to the repository and a trivial merge is possible. -If you click it GitHub will perform a ``non-fast-forward'' merge, meaning that even if the merge *could* be a fast-forward, it will still create a merge commit. +If you click it GitHub will perform a "`non-fast-forward`" merge, meaning that even if the merge *could* be a fast-forward, it will still create a merge commit. If you would prefer, you can simply pull the branch down and merge it locally. If you merge this branch into the `master` branch and push it to GitHub, the Pull Request will automatically be closed. @@ -220,7 +220,7 @@ When code is proposed with a Pull Request and the maintainers or community sugge For instance, if you go back and look again at <<_pr_final>>, you'll notice that the contributor did not rebase his commit and send another Pull Request. Instead they added new commits and pushed them to the existing branch. This way if you go back and look at this Pull Request in the future, you can easily find all of the context of why decisions were made. -Pushing the ``Merge'' button on the site purposefully creates a merge commit that references the Pull Request so that it's easy to go back and research the original conversation if necessary. +Pushing the "`Merge`" button on the site purposefully creates a merge commit that references the Pull Request so that it's easy to go back and research the original conversation if necessary. ===== Keeping up with Upstream @@ -241,7 +241,7 @@ What matters is the history and the final merge, so rebasing isn't getting you m If you want to merge in the target branch to make your Pull Request mergeable, you would add the original repository as a new remote, fetch from it, merge the main branch of that repository into your topic branch, fix any issues and finally push it back up to the same branch you opened the Pull Request on. -For example, let's say that in the ``tonychacon'' example we were using before, the original author made a change that would create a conflict in the Pull Request. +For example, let's say that in the "`tonychacon`" example we were using before, the original author made a change that would create a conflict in the Pull Request. Let's go through those steps. [source,console] @@ -298,13 +298,13 @@ Instead, push the rebased branch to a new branch on GitHub and open a brand new ===== References -Your next question may be ``How do I reference the old Pull Request?''. +Your next question may be "`How do I reference the old Pull Request?`". It turns out there are many, many ways to reference other things almost anywhere you can write in GitHub. Let's start with how to cross-reference another Pull Request or an Issue. All Pull Requests and Issues are assigned numbers and they are unique within the project. -For example, you can't have Pull Request #3 _and_ Issue #3. -If you want to reference any Pull Request or Issue from any other one, you can simply put `#` in any comment or description. +For example, you can't have Pull Request +#3+ _and_ Issue +#3+. +If you want to reference any Pull Request or Issue from any other one, you can simply put `+#+` in any comment or description. You can also be more specific if the Issue or Pull request lives somewhere else; write `username#` if you're referring to an Issue or Pull Request in a fork of the repository you're in, or `username/repo#` to reference something in another repository. Let's look at an example. @@ -339,7 +339,7 @@ Again, you can reference commits in forks or other repositories in the same way ==== GitHub Flavored Markdown Linking to other Issues is just the beginning of interesting things you can do with almost any text box on GitHub. -In Issue and Pull Request descriptions, comments, code comments and more, you can use what is called ``GitHub Flavored Markdown''. +In Issue and Pull Request descriptions, comments, code comments and more, you can use what is called "`GitHub Flavored Markdown`". Markdown is like writing in plain text but which is rendered richly. See <<_example_markdown>> for an example of how comments or text can be written and then rendered using Markdown. @@ -392,7 +392,7 @@ You can also add code snippets to comments. This is especially useful if you want to present something that you _could_ try to do before actually implementing it as a commit on your branch. This is also often used to add example code of what is not working or what this Pull Request could implement. -To add a snippet of code you have to ``fence'' it in backticks. +To add a snippet of code you have to "`fence`" it in backticks. [source,text] ---- @@ -484,7 +484,7 @@ In addition to adding Markdown image links to comments, which can be difficult t .Drag and drop images to upload them and auto-embed them image::images/markdown-08-drag-drop.png[Drag and drop images] -If you look at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. +If you look at <<_md_drag>>, you can see a small "`Parsed as Markdown`" hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. [[_fetch_and_push_on_different_repositories]] diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index cc7637e1a..8767ec31e 100644 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -6,22 +6,22 @@ Now that we're comfortable contributing to a project, let's look at the other si ==== Creating a New Repository Let's create a new repository to share our project code with. -Start by clicking the ``New repository'' button on the right-hand side of the dashboard, or from the `+` button in the top toolbar next to your username as seen in <<_new_repo_dropdown>>. +Start by clicking the "`New repository`" button on the right-hand side of the dashboard, or from the `+` button in the top toolbar next to your username as seen in <<_new_repo_dropdown>>. -.The ``Your repositories'' area -image::images/newrepo.png[The ``Your repositories'' area] +.The "`Your repositories`" area +image::images/newrepo.png[The "`Your repositories`" area] [[_new_repo_dropdown]] -.The ``New repository'' dropdown -image::images/new-repo.png[The ``new repository'' dropdown] +.The "`New repository`" dropdown +image::images/new-repo.png[The "`new repository`" dropdown] -This takes you to the ``new repository'' form: +This takes you to the "`new repository`" form: -.The ``new repository'' form -image::images/newrepoform.png[The ``new repository'' form] +.The "`new repository`" form +image::images/newrepoform.png[The "`new repository`" form] All you really have to do here is provide a project name; the rest of the fields are completely optional. -For now, just click the ``Create Repository'' button, and boom – you have a new repository on GitHub, named `/`. +For now, just click the "`Create Repository`" button, and boom – you have a new repository on GitHub, named `/`. Since you have no code there yet, GitHub will show you instructions for how to create a brand-new Git repository, or connect an existing Git project. We won't belabor this here; if you need a refresher, check out <>. @@ -39,19 +39,19 @@ The HTTPS one is also exactly the same URL they would paste into a browser to vi ==== Adding Collaborators -If you're working with other people who you want to give commit access to, you need to add them as ``collaborators''. +If you're working with other people who you want to give commit access to, you need to add them as "`collaborators`". If Ben, Jeff, and Louise all sign up for accounts on GitHub, and you want to give them push access to your repository, you can add them to your project. -Doing so will give them ``push'' access, which means they have both read and write access to the project and Git repository. +Doing so will give them "`push`" access, which means they have both read and write access to the project and Git repository. -Click the ``Settings'' link at the bottom of the right-hand sidebar. +Click the "`Settings`" link at the bottom of the right-hand sidebar. .The repository settings link image::images/reposettingslink.png[The repository settings link] -Then select ``Collaborators'' from the menu on the left-hand side. -Then, just type a username into the box, and click ``Add collaborator.'' +Then select "`Collaborators`" from the menu on the left-hand side. +Then, just type a username into the box, and click "`Add collaborator.`" You can repeat this as many times as you like to grant access to everyone you like. -If you need to revoke access, just click the ``X'' on the right-hand side of their row. +If you need to revoke access, just click the "`X`" on the right-hand side of their row. .Repository collaborators image::images/collaborators.png[The repository collaborators box] @@ -63,7 +63,7 @@ Now that you have a project with some code in it and maybe even a few collaborat Pull Requests can either come from a branch in a fork of your repository or they can come from another branch in the same repository. The only difference is that the ones in a fork are often from people where you can't push to their branch and they can't push to yours, whereas with internal Pull Requests generally both parties can access the branch. -For these examples, let's assume you are ``tonychacon'' and you've created a new Arduino code project named ``fade''. +For these examples, let's assume you are "`tonychacon`" and you've created a new Arduino code project named "`fade`". [[_email_notifications]] ===== Email Notifications @@ -105,8 +105,8 @@ image::images/maint-03-email-resp.png[Email response] Once the code is in a place you like and want to merge it in, you can either pull the code down and merge it locally, either with the `git pull ` syntax we saw earlier, or by adding the fork as a remote and fetching and merging. -If the merge is trivial, you can also just hit the ``Merge'' button on the GitHub site. -This will do a ``non-fast-forward'' merge, creating a merge commit even if a fast-forward merge was possible. +If the merge is trivial, you can also just hit the "`Merge`" button on the GitHub site. +This will do a "`non-fast-forward`" merge, creating a merge commit even if a fast-forward merge was possible. This means that no matter what, every time you hit the merge button, a merge commit is created. As you can see in <<_merge_button>>, GitHub gives you all of this information if you click the hint link. @@ -125,10 +125,10 @@ This is a bit of an advanced trick and we'll go over the details of this a bit m GitHub actually advertises the Pull Request branches for a repository as sort of pseudo-branches on the server. By default you don't get them when you clone, but they are there in an obscured way and you can access them pretty easily. -To demonstrate this, we're going to use a low-level command (often referred to as a ``plumbing'' command, which we'll read about more in <>) called `ls-remote`. +To demonstrate this, we're going to use a low-level command (often referred to as a "`plumbing`" command, which we'll read about more in <>) called `ls-remote`. This command is generally not used in day-to-day Git operations but it's useful to show us what references are present on the server. -If we run this command against the ``blink'' repository we were using earlier, we will get a list of all the branches and tags and other references in the repository. +If we run this command against the "`blink`" repository we were using earlier, we will get a list of all the branches and tags and other references in the repository. [source,console] ---- @@ -161,7 +161,7 @@ From https://github.com/libgit2/libgit2 * branch refs/pull/958/head -> FETCH_HEAD ---- -This tells Git, ``Connect to the `origin` remote, and download the ref named `refs/pull/958/head`.'' +This tells Git, "`Connect to the `origin` remote, and download the ref named `refs/pull/958/head`.`" Git happily obeys, and downloads everything you need to construct that ref, and puts a pointer to the commit you want under `.git/FETCH_HEAD`. You can follow that up with `git merge FETCH_HEAD` into a branch you want to test it in, but that merge commit message looks a bit weird. Also, if you're reviewing a *lot* of pull requests, this gets tedious. @@ -177,7 +177,7 @@ It should look a bit like this: fetch = +refs/heads/*:refs/remotes/origin/* ---- -That line that begins with `fetch =` is a ``refspec.'' +That line that begins with `fetch =` is a "`refspec.`" It's a way of mapping names on the remote with names in your local `.git` directory. This particular one tells Git, "the things on the remote that are under `refs/heads` should go in my local repository under `refs/remotes/origin`." You can modify this section to add another refspec: @@ -190,7 +190,7 @@ You can modify this section to add another refspec: fetch = +refs/pull/*/head:refs/remotes/origin/pr/* ---- -That last line tells Git, ``All the refs that look like `refs/pull/123/head` should be stored locally like `refs/remotes/origin/pr/123`.'' +That last line tells Git, "`All the refs that look like `refs/pull/123/head` should be stored locally like `refs/remotes/origin/pr/123`.`" Now, if you save that file, and do a `git fetch`: [source,console] @@ -215,7 +215,7 @@ Switched to a new branch 'pr/2' ---- The eagle-eyed among you would note the `head` on the end of the remote portion of the refspec. -There's also a `refs/pull/#/merge` ref on the GitHub side, which represents the commit that would result if you push the ``merge'' button on the site. +There's also a `refs/pull/#/merge` ref on the GitHub side, which represents the commit that would result if you push the "`merge`" button on the site. This can allow you to test the merge before even hitting the button. @@ -227,7 +227,7 @@ In fact, you can even target another Pull Request. If you see a Pull Request that is moving in the right direction and you have an idea for a change that depends on it or you're not sure is a good idea, or you just don't have push access to the target branch, you can open a Pull Request directly to it. When you go to open a Pull Request, there is a box at the top of the page that specifies which branch you're requesting to pull to and which you're requesting to pull from. -If you hit the ``Edit'' button at the right of that box you can change not only the branches but also which fork. +If you hit the "`Edit`" button at the right of that box you can change not only the branches but also which fork. [[_pr_targets]] .Manually change the Pull Request target fork and branch @@ -250,22 +250,22 @@ Once you post a comment with a user mention, that user will be notified. This means that this can be a really effective way of pulling people into conversations rather than making them poll. Very often in Pull Requests on GitHub people will pull in other people on their teams or in their company to review an Issue or Pull Request. -If someone gets mentioned on a Pull Request or Issue, they will be ``subscribed'' to it and will continue getting notifications any time some activity occurs on it. +If someone gets mentioned on a Pull Request or Issue, they will be "`subscribed`" to it and will continue getting notifications any time some activity occurs on it. You will also be subscribed to something if you opened it, if you're watching the repository or if you comment on something. -If you no longer wish to receive notifications, there is an ``Unsubscribe'' button on the page you can click to stop receiving updates on it. +If you no longer wish to receive notifications, there is an "`Unsubscribe`" button on the page you can click to stop receiving updates on it. .Unsubscribe from an Issue or Pull Request image::images/maint-06-unsubscribe.png[Unsubscribe] ===== The Notifications Page -When we mention ``notifications'' here with respect to GitHub, we mean a specific way that GitHub tries to get in touch with you when events happen and there are a few different ways you can configure them. -If you go to the ``Notification center'' tab from the settings page, you can see some of the options you have. +When we mention "`notifications`" here with respect to GitHub, we mean a specific way that GitHub tries to get in touch with you when events happen and there are a few different ways you can configure them. +If you go to the "`Notification center`" tab from the settings page, you can see some of the options you have. .Notification center options image::images/maint-07-notifications.png[Notification center] -The two choices are to get notifications over ``Email'' and over ``Web'' and you can choose either, neither or both for when you actively participate in things and for activity on repositories you are watching. +The two choices are to get notifications over "`Email`" and over "`Web`" and you can choose either, neither or both for when you actively participate in things and for activity on repositories you are watching. ====== Web Notifications @@ -310,10 +310,10 @@ X-GitHub-Recipient-Address: tchacon@example.com There are a couple of interesting things here. If you want to highlight or re-route emails to this particular project or even Pull Request, the information in `Message-ID` gives you all the data in `///` format. -If this were an issue, for example, the `` field would have been ``issues'' rather than ``pull''. +If this were an issue, for example, the `` field would have been "`issues`" rather than "`pull`". -The `List-Post` and `List-Unsubscribe` fields mean that if you have a mail client that understands those, you can easily post to the list or ``Unsubscribe'' from the thread. -That would be essentially the same as clicking the ``mute'' button on the web version of the notification or ``Unsubscribe'' on the Issue or Pull Request page itself. +The `List-Post` and `List-Unsubscribe` fields mean that if you have a mail client that understands those, you can easily post to the list or "`Unsubscribe`" from the thread. +That would be essentially the same as clicking the "`mute`" button on the web version of the notification or "`Unsubscribe`" on the Issue or Pull Request page itself. It's also worth noting that if you have both email and web notifications enabled and you read the email version of the notification, the web version will be marked as read as well if you have images allowed in your mail client. @@ -356,7 +356,7 @@ Generally there are not a lot of administrative things you can do with a single ===== Changing the Default Branch -If you are using a branch other than ``master'' as your default branch that you want people to open Pull Requests on or see by default, you can change that in your repository's settings page under the ``Options'' tab. +If you are using a branch other than "`master`" as your default branch that you want people to open Pull Requests on or see by default, you can change that in your repository's settings page under the "`Options`" tab. [[_default_branch]] .Change the default branch for a project @@ -366,7 +366,7 @@ Simply change the default branch in the dropdown and that will be the default fo ===== Transferring a Project -If you would like to transfer a project to another user or an organization in GitHub, there is a ``Transfer ownership'' option at the bottom of the same ``Options'' tab of your repository settings page that allows you to do this. +If you would like to transfer a project to another user or an organization in GitHub, there is a "`Transfer ownership`" option at the bottom of the same "`Options`" tab of your repository settings page that allows you to do this. [[_transfer_project]] .Transfer a project to another GitHub user or Organization diff --git a/book/06-github/sections/4-managing-organization.asc b/book/06-github/sections/4-managing-organization.asc index e919b3344..35cc312d1 100644 --- a/book/06-github/sections/4-managing-organization.asc +++ b/book/06-github/sections/4-managing-organization.asc @@ -5,14 +5,14 @@ In addition to single-user accounts, GitHub has what are called Organizations. Like personal accounts, Organizational accounts have a namespace where all their projects exist, but many other things are different. These accounts represent a group of people with shared ownership of projects, and there are many tools to manage subgroups of those people. -Normally these accounts are used for Open Source groups (such as ``perl'' or ``rails'') or companies (such as ``google'' or ``twitter''). +Normally these accounts are used for Open Source groups (such as "`perl`" or "`rails`") or companies (such as "`google`" or "`twitter`"). ==== Organization Basics -An organization is pretty easy to create; just click on the ``+'' icon at the top-right of any GitHub page, and select ``New organization'' from the menu. +An organization is pretty easy to create; just click on the "`+`" icon at the top-right of any GitHub page, and select "`New organization`" from the menu. -.The ``New organization'' menu item -image::images/neworg.png[The ``New organization'' menu item] +.The "`New organization`" menu item +image::images/neworg.png[The "`New organization`" menu item] First you'll need to name your organization and provide an email address for a main point of contact for the group. Then you can invite other users to be co-owners of the account if you want to. @@ -22,7 +22,7 @@ Like personal accounts, organizations are free if everything you plan to store t As an owner in an organization, when you fork a repository, you'll have the choice of forking it to your organization's namespace. When you create new repositories you can create them either under your personal account or under any of the organizations that you are an owner in. -You also automatically ``watch'' any new repository created under these organizations. +You also automatically "`watch`" any new repository created under these organizations. Just like in <<_personal_avatar>>, you can upload an avatar for your organization to personalize it a bit. Also just like personal accounts, you have a landing page for the organization that lists all of your repositories and can be viewed by other people. @@ -46,7 +46,7 @@ image::images/orgs-01-page.png[The Organization page] To manage your Teams, you can click on the Teams sidebar on the right hand side of the page in <<_org_page>>. This will bring you to a page you can use to add members to the team, add repositories to the team or manage the settings and access control levels for the team. Each team can have read only, read/write or administrative access to the repositories. -You can change that level by clicking the ``Settings'' button in <<_team_page>>. +You can change that level by clicking the "`Settings`" button in <<_team_page>>. [[_team_page]] .The Team page diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 669e2d3c5..3ab8516ad 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -13,7 +13,7 @@ The Hooks and Services section of GitHub repository administration is the easies First we'll take a look at Services. Both the Hooks and Services integrations can be found in the Settings section of your repository, where we previously looked at adding Collaborators and changing the default branch of your project. -Under the ``Webhooks and Services'' tab you will see something like <<_services_hooks>>. +Under the "`Webhooks and Services`" tab you will see something like <<_services_hooks>>. [[_services_hooks]] .Services and Hooks configuration section @@ -22,13 +22,13 @@ image::images/scripting-01-services.png[Services and hooks] There are dozens of services you can choose from, most of them integrations into other commercial and open source systems. Most of them are for Continuous Integration services, bug and issue trackers, chat room systems and documentation systems. We'll walk through setting up a very simple one, the Email hook. -If you choose ``email'' from the ``Add Service'' dropdown, you'll get a configuration screen like <<_service_config>>. +If you choose "`email`" from the "`Add Service`" dropdown, you'll get a configuration screen like <<_service_config>>. [[_service_config]] .Email service configuration image::images/scripting-02-email-service.png[Email service] -In this case, if we hit the ``Add service'' button, the email address we specified will get an email every time someone pushes to the repository. +In this case, if we hit the "`Add service`" button, the email address we specified will get an email every time someone pushes to the repository. Services can listen for lots of different types of events, but most only listen for push events and then do something with that data. If there is a system you are using that you would like to integrate with GitHub, you should check here to see if there is an existing service integration available. @@ -42,7 +42,7 @@ You specify a URL and GitHub will post an HTTP payload to that URL on any event Generally the way this works is you can setup a small web service to listen for a GitHub hook payload and then do something with the data when it is received. -To enable a hook, you click the ``Add webhook'' button in <<_services_hooks>>. +To enable a hook, you click the "`Add webhook`" button in <<_services_hooks>>. This will bring you to a page that looks like <<_web_hook>>. [[_web_hook]] @@ -50,7 +50,7 @@ This will bring you to a page that looks like <<_web_hook>>. image::images/scripting-03-webhook.png[Web hook] The configuration for a web hook is pretty simple. -In most cases you simply enter a URL and a secret key and hit ``Add webhook''. +In most cases you simply enter a URL and a secret key and hit "`Add webhook`". There are a few options for which events you want GitHub to send you a payload for -- the default is to only get a payload for the `push` event, when someone pushes new code to any branch of your repository. Let's see a small example of a web service you may set up to handle a web hook. @@ -123,7 +123,7 @@ In this section we'll learn how to authenticate and connect to the API, how to c The most basic thing you can do is a simple GET request on an endpoint that doesn't require authentication. This could be a user or read-only information on an open source project. -For example, if we want to know more about a user named ``schacon'', we can run something like this: +For example, if we want to know more about a user named "`schacon`", we can run something like this: [source,javascript] ---- @@ -172,10 +172,10 @@ However, if you want to do an action on the website such as comment on an Issue There are several ways to authenticate. You can use basic authentication with just your username and password, but generally it's a better idea to use a personal access token. -You can generate this from the ``Applications'' tab of your settings page. +You can generate this from the "`Applications`" tab of your settings page. [[_access_token]] -.Generate your access token from the ``Applications'' tab of your settings page +.Generate your access token from the "`Applications`" tab of your settings page image::images/scripting-05-access-token.png[Access Token] It will ask you which scopes you want for this token and a description. @@ -279,8 +279,8 @@ end Hopefully this is fairly simple to follow. In this web hook handler we look through each commit that was just pushed, we look for the string 'Signed-off-by' in the commit message and finally we POST via HTTP to the `/repos///statuses/` API endpoint with the status. -In this case you can send a state ('success', 'failure', 'error'), a description of what happened, a target URL the user can go to for more information and a ``context'' in case there are multiple statuses for a single commit. -For example, a testing service may provide a status and a validation service like this may also provide a status -- the ``context'' field is how they're differentiated. +In this case you can send a state ('success', 'failure', 'error'), a description of what happened, a target URL the user can go to for more information and a "`context`" in case there are multiple statuses for a single commit. +For example, a testing service may provide a status and a validation service like this may also provide a status -- the "`context`" field is how they're differentiated. If someone opens a new Pull Request on GitHub and this hook is set up, you may see something like <<_commit_status>>. @@ -288,7 +288,7 @@ If someone opens a new Pull Request on GitHub and this hook is set up, you may s .Commit status via the API image::images/scripting-07-status.png[Commit status] -You can now see a little green check mark next to the commit that has a ``Signed-off-by'' string in the message and a red cross through the one where the author forgot to sign off. +You can now see a little green check mark next to the commit that has a "`Signed-off-by`" string in the message and a red cross through the one where the author forgot to sign off. You can also see that the Pull Request takes the status of the last commit on the branch and warns you if it is a failure. This is really useful if you're using this API for test results so you don't accidentally merge something where the last commit is failing tests. diff --git a/book/07-git-tools/git-credential-read-only b/book/07-git-tools/git-credential-read-only index b98833c4e..0e9147597 100755 --- a/book/07-git-tools/git-credential-read-only +++ b/book/07-git-tools/git-credential-read-only @@ -15,7 +15,7 @@ exit(0) unless File.exists? path known = {} # <3> while line = STDIN.gets - break if line.strip == '' + break if line.strip == `" k,v = line.strip.split '=', 2 known[k] = v end diff --git a/book/07-git-tools/sections/advanced-merging.asc b/book/07-git-tools/sections/advanced-merging.asc index 79fa865ac..e27cb0779 100644 --- a/book/07-git-tools/sections/advanced-merging.asc +++ b/book/07-git-tools/sections/advanced-merging.asc @@ -36,7 +36,7 @@ hello() ---- In our repository, we create a new branch named `whitespace` and proceed to change all the Unix line endings to DOS line endings, essentially changing every line of the file, but just with whitespace. -Then we change the line ``hello world'' to ``hello mundo''. +Then we change the line "`hello world`" to "`hello mundo`". [source,console] ---- @@ -168,8 +168,8 @@ Then we want to get copies of my version of the file, their version (from the br Then we want to fix up either their side or our side and re-try the merge again for just this single file. Getting the three file versions is actually pretty easy. -Git stores all of these versions in the index under ``stages'' which each have numbers associated with them. -Stage 1 is the common ancestor, stage 2 is your version and stage 3 is from the `MERGE_HEAD`, the version you're merging in (``theirs''). +Git stores all of these versions in the index under "`stages`" which each have numbers associated with them. +Stage 1 is the common ancestor, stage 2 is your version and stage 3 is from the `MERGE_HEAD`, the version you're merging in ("`theirs`"). You can extract a copy of each of these versions of the conflicted file with the `git show` command and a special syntax. @@ -362,7 +362,7 @@ This will re-checkout the file again and replace the merge conflict markers. This can be useful if you want to reset the markers and try to resolve them again. You can pass `--conflict` either `diff3` or `merge` (which is the default). -If you pass it `diff3`, Git will use a slightly different version of conflict markers, not only giving you the ``ours'' and ``theirs'' versions, but also the ``base'' version inline to give you more context. +If you pass it `diff3`, Git will use a slightly different version of conflict markers, not only giving you the "`ours`" and "`theirs`" versions, but also the "`base`" version inline to give you more context. [source,console] ---- @@ -406,7 +406,7 @@ Another useful tool when resolving merge conflicts is `git log`. This can help you get context on what may have contributed to the conflicts. Reviewing a little bit of history to remember why two lines of development were touching the same area of code can be really helpful sometimes. -To get a full list of all of the unique commits that were included in either branch involved in this merge, we can use the ``triple dot'' syntax that we learned in <>. +To get a full list of all of the unique commits that were included in either branch involved in this merge, we can use the "`triple dot`" syntax that we learned in <>. [source,console] ---- @@ -462,8 +462,8 @@ index 0399cd5,59727f0..0000000 hello() ---- -The format is called ``Combined Diff'' and gives you two columns of data next to each line. -The first column shows you if that line is different (added or removed) between the ``ours'' branch and the file in your working directory and the second column does the same between the ``theirs'' branch and your working directory copy. +The format is called "`Combined Diff`" and gives you two columns of data next to each line. +The first column shows you if that line is different (added or removed) between the "`ours`" branch and the file in your working directory and the second column does the same between the "`theirs`" branch and your working directory copy. So in that example you can see that the `<<<<<<<` and `>>>>>>>` lines are in the working copy but were not in either side of the merge. This makes sense because the merge tool stuck them in there for our context, but we're expected to remove them. @@ -490,7 +490,7 @@ index 0399cd5,59727f0..0000000 hello() ---- -This shows us that ``hola world'' was in our side but not in the working copy, that ``hello mundo'' was in their side but not in the working copy and finally that ``hola mundo'' was not in either side but is now in the working copy. +This shows us that "`hola world`" was in our side but not in the working copy, that "`hello mundo`" was in their side but not in the working copy and finally that "`hola mundo`" was not in either side but is now in the working copy. This can be useful to review before committing the resolution. You can also get this from the `git log` for any merge to see how something was resolved after the fact. @@ -563,7 +563,7 @@ This approach also won't work if any other commits have been created since the m ===== Reverse the commit If moving the branch pointers around isn't going to work for you, Git gives you the option of making a new commit which undoes all the changes from an existing one. -Git calls this operation a ``revert'', and in this particular scenario, you'd invoke it like this: +Git calls this operation a "`revert`", and in this particular scenario, you'd invoke it like this: [source,console] ---- @@ -571,7 +571,7 @@ $ git revert -m 1 HEAD [master b1d8379] Revert "Merge branch 'topic'" ---- -The `-m 1` flag indicates which parent is the ``mainline'' and should be kept. +The `-m 1` flag indicates which parent is the "`mainline`" and should be kept. When you invoke a merge into `HEAD` (`git merge topic`), the new commit has two parents: the first one is `HEAD` (`C6`), and the second is the tip of the branch being merged in (`C4`). In this case, we want to undo all the changes introduced by merging in parent #2 (`C4`), while keeping all the content from parent #1 (`C6`). @@ -612,13 +612,13 @@ In this example, `M` and `^M` cancel out. ==== Other Types of Merges -So far we've covered the normal merge of two branches, normally handled with what is called the ``recursive'' strategy of merging. +So far we've covered the normal merge of two branches, normally handled with what is called the "`recursive`" strategy of merging. There are other ways to merge branches together however. Let's cover a few of them quickly. ===== Our or Theirs Preference -First of all, there is another useful thing we can do with the normal ``recursive'' mode of merging. +First of all, there is another useful thing we can do with the normal "`recursive`" mode of merging. We've already seen the `ignore-all-space` and `ignore-space-change` options which are passed with a `-X` but we can also tell Git to favor one side or the other when it sees a conflict. By default, when Git sees a conflict between two branches being merged, it will add merge conflict markers into your code and mark the file as conflicted and let you resolve it. @@ -628,7 +628,7 @@ If Git sees this, it will not add conflict markers. Any differences that are mergeable, it will merge. Any differences that conflict, it will simply choose the side you specify in whole, including binary files. -If we go back to the ``hello world'' example we were using before, we can see that merging in our branch causes conflicts. +If we go back to the "`hello world`" example we were using before, we can see that merging in our branch causes conflicts. [source,console] ---- @@ -652,13 +652,13 @@ Merge made by the 'recursive' strategy. create mode 100644 test.sh ---- -In that case, instead of getting conflict markers in the file with ``hello mundo'' on one side and ``hola world'' on the other, it will simply pick ``hola world''. +In that case, instead of getting conflict markers in the file with "`hello mundo`" on one side and "`hola world`" on the other, it will simply pick "`hola world`". However, all the other non-conflicting changes on that branch are merged successfully in. This option can also be passed to the `git merge-file` command we saw earlier by running something like `git merge-file --ours` for individual file merges. -If you want to do something like this but not have Git even try to merge changes from the other side in, there is a more draconian option, which is the ``ours'' merge _strategy_. -This is different from the ``ours'' recursive merge _option_. +If you want to do something like this but not have Git even try to merge changes from the other side in, there is a more draconian option, which is the "`ours`" merge _strategy_. +This is different from the "`ours`" recursive merge _option_. This will basically do a fake merge. It will record a new merge commit with both branches as parents, but it will not even look at the branch you're merging in. diff --git a/book/07-git-tools/sections/bundling.asc b/book/07-git-tools/sections/bundling.asc index 3f1c8212d..f0752173f 100644 --- a/book/07-git-tools/sections/bundling.asc +++ b/book/07-git-tools/sections/bundling.asc @@ -3,7 +3,7 @@ Though we've covered the common ways to transfer Git data over a network (HTTP, SSH, etc), there is actually one more way to do so that is not commonly used but can actually be quite useful. -Git is capable of ``bundling'' its data into a single file. +Git is capable of "`bundling`" its data into a single file. This can be useful in various scenarios. Maybe your network is down and you want to send changes to your co-workers. Perhaps you're working somewhere offsite and don't have access to the local network for security reasons. diff --git a/book/07-git-tools/sections/credentials.asc b/book/07-git-tools/sections/credentials.asc index 408f5b408..b87d1a2a6 100644 --- a/book/07-git-tools/sections/credentials.asc +++ b/book/07-git-tools/sections/credentials.asc @@ -12,15 +12,15 @@ Git has a few options provided in the box: * The default is not to cache at all. Every connection will prompt you for your username and password. -* The ``cache'' mode keeps credentials in memory for a certain period of time. +* The "`cache`" mode keeps credentials in memory for a certain period of time. None of the passwords are ever stored on disk, and they are purged from the cache after 15 minutes. -* The ``store'' mode saves the credentials to a plain-text file on disk, and they never expire. +* The "`store`" mode saves the credentials to a plain-text file on disk, and they never expire. This means that until you change your password for the Git host, you won't ever have to type in your credentials again. The downside of this approach is that your passwords are stored in cleartext in a plain file in your home directory. -* If you're using a Mac, Git comes with an ``osxkeychain'' mode, which caches credentials in the secure keychain that's attached to your system account. +* If you're using a Mac, Git comes with an "`osxkeychain`" mode, which caches credentials in the secure keychain that's attached to your system account. This method stores the credentials on disk, and they never expire, but they're encrypted with the same system that stores HTTPS certificates and Safari auto-fills. -* If you're using Windows, you can install a helper called ``Git Credential Manager for Windows.'' - This is similar to the ``osxkeychain'' helper described above, but uses the Windows Credential Store to control sensitive information. +* If you're using Windows, you can install a helper called "`Git Credential Manager for Windows.`" + This is similar to the "`osxkeychain`" helper described above, but uses the Windows Credential Store to control sensitive information. It can be found at https://github.com/Microsoft/Git-Credential-Manager-for-Windows[]. You can choose one of these methods by setting a Git configuration value: @@ -31,9 +31,9 @@ $ git config --global credential.helper cache ---- Some of these helpers have options. -The ``store'' helper can take a `--file ` argument, which customizes where the plain-text file is saved (the default is `~/.git-credentials`). -The ``cache'' helper accepts the `--timeout ` option, which changes the amount of time its daemon is kept running (the default is ``900'', or 15 minutes). -Here's an example of how you'd configure the ``store'' helper with a custom file name: +The "`store`" helper can take a `--file ` argument, which customizes where the plain-text file is saved (the default is `~/.git-credentials`). +The "`cache`" helper accepts the `--timeout ` option, which changes the amount of time its daemon is kept running (the default is "`900`", or 15 minutes). +Here's an example of how you'd configure the "`store`" helper with a custom file name: [source,console] ---- @@ -59,7 +59,7 @@ Git's root command for the credential-helper system is `git credential`, which t This might be easier to understand with an example. Let's say that a credential helper has been configured, and the helper has stored credentials for `mygithost`. -Here's a session that uses the ``fill'' command, which is invoked when Git is trying to find credentials for a host: +Here's a session that uses the "`fill`" command, which is invoked when Git is trying to find credentials for a host: [source,console] ---- @@ -103,7 +103,7 @@ There are several forms it can take: |====== So the helpers described above are actually named `git-credential-cache`, `git-credential-store`, and so on, and we can configure them to take command-line arguments. -The general form for this is ``git-credential-foo [args] .'' +The general form for this is "`git-credential-foo [args] .`" The stdin/stdout protocol is the same as git-credential, but they use a slightly different set of actions: * `get` is a request for a username/password pair. @@ -132,7 +132,7 @@ username=bob <3> password=s3cre7 ---- -<1> Here we tell `git-credential-store` to save some credentials: the username ``bob'' and the password ``s3cre7'' are to be used when `https://mygithost` is accessed. +<1> Here we tell `git-credential-store` to save some credentials: the username "`bob`" and the password "`s3cre7`" are to be used when `https://mygithost` is accessed. <2> Now we'll retrieve those credentials. We provide the parts of the connection we already know (`https://mygithost`), and an empty line. <3> `git-credential-store` replies with the username and password we stored above. @@ -191,7 +191,7 @@ username=bob password=s3cre7 ---- -Since its name starts with ``git-'', we can use the simple syntax for the configuration value: +Since its name starts with "`git-`", we can use the simple syntax for the configuration value: [source,console] ---- diff --git a/book/07-git-tools/sections/interactive-staging.asc b/book/07-git-tools/sections/interactive-staging.asc index affa704b2..1f7a5635d 100644 --- a/book/07-git-tools/sections/interactive-staging.asc +++ b/book/07-git-tools/sections/interactive-staging.asc @@ -24,7 +24,7 @@ What now> You can see that this command shows you a much different view of your staging area than you're probably used to -- basically, the same information you get with `git status` but a bit more succinct and informative. It lists the changes you've staged on the left and unstaged changes on the right. -After this comes a ``Commands'' section, which allows you to do a number of things like staging and unstaging files, staging parts of files, adding untracked files, and displaying diffs of what has been staged. +After this comes a "`Commands`" section, which allows you to do a number of things like staging and unstaging files, staging parts of files, adding untracked files, and displaying diffs of what has been staged. ==== Staging and Unstaging Files diff --git a/book/07-git-tools/sections/rerere.asc b/book/07-git-tools/sections/rerere.asc index 648a9120a..35a65d14c 100644 --- a/book/07-git-tools/sections/rerere.asc +++ b/book/07-git-tools/sections/rerere.asc @@ -2,7 +2,7 @@ === Rerere The `git rerere` functionality is a bit of a hidden feature. -The name stands for ``reuse recorded resolution'' and, as the name implies, it allows you to ask Git to remember how you've resolved a hunk conflict so that the next time it sees the same conflict, Git can resolve it for you automatically. +The name stands for "`reuse recorded resolution`" and, as the name implies, it allows you to ask Git to remember how you've resolved a hunk conflict so that the next time it sees the same conflict, Git can resolve it for you automatically. There are a number of scenarios in which this functionality might be really handy. One of the examples that is mentioned in the documentation is when you want to make sure a long-lived topic branch will ultimately merge cleanly, but you don't want to have a bunch of intermediate merge commits cluttering up your commit history. @@ -36,7 +36,7 @@ def hello end ---- -In one branch we change the word ``hello'' to ``hola'', then in another branch we change the ``world'' to ``mundo'', just like before. +In one branch we change the word "`hello`" to "`hola`", then in another branch we change the "`world`" to "`mundo`", just like before. image::images/rerere1.png[] @@ -129,7 +129,7 @@ $ git rerere diff end ---- -So that basically says, when Git sees a hunk conflict in a `hello.rb` file that has ``hello mundo'' on one side and ``hola world'' on the other, it will resolve it to ``hola mundo''. +So that basically says, when Git sees a hunk conflict in a `hello.rb` file that has "`hello mundo`" on one side and "`hola world`" on the other, it will resolve it to "`hola mundo`". Now we can mark it as resolved and commit it: diff --git a/book/07-git-tools/sections/reset.asc b/book/07-git-tools/sections/reset.asc index 759cb5ef3..05735f317 100644 --- a/book/07-git-tools/sections/reset.asc +++ b/book/07-git-tools/sections/reset.asc @@ -9,7 +9,7 @@ For this, we recommend a simple metaphor. ==== The Three Trees An easier way to think about `reset` and `checkout` is through the mental frame of Git being a content manager of three different trees. -By ``tree'' here, we really mean ``collection of files'', not specifically the data structure. +By "`tree`" here, we really mean "`collection of files`", not specifically the data structure. There are a few cases where the index doesn't exactly act like a tree, but for our purposes it is easier to think about it this way for now. Git as a system manages and manipulates three trees in its normal operation: @@ -46,13 +46,13 @@ $ git ls-tree -r HEAD 040000 tree 99f1a6d12cb4b6f19... lib ---- -The Git `cat-file` and `ls-tree` commands are ``plumbing'' commands that are used for lower level things and not really used in day-to-day work, but they help us see what's going on here. +The Git `cat-file` and `ls-tree` commands are "`plumbing`" commands that are used for lower level things and not really used in day-to-day work, but they help us see what's going on here. [[_the_index]] ===== The Index The _index_ is your *proposed next commit*. -We've also been referring to this concept as Git's ``Staging Area'' as this is what Git looks at when you run `git commit`. +We've also been referring to this concept as Git's "`Staging Area`" as this is what Git looks at when you run `git commit`. Git populates this index with a list of all the file contents that were last checked out into your working directory and what they looked like when they were originally checked out. You then replace some of those files with new versions of them, and `git commit` converts that into the tree for a new commit. @@ -71,7 +71,7 @@ The index is not technically a tree structure -- it's actually implemented as a ===== The Working Directory -Finally, you have your _working directory_ (also commonly referred to as the ``working tree''). +Finally, you have your _working directory_ (also commonly referred to as the "`working tree`"). The other two trees store their content in an efficient but inconvenient manner, inside the `.git` folder. The working directory unpacks them into actual files, which makes it much easier for you to edit them. Think of the working directory as a *sandbox*, where you can try changes out before committing them to your staging area (index) and then to history. @@ -118,12 +118,12 @@ Let's call this *v2* of the file, and indicate it in red. image::images/reset-ex4.png[] -If we run `git status` right now, we'll see the file in red as ``Changes not staged for commit'', because that entry differs between the index and the working directory. +If we run `git status` right now, we'll see the file in red as "`Changes not staged for commit`", because that entry differs between the index and the working directory. Next we run `git add` on it to stage it into our index. image::images/reset-ex5.png[] -At this point, if we run `git status`, we will see the file in green under ``Changes to be committed'' because the index and HEAD differ -- that is, our proposed next commit is now different from our last commit. +At this point, if we run `git status`, we will see the file in green under "`Changes to be committed`" because the index and HEAD differ -- that is, our proposed next commit is now different from our last commit. Finally, we run `git commit` to finalize the commit. image::images/reset-ex6.png[] @@ -222,7 +222,7 @@ image::images/reset-path2.png[] This is why the output of the `git status` command suggests that you run this to unstage a file (see <> for more on this). -We could just as easily not let Git assume we meant ``pull the data from HEAD'' by specifying a specific commit to pull that file version from. +We could just as easily not let Git assume we meant "`pull the data from HEAD`" by specifying a specific commit to pull that file version from. We would just run something like `git reset eb43bf file.txt`. image::images/reset-path3.png[] @@ -237,7 +237,7 @@ So you can selectively unstage or revert content. Let's look at how to do something interesting with this newfound power -- squashing commits. -Say you have a series of commits with messages like ``oops.'', ``WIP'' and ``forgot this file''. +Say you have a series of commits with messages like "`oops.`", "`WIP`" and "`forgot this file`". You can use `reset` to quickly and easily squash them into a single commit that makes you look really smart. <<_squashing>> shows another way to do this, but in this example it's simpler to use `reset`. @@ -296,7 +296,7 @@ Also, like `git reset` and `git add`, `checkout` will accept a `--patch` option Hopefully now you understand and feel more comfortable with the `reset` command, but are probably still a little confused about how exactly it differs from `checkout` and could not possibly remember all the rules of the different invocations. Here's a cheat-sheet for which commands affect which trees. -The ``HEAD'' column reads ``REF'' if that command moves the reference (branch) that HEAD points to, and ``HEAD'' if it moves HEAD itself. +The "`HEAD`" column reads "`REF`" if that command moves the reference (branch) that HEAD points to, and "`HEAD`" if it moves HEAD itself. Pay especial attention to the 'WD Safe?' column -- if it says *NO*, take a second to think before running that command. [options="header", cols="3,1,1,1,1"] diff --git a/book/07-git-tools/sections/revision-selection.asc b/book/07-git-tools/sections/revision-selection.asc index 17b5ab60d..f853bb5c2 100644 --- a/book/07-git-tools/sections/revision-selection.asc +++ b/book/07-git-tools/sections/revision-selection.asc @@ -112,7 +112,7 @@ ca82a6dff817ec66f44342007202690a93763949 [[_git_reflog]] ==== RefLog Shortnames -One of the things Git does in the background while you're working away is keep a ``reflog'' -- a log of where your HEAD and branch references have been for the last few months. +One of the things Git does in the background while you're working away is keep a "`reflog`" -- a log of where your HEAD and branch references have been for the last few months. You can see your reflog by using `git reflog`: @@ -177,7 +177,7 @@ Running `git show HEAD@{2.months.ago}` will show you the matching commit only if [TIP] .Think of the reflog as Git's version of shell history ==== -If you have a UNIX or Linux background, you can think of the reflog as Git's version of shell history, which emphasizes that what's there is clearly relevant only for you and your ``session'', and has nothing to do with anyone else who might be working on the same machine. +If you have a UNIX or Linux background, you can think of the reflog as Git's version of shell history, which emphasizes that what's there is clearly relevant only for you and your "`session`", and has nothing to do with anyone else who might be working on the same machine. ==== [NOTE] @@ -215,7 +215,7 @@ $ git log --pretty=format:'%h %s' --graph * 9b29157 Add open3_detach to gemspec file list ---- -Then, you can see the previous commit by specifying `HEAD^`, which means ``the parent of HEAD'': +Then, you can see the previous commit by specifying `HEAD^`, which means "`the parent of HEAD`": [source,console] ---- @@ -244,7 +244,7 @@ $ git show "HEAD^" # OK ==== -You can also specify a number after the `^` to identify _which_ parent you want; for example, `d921970^2` means ``the second parent of d921970.'' +You can also specify a number after the `^` to identify _which_ parent you want; for example, `d921970^2` means "`the second parent of d921970.`" This syntax is useful only for merge commits, which have more than one parent -- the _first_ parent of a merge commit is from the branch you were on when you merged (frequently `master`), while the _second_ parent of a merge commit is from the branch that was merged (say, `topic`): [source,console] @@ -267,7 +267,7 @@ Date: Wed Dec 10 22:22:03 2008 +0000 The other main ancestry specification is the `~` (tilde). This also refers to the first parent, so `HEAD~` and `HEAD^` are equivalent. The difference becomes apparent when you specify a number. -`HEAD~2` means ``the first parent of the first parent,'' or ``the grandparent'' -- it traverses the first parents the number of times you specify. +`HEAD~2` means "`the first parent of the first parent,`" or "`the grandparent`" -- it traverses the first parents the number of times you specify. For example, in the history listed earlier, `HEAD~3` would be: [source,console] @@ -298,7 +298,7 @@ You can also combine these syntaxes -- you can get the second parent of the prev ==== Commit Ranges Now that you can specify individual commits, let's see how to specify ranges of commits. -This is particularly useful for managing your branches -- if you have a lot of branches, you can use range specifications to answer questions such as, ``What work is on this branch that I haven't yet merged into my main branch?'' +This is particularly useful for managing your branches -- if you have a lot of branches, you can use range specifications to answer questions such as, "`What work is on this branch that I haven't yet merged into my main branch?`" ===== Double Dot @@ -311,7 +311,7 @@ For example, say you have a commit history that looks like <>. image::images/double-dot.png[Example history for range selection] Say you want to see what is in your `experiment` branch that hasn't yet been merged into your `master` branch. -You can ask Git to show you a log of just those commits with `master..experiment` -- that means ``all commits reachable from `experiment` that aren't reachable from `master`.'' +You can ask Git to show you a log of just those commits with `master..experiment` -- that means "`all commits reachable from `experiment` that aren't reachable from `master`.`" For the sake of brevity and clarity in these examples, the letters of the commit objects from the diagram are used in place of the actual log output in the order that they would display: [source,console] diff --git a/book/07-git-tools/sections/rewriting-history.asc b/book/07-git-tools/sections/rewriting-history.asc index cbaee261a..7110027ec 100644 --- a/book/07-git-tools/sections/rewriting-history.asc +++ b/book/07-git-tools/sections/rewriting-history.asc @@ -172,7 +172,7 @@ Each time, Git will stop, let you amend the commit, and continue when you're fin ==== Reordering Commits You can also use interactive rebases to reorder or remove commits entirely. -If you want to remove the ``Add cat-file'' commit and change the order in which the other two commits are introduced, you can change the rebase script from this: +If you want to remove the "`Add cat-file`" commit and change the order in which the other two commits are introduced, you can change the rebase script from this: [source,console] ---- @@ -190,7 +190,7 @@ pick f7f3f6d Change my name a bit ---- When you save and exit the editor, Git rewinds your branch to the parent of these commits, applies `310154e` and then `f7f3f6d`, and then stops. -You effectively change the order of those commits and remove the ``Add cat-file'' commit completely. +You effectively change the order of those commits and remove the "`Add cat-file`" commit completely. [[_squashing]] ==== Squashing Commits @@ -226,7 +226,7 @@ The script puts helpful instructions in the rebase message: # Note that empty commits are commented out ---- -If, instead of ``pick'' or ``edit'', you specify ``squash'', Git applies both that change and the change directly before it and makes you merge the commit messages together. +If, instead of "`pick`" or "`edit`", you specify "`squash`", Git applies both that change and the change directly before it and makes you merge the commit messages together. So, if you want to make a single commit from these three commits, you make the script look like this: [source,console] @@ -259,8 +259,8 @@ When you save that, you have a single commit that introduces the changes of all Splitting a commit undoes a commit and then partially stages and commits as many times as commits you want to end up with. For example, suppose you want to split the middle commit of your three commits. -Instead of ``Update README formatting and add blame'', you want to split it into two commits: ``Update README formatting'' for the first, and ``Add blame'' for the second. -You can do that in the `rebase -i` script by changing the instruction on the commit you want to split to ``edit'': +Instead of "`Update README formatting and add blame`", you want to split it into two commits: "`Update README formatting`" for the first, and "`Add blame`" for the second. +You can do that in the `rebase -i` script by changing the instruction on the commit you want to split to "`edit`": [source,console] ---- diff --git a/book/07-git-tools/sections/searching.asc b/book/07-git-tools/sections/searching.asc index dd025e437..8caf1230f 100644 --- a/book/07-git-tools/sections/searching.asc +++ b/book/07-git-tools/sections/searching.asc @@ -60,7 +60,7 @@ date.c: /* gmtime_r() in match_digit() may have clobbered it */ As you can see, the `gmtime_r` routine is called from both the `match_multi_number` and `match_digit` functions in the `date.c` file (the third match displayed represents just the string appearing in a comment). You can also search for complex combinations of strings with the `--and` flag, which ensures that multiple matches must occur in the same line of text. -For instance, let's look for any lines that define a constant whose name contains _either_ of the substrings ``LINK'' or ``BUF_MAX'', specifically in an older version of the Git codebase represented by the tag `v1.8.0` (we'll throw in the `--break` and `--heading` options which help split up the output into a more readable format): +For instance, let's look for any lines that define a constant whose name contains _either_ of the substrings "`LINK`" or "`BUF_MAX`", specifically in an older version of the Git codebase represented by the tag `v1.8.0` (we'll throw in the `--break` and `--heading` options which help split up the output into a more readable format): [source,console] ---- @@ -96,7 +96,7 @@ As we saw in the above example, we looked for terms in an older version of the G Perhaps you're looking not for _where_ a term exists, but _when_ it existed or was introduced. The `git log` command has a number of powerful tools for finding specific commits by the content of their messages or even the content of the diff they introduce. -If, for example, we want to find out when the `ZLIB_BUF_MAX` constant was originally introduced, we can use the `-S` option (colloquially referred to as the Git ``pickaxe'' option) to tell Git to show us only those commits that changed the number of occurrences of that string. +If, for example, we want to find out when the `ZLIB_BUF_MAX` constant was originally introduced, we can use the `-S` option (colloquially referred to as the Git "`pickaxe`" option) to tell Git to show us only those commits that changed the number of occurrences of that string. [source,console] ---- diff --git a/book/07-git-tools/sections/stashing-cleaning.asc b/book/07-git-tools/sections/stashing-cleaning.asc index f307e88de..f15b7c0c4 100644 --- a/book/07-git-tools/sections/stashing-cleaning.asc +++ b/book/07-git-tools/sections/stashing-cleaning.asc @@ -236,9 +236,9 @@ A safer option is to run `git stash --all` to remove everything but save it in a Assuming you do want to remove cruft files or clean your working directory, you can do so with `git clean`. To remove all the untracked files in your working directory, you can run `git clean -f -d`, which removes any files and also any subdirectories that become empty as a result. -The `-f` means 'force' or ``really do this,'' and is required if the Git configuration variable `clean.requireForce` is not explicitly set to false. +The `-f` means 'force' or "`really do this,`" and is required if the Git configuration variable `clean.requireForce` is not explicitly set to false. -If you ever want to see what it would do, you can run the command with the `--dry-run` (or `-n`) option, which means ``do a dry run and tell me what you _would_ have removed''. +If you ever want to see what it would do, you can run the command with the `--dry-run` (or `-n`) option, which means "`do a dry run and tell me what you _would_ have removed`". [source,console] ---- @@ -269,7 +269,7 @@ Would remove tmp/ ---- If you don't know what the `git clean` command is going to do, always run it with a `-n` first to double check before changing the `-n` to a `-f` and doing it for real. -The other way you can be careful about the process is to run it with the `-i` or ``interactive'' flag. +The other way you can be careful about the process is to run it with the `-i` or "`interactive`" flag. This will run the clean command in an interactive mode. diff --git a/book/07-git-tools/sections/submodules.asc b/book/07-git-tools/sections/submodules.asc index a832bdedd..4b98257a7 100644 --- a/book/07-git-tools/sections/submodules.asc +++ b/book/07-git-tools/sections/submodules.asc @@ -23,7 +23,7 @@ We'll walk through developing a simple project that has been split up into a mai Let's start by adding an existing Git repository as a submodule of the repository that we're working on. To add a new submodule you use the `git submodule add` command with the absolute or relative URL of the project you would like to start tracking. -In this example, we'll add a library called ``DbConnector''. +In this example, we'll add a library called "`DbConnector`". [source,console] ---- @@ -36,7 +36,7 @@ Unpacking objects: 100% (11/11), done. Checking connectivity... done. ---- -By default, submodules will add the subproject into a directory named the same as the repository, in this case ``DbConnector''. +By default, submodules will add the subproject into a directory named the same as the repository, in this case "`DbConnector`". You can add a different path at the end of the command if you want it to go elsewhere. If you run `git status` at this point, you'll notice a few things. @@ -234,7 +234,7 @@ Fast-forward ---- Now if you go back into the main project and run `git diff --submodule` you can see that the submodule was updated and get a list of commits that were added to it. -If you don't want to type `--submodule` every time you run `git diff`, you can set it as the default format by setting the `diff.submodule` config value to ``log''. +If you don't want to type `--submodule` every time you run `git diff`, you can set it as the default format by setting the `diff.submodule` config value to "`log`". [source,console] ---- @@ -264,7 +264,7 @@ Submodule path 'DbConnector': checked out 'd0354fc054692d3906c85c3af05ddce39a1c0 This command will by default assume that you want to update the checkout to the `master` branch of the submodule repository. You can, however, set this to something different if you want. -For example, if you want to have the DbConnector submodule track that repository's ``stable'' branch, you can set it in either your `.gitmodules` file (so everyone else also tracks it), or just in your local `.git/config` file. +For example, if you want to have the DbConnector submodule track that repository's "`stable`" branch, you can set it in either your `.gitmodules` file (so everyone else also tracks it), or just in your local `.git/config` file. Let's set it in the `.gitmodules` file: [source,console] @@ -283,7 +283,7 @@ Submodule path 'DbConnector': checked out 'c87d55d4c6d4b05ee34fbc8cb6f7bf4585ae6 If you leave off the `-f .gitmodules` it will only make the change for you, but it probably makes more sense to track that information with the repository so everyone else does as well. -When we run `git status` at this point, Git will show us that we have ``new commits'' on the submodule. +When we run `git status` at this point, Git will show us that we have "`new commits`" on the submodule. [source,console] ---- @@ -417,7 +417,7 @@ no changes added to commit (use "git add" and/or "git commit -a") By default, the `git pull` command recursively fetches submodules changes, as we can see in the output of the first command above. However, it does not *update* the submodules. -This is shown by the output of the `git status` command, which shows the submodule is ``modified'', and has ``new commits''. +This is shown by the output of the `git status` command, which shows the submodule is "`modified`", and has "`new commits`". What's more, the brackets showing the new commits point left (<), indicating that these commits are recorded in MainProject but are not present in the local DbConnector checkout. To finalize the update, you need to run `git submodule update`: @@ -459,7 +459,7 @@ Otherwise you would probably instead be using a simpler dependency management sy So now let's go through an example of making changes to the submodule at the same time as the main project and committing and publishing those changes at the same time. -So far, when we've run the `git submodule update` command to fetch changes from the submodule repositories, Git would get the changes and update the files in the subdirectory but will leave the sub-repository in what's called a ``detached HEAD'' state. +So far, when we've run the `git submodule update` command to fetch changes from the submodule repositories, Git would get the changes and update the files in the subdirectory but will leave the sub-repository in what's called a "`detached HEAD`" state. This means that there is no local working branch (like `master`, for example) tracking changes. With no working branch tracking changes, that means even if you commit changes to the submodule, those changes will quite possibly be lost the next time you run `git submodule update`. You have to do some extra steps if you want changes in a submodule to be tracked. @@ -478,7 +478,7 @@ $ git checkout stable Switched to branch 'stable' ---- -Let's try updating our submodule with the ``merge'' option. +Let's try updating our submodule with the "`merge`" option. To specify it manually, we can just add the `--merge` option to our `update` call. Here we'll see that there was a change on the server for this submodule and it gets merged in. @@ -585,8 +585,8 @@ If we commit in the main project and push it up without pushing the submodule ch Those changes will only exist on our local copy. In order to make sure this doesn't happen, you can ask Git to check that all your submodules have been pushed properly before pushing the main project. -The `git push` command takes the `--recurse-submodules` argument which can be set to either ``check'' or ``on-demand''. -The ``check'' option will make `push` simply fail if any of the committed submodule changes haven't been pushed. +The `git push` command takes the `--recurse-submodules` argument which can be set to either "`check`" or "`on-demand`". +The "`check`" option will make `push` simply fail if any of the committed submodule changes haven't been pushed. [source,console] ---- @@ -610,7 +610,7 @@ As you can see, it also gives us some helpful advice on what we might want to do The simple option is to go into each submodule and manually push to the remotes to make sure they're externally available and then try this push again. If you want the check behavior to happen for all pushes, you can make this behavior the default by doing `git config push.recurseSubmodules check`. -The other option is to use the ``on-demand'' value, which will try to do this for you. +The other option is to use the "`on-demand`" value, which will try to do this for you. [source,console] ---- @@ -663,7 +663,7 @@ Automatic merge failed; fix conflicts and then commit the result. ---- So basically what has happened here is that Git has figured out that the two branches record points in the submodule's history that are divergent and need to be merged. -It explains it as ``merge following commits not found'', which is confusing but we'll explain why that is in a bit. +It explains it as "`merge following commits not found`", which is confusing but we'll explain why that is in a bit. To solve the problem, you need to figure out what state the submodule should be in. Strangely, Git doesn't really give you much information to help out here, not even the SHA-1s of the commits of both sides of the history. @@ -744,7 +744,7 @@ Interestingly, there is another case that Git handles. If a merge commit exists in the submodule directory that contains *both* commits in its history, Git will suggest it to you as a possible solution. It sees that at some point in the submodule project, someone merged branches containing these two commits, so maybe you'll want that one. -This is why the error message from before was ``merge following commits not found'', because it could not do *this*. +This is why the error message from before was "`merge following commits not found`", because it could not do *this*. It's confusing because who would expect it to *try* to do this? If it does find a single acceptable merge commit, you'll see something like this: @@ -969,7 +969,7 @@ nothing to commit, working tree clean ---- Using the `--recurse-submodules` flag of `git checkout` can also be useful when you work on several branches in the superproject, each having your submodule pointing at different commits. -Indeed, if you switch between branches that record the submodule at different commits, upon executing `git status` the submodule will appear as ``modified'', and indicate ``new commits''. +Indeed, if you switch between branches that record the submodule at different commits, upon executing `git status` the submodule will appear as "`modified`", and indicate "`new commits`". That is because the submodule state is by default not carried over when switching branches. This can be really confusing, so it's a good idea to always `git checkout --recurse-submodules` when your project has submodules. diff --git a/book/08-customizing-git/sections/attributes.asc b/book/08-customizing-git/sections/attributes.asc index 6438920ad..c4ec16b84 100644 --- a/book/08-customizing-git/sections/attributes.asc +++ b/book/08-customizing-git/sections/attributes.asc @@ -58,8 +58,8 @@ Put the following line in your `.gitattributes` file: *.docx diff=word ---- -This tells Git that any file that matches this pattern (`.docx`) should use the ``word'' filter when you try to view a diff that contains changes. -What is the ``word'' filter? +This tells Git that any file that matches this pattern (`.docx`) should use the "`word`" filter when you try to view a diff that contains changes. +What is the "`word`" filter? You have to set it up. Here you'll configure Git to use the `docx2txt` program to convert Word documents into readable text files, which it will then diff properly. @@ -82,7 +82,7 @@ Finally, you can configure Git to use this script: $ git config diff.word.textconv docx2txt ---- -Now Git knows that if it tries to do a diff between two snapshots, and any of the files end in `.docx`, it should run those files through the ``word'' filter, which is defined as the `docx2txt` program. +Now Git knows that if it tries to do a diff between two snapshots, and any of the files end in `.docx`, it should run those files through the "`word`" filter, which is defined as the `docx2txt` program. This effectively makes nice text-based versions of your Word files before attempting to diff them. Here's an example: Chapter 1 of this book was converted to Word format and committed in a Git repository. @@ -106,7 +106,7 @@ index 0b013ca..ba25db5 100644 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. ---- -Git successfully and succinctly tells us that we added the string ``Testing: 1, 2, 3.'', which is correct. +Git successfully and succinctly tells us that we added the string "`Testing: 1, 2, 3.`", which is correct. It's not perfect – formatting changes wouldn't show up here – but it certainly works. Another interesting problem you can solve this way involves diffing image files. @@ -192,27 +192,27 @@ However, that result is of limited use. If you've used keyword substitution in CVS or Subversion, you can include a datestamp – the SHA-1 isn't all that helpful, because it's fairly random and you can't tell if one SHA-1 is older or newer than another just by looking at them. It turns out that you can write your own filters for doing substitutions in files on commit/checkout. -These are called ``clean'' and ``smudge'' filters. -In the `.gitattributes` file, you can set a filter for particular paths and then set up scripts that will process files just before they're checked out (``smudge'', see <>) and just before they're staged (``clean'', see <>). +These are called "`clean`" and "`smudge`" filters. +In the `.gitattributes` file, you can set a filter for particular paths and then set up scripts that will process files just before they're checked out ("`smudge`", see <>) and just before they're staged ("`clean`", see <>). These filters can be set to do all sorts of fun things. [[filters_a]] -.The ``smudge'' filter is run on checkout -image::images/smudge.png[The ``smudge'' filter is run on checkout] +.The "`smudge`" filter is run on checkout +image::images/smudge.png[The "`smudge`" filter is run on checkout] [[filters_b]] -.The ``clean'' filter is run when files are staged -image::images/clean.png[The ``clean'' filter is run when files are staged] +.The "`clean`" filter is run when files are staged +image::images/clean.png[The "`clean`" filter is run when files are staged] The original commit message for this feature gives a simple example of running all your C source code through the `indent` program before committing. -You can set it up by setting the filter attribute in your `.gitattributes` file to filter `*.c` files with the ``indent'' filter: +You can set it up by setting the filter attribute in your `.gitattributes` file to filter `*.c` files with the "`indent`" filter: [source,ini] ---- *.c filter=indent ---- -Then, tell Git what the ``indent'' filter does on smudge and clean: +Then, tell Git what the "`indent`" filter does on smudge and clean: [source,console] ---- diff --git a/book/08-customizing-git/sections/config.asc b/book/08-customizing-git/sections/config.asc index 207c69da1..2c5e73565 100644 --- a/book/08-customizing-git/sections/config.asc +++ b/book/08-customizing-git/sections/config.asc @@ -24,7 +24,7 @@ Finally, Git looks for configuration values in the configuration file in the Git These values are specific to that single repository, and represent passing the `--local` option to `git config`. If you don't specify which level you want to work with, this is the default. -Each of these ``levels'' (system, global, local) overwrites values in the previous level, so values in `.git/config` trump those in `[path]/etc/gitconfig`, for instance. +Each of these "`levels`" (system, global, local) overwrites values in the previous level, so values in `.git/config` trump those in `[path]/etc/gitconfig`, for instance. [NOTE] ==== @@ -190,7 +190,7 @@ Continuing under the assumption that you meant 'checkout' in 0.1 seconds automatically... ---- -Note that ``0.1 seconds'' business. +Note that "`0.1 seconds`" business. `help.autocorrect` is actually an integer which represents tenths of a second. So if you set it to 50, Git will give you 5 seconds to change your mind before executing the autocorrected command. diff --git a/book/08-customizing-git/sections/policy.asc b/book/08-customizing-git/sections/policy.asc index a20d40d88..852a0c03a 100644 --- a/book/08-customizing-git/sections/policy.asc +++ b/book/08-customizing-git/sections/policy.asc @@ -18,7 +18,7 @@ The `update` hook runs once per branch being pushed and takes three arguments: * The new revision being pushed You also have access to the user doing the pushing if the push is being run over SSH. -If you've allowed everyone to connect with a single user (like ``git'') via public-key authentication, you may have to give that user a shell wrapper that determines which user is connecting based on the public key, and set an environment variable accordingly. +If you've allowed everyone to connect with a single user (like "`git`") via public-key authentication, you may have to give that user a shell wrapper that determines which user is connecting based on the public key, and set an environment variable accordingly. Here we'll assume the connecting user is in the `$USER` environment variable, so your update script begins by gathering all the information you need: [source,ruby] @@ -41,7 +41,7 @@ Don't judge – it's easier to demonstrate this way. ===== Enforcing a Specific Commit-Message Format Your first challenge is to enforce that each commit message adheres to a particular format. -Just to have a target, assume that each message has to include a string that looks like ``ref: 1234'' because you want each commit to link to a work item in your ticketing system. +Just to have a target, assume that each message has to include a string that looks like "`ref: 1234`" because you want each commit to link to a work item in your ticketing system. You must look at each commit being pushed up, see if that string is in the commit message, and, if the string is absent from any of the commits, exit non-zero so the push is rejected. You can get a list of the SHA-1 values of all the commits that are being pushed by taking the `$newrev` and `$oldrev` values and passing them to a Git plumbing command called `git rev-list`. diff --git a/book/09-git-and-other-scms/sections/client-hg.asc b/book/09-git-and-other-scms/sections/client-hg.asc index 1c0770c96..a992e1b6a 100644 --- a/book/09-git-and-other-scms/sections/client-hg.asc +++ b/book/09-git-and-other-scms/sections/client-hg.asc @@ -47,7 +47,7 @@ $ hg clone http://selenic.com/repo/hello /tmp/hello ===== Getting Started -Now that we have a suitable ``server-side'' repository, we can go through a typical workflow. +Now that we have a suitable "`server-side`" repository, we can go through a typical workflow. As you'll see, these two systems are similar enough that there isn't much friction. As always with Git, first we clone: @@ -93,7 +93,7 @@ $ tree .git/refs Git-remote-hg is trying to make things more idiomatically Git-esque, but under the hood it's managing the conceptual mapping between two slightly different systems. The `refs/hg` directory is where the actual remote refs are stored. -For example, the `refs/hg/origin/branches/default` is a Git ref file that contains the SHA-1 starting with ``ac7955c'', which is the commit that `master` points to. +For example, the `refs/hg/origin/branches/default` is a Git ref file that contains the SHA-1 starting with "`ac7955c`", which is the commit that `master` points to. So the `refs/hg` directory is kind of like a fake `refs/remotes/origin`, but it has the added distinction between bookmarks and branches. The `notes/hg` file is the starting point for how git-remote-hg maps Git commit hashes to Mercurial changeset IDs. @@ -121,7 +121,7 @@ $ git cat-file -p ac9117f So `refs/notes/hg` points to a tree, which in the Git object database is a list of other objects with names. `git ls-tree` outputs the mode, type, object hash, and filename for items inside a tree. -Once we dig down to one of the tree items, we find that inside it is a blob named ``ac9117f'' (the SHA-1 hash of the commit pointed to by `master`), with contents ``0a04b98'' (which is the ID of the Mercurial changeset at the tip of the `default` branch). +Once we dig down to one of the tree items, we find that inside it is a blob named "`ac9117f`" (the SHA-1 hash of the commit pointed to by `master`), with contents "`0a04b98`" (which is the ID of the Mercurial changeset at the tip of the `default` branch). The good news is that we mostly don't have to worry about all of this. The typical workflow won't be very different from working with a Git remote. @@ -171,7 +171,7 @@ $ git log --oneline --graph --decorate --all * 65bb417 Create a standard 'hello, world' program ---- -Since we used the `--all` flag, we see the ``notes'' refs that are used internally by git-remote-hg, but we can ignore them. +Since we used the `--all` flag, we see the "`notes`" refs that are used internally by git-remote-hg, but we can ignore them. The rest is what we expected; `origin/master` has advanced by one commit, and our history has now diverged. Unlike the other systems we work with in this chapter, Mercurial is capable of handling merges, so we're not going to do anything fancy. @@ -233,9 +233,9 @@ The changeset numbered _2_ was made by Mercurial, and the changesets numbered _3 ===== Branches and Bookmarks Git has only one kind of branch: a reference that moves when commits are made. -In Mercurial, this kind of a reference is called a ``bookmark,'' and it behaves in much the same way as a Git branch. +In Mercurial, this kind of a reference is called a "`bookmark,`" and it behaves in much the same way as a Git branch. -Mercurial's concept of a ``branch'' is more heavyweight. +Mercurial's concept of a "`branch`" is more heavyweight. The branch that a changeset is made on is recorded _with the changeset_, which means it will always be in the repository history. Here's an example of a commit that was made on the `develop` branch: @@ -250,7 +250,7 @@ date: Thu Aug 14 20:06:38 2014 -0700 summary: More documentation ---- -Note the line that begins with ``branch''. +Note the line that begins with "`branch`". Git can't really replicate this (and doesn't need to; both types of branch can be represented as a Git ref), but git-remote-hg needs to understand the difference, because Mercurial cares. Creating Mercurial bookmarks is as easy as creating Git branches. @@ -298,7 +298,7 @@ o 0 0a04b987be5a 2005-08-26 01:20 -0700 mpm Note the new `[featureA]` tag on revision 5. These act exactly like Git branches on the Git side, with one exception: you can't delete a bookmark from the Git side (this is a limitation of remote helpers). -You can work on a ``heavyweight'' Mercurial branch also: just put a branch in the `branches` namespace: +You can work on a "`heavyweight`" Mercurial branch also: just put a branch in the `branches` namespace: [source,console] ---- @@ -344,7 +344,7 @@ o changeset: 5:bd5ac26f11f9 [...] ---- -The branch name ``permanent'' was recorded with the changeset marked _7_. +The branch name "`permanent`" was recorded with the changeset marked _7_. From the Git side, working with either of these branch styles is the same: just checkout, commit, fetch, merge, pull, and push as you normally would. One thing you should know is that Mercurial doesn't support rewriting history, only adding to it. diff --git a/book/09-git-and-other-scms/sections/client-p4.asc b/book/09-git-and-other-scms/sections/client-p4.asc index 61ae65c75..2cd034612 100644 --- a/book/09-git-and-other-scms/sections/client-p4.asc +++ b/book/09-git-and-other-scms/sections/client-p4.asc @@ -8,7 +8,7 @@ As such, it's designed with the constraints of its day; it assumes you're always To be sure, its features and constraints are well-suited to several specific problems, but there are lots of projects using Perforce where Git would actually work better. There are two options if you'd like to mix your use of Perforce and Git. -The first one we'll cover is the ``Git Fusion'' bridge from the makers of Perforce, which lets you expose subtrees of your Perforce depot as read-write Git repositories. +The first one we'll cover is the "`Git Fusion`" bridge from the makers of Perforce, which lets you expose subtrees of your Perforce depot as read-write Git repositories. The second is git-p4, a client-side bridge that lets you use Git as a Perforce client, without requiring any reconfiguration of the Perforce server. [[_p4_git_fusion]] @@ -30,7 +30,7 @@ image::images/git-fusion-boot.png[The Git Fusion virtual machine boot screen] You should take note of the IP address that's shown here, we'll be using it later on. Next, we'll create a Perforce user. -Select the ``Login'' option at the bottom and press enter (or SSH to the machine), and log in as `root`. +Select the "`Login`" option at the bottom and press enter (or SSH to the machine), and log in as `root`. Then use these commands to create a user: [source,console] @@ -186,7 +186,7 @@ Note that the email addresses and full names should be unique, unless you want a Perforce Git Fusion is a two-way bridge between Perforce and Git version control. Let's have a look at how it feels to work from the Git side. -We'll assume we've mapped in the ``Jam'' project using a configuration file as shown above, which we can clone like this: +We'll assume we've mapped in the "`Jam`" project using a configuration file as shown above, which we can clone like this: [source,console] ---- @@ -297,7 +297,7 @@ At top right, we have a visual graph of how different revisions of the file are The rest of the view is given to the details view for the selected revision (`2` in this case). One thing to notice is that the graph looks exactly like the one in Git's history. -Perforce didn't have a named branch to store the `1` and `2` commits, so it made an ``anonymous'' branch in the `.git-fusion` directory to hold it. +Perforce didn't have a named branch to store the `1` and `2` commits, so it made an "`anonymous`" branch in the `.git-fusion` directory to hold it. This will also happen for named Git branches that don't correspond to a named Perforce branch (and you can later map them to a Perforce branch using the configuration file). Most of this happens behind the scenes, but the end result is that one person on a team can be using Git, another can be using Perforce, and neither of them will know about the other's choice. @@ -350,7 +350,7 @@ Initialized empty Git repository in /private/tmp/www-shallow/.git/ Doing initial import of //depot/www/live/ from revision #head into refs/remotes/p4/master ---- -This creates what in Git terms is a ``shallow'' clone; only the very latest Perforce revision is imported into Git; remember, Perforce isn't designed to give every revision to every user. +This creates what in Git terms is a "`shallow`" clone; only the very latest Perforce revision is imported into Git; remember, Perforce isn't designed to give every revision to every user. This is enough to use Git as a Perforce client, but for other purposes it's not enough. Once it's finished, we have a fully-functional Git repository: @@ -362,7 +362,7 @@ $ git log --oneline --all --graph --decorate * 70eaf78 (HEAD, p4/master, p4/HEAD, master) Initial import of //depot/www/live/ from the state at revision #head ---- -Note how there's a ``p4'' remote for the Perforce server, but everything else looks like a standard clone. +Note how there's a "`p4`" remote for the Perforce server, but everything else looks like a standard clone. Actually, that's a bit misleading; there isn't actually a remote there. [source,console] @@ -638,7 +638,7 @@ $ cd project; git log --oneline --all --graph --decorate * 2b83451 Project init ---- -Note the ``@all'' specifier in the depot path; that tells git-p4 to clone not just the latest changeset for that subtree, but all changesets that have ever touched those paths. +Note the "`@all`" specifier in the depot path; that tells git-p4 to clone not just the latest changeset for that subtree, but all changesets that have ever touched those paths. This is closer to Git's concept of a clone, but if you're working on a project with a long history, it could take a while. The `--detect-branches` flag tells git-p4 to use Perforce's branch specs to map the branches to Git refs. @@ -653,7 +653,7 @@ $ git config git-p4.branchList main:dev $ git clone --detect-branches //depot/project@all . ---- -Setting the `git-p4.branchList` configuration variable to `main:dev` tells git-p4 that ``main'' and ``dev'' are both branches, and the second one is a child of the first one. +Setting the `git-p4.branchList` configuration variable to `main:dev` tells git-p4 that "`main`" and "`dev`" are both branches, and the second one is a child of the first one. If we now `git checkout -b dev p4/project/dev` and make some commits, git-p4 is smart enough to target the right branch when we do `git p4 submit`. Unfortunately, git-p4 can't mix shallow clones and multiple branches; if you have a huge project and want to work on more than one branch, you'll have to `git p4 clone` once for each branch you want to submit to. diff --git a/book/09-git-and-other-scms/sections/client-svn.asc b/book/09-git-and-other-scms/sections/client-svn.asc index 5ee30720a..cb50aa59c 100644 --- a/book/09-git-and-other-scms/sections/client-svn.asc +++ b/book/09-git-and-other-scms/sections/client-svn.asc @@ -370,7 +370,7 @@ $ git branch opera remotes/origin/opera ---- Now, if you want to merge your `opera` branch into `trunk` (your `master` branch), you can do so with a normal `git merge`. -But you need to provide a descriptive commit message (via `-m`), or the merge will say ``Merge branch opera'' instead of something useful. +But you need to provide a descriptive commit message (via `-m`), or the merge will say "`Merge branch opera`" instead of something useful. Remember that although you're using `git merge` to do this operation, and the merge likely will be much easier than it would be in Subversion (because Git will automatically detect the appropriate merge base for you), this isn't a normal Git merge commit. You have to push this data back to a Subversion server that can't handle a commit that tracks more than one parent; so, after you push it up, it will look like a single commit that squashed in all the work of another branch under a single commit. diff --git a/book/09-git-and-other-scms/sections/import-custom.asc b/book/09-git-and-other-scms/sections/import-custom.asc index 14bc9c00b..e3e58ff5f 100644 --- a/book/09-git-and-other-scms/sections/import-custom.asc +++ b/book/09-git-and-other-scms/sections/import-custom.asc @@ -55,7 +55,7 @@ end ---- You run `print_export` inside each directory, which takes the manifest and mark of the previous snapshot and returns the manifest and mark of this one; that way, you can link them properly. -``Mark'' is the `fast-import` term for an identifier you give to a commit; as you create commits, you give each one a mark that you can use to link to it from other commits. +"`Mark`" is the `fast-import` term for an identifier you give to a commit; as you create commits, you give each one a mark that you can use to link to it from other commits. So, the first thing to do in your `print_export` method is generate a mark from the directory name: [source,ruby] diff --git a/book/09-git-and-other-scms/sections/import-svn.asc b/book/09-git-and-other-scms/sections/import-svn.asc index becb37df2..df306b3f0 100644 --- a/book/09-git-and-other-scms/sections/import-svn.asc +++ b/book/09-git-and-other-scms/sections/import-svn.asc @@ -105,7 +105,7 @@ $ for b in $(git for-each-ref --format='%(refname:short)' refs/remotes); do git ---- It may happen that you'll see some extra branches which are suffixed by `@xxx` (where xxx is a number), while in Subversion you only see one branch. -This is actually a Subversion feature called ``peg-revisions'', which is something that Git simply has no syntactical counterpart for. +This is actually a Subversion feature called "`peg-revisions`", which is something that Git simply has no syntactical counterpart for. Hence, `git svn` simply adds the svn version number to the branch name just in the same way as you would have written it in svn to address the peg-revision of that branch. If you do not care anymore about the peg-revisions, simply remove them: diff --git a/book/10-git-internals/sections/environment.asc b/book/10-git-internals/sections/environment.asc index eefc93e48..fc7e51d1b 100644 --- a/book/10-git-internals/sections/environment.asc +++ b/book/10-git-internals/sections/environment.asc @@ -51,11 +51,11 @@ If you happen to have a lot of projects with large files that have the exact sam ==== Pathspecs -A ``pathspec'' refers to how you specify paths to things in Git, including the use of wildcards. +A "`pathspec`" refers to how you specify paths to things in Git, including the use of wildcards. These are used in the `.gitignore` file, but also on the command-line (`git add *.c`). *`GIT_GLOB_PATHSPECS`* and *`GIT_NOGLOB_PATHSPECS`* control the default behavior of wildcards in pathspecs. -If `GIT_GLOB_PATHSPECS` is set to 1, wildcard characters act as wildcards (which is the default); if `GIT_NOGLOB_PATHSPECS` is set to 1, wildcard characters only match themselves, meaning something like `*.c` would only match a file _named_ ``*.c'', rather than any file whose name ends with `.c`. +If `GIT_GLOB_PATHSPECS` is set to 1, wildcard characters act as wildcards (which is the default); if `GIT_NOGLOB_PATHSPECS` is set to 1, wildcard characters only match themselves, meaning something like `*.c` would only match a file _named_ "`*.c`", rather than any file whose name ends with `.c`. You can override this in individual cases by starting the pathspec with `:(glob)` or `:(literal)`, as in `:(glob)*.c`. *`GIT_LITERAL_PATHSPECS`* disables both of the above behaviors; no wildcard characters will work, and the override prefixes are disabled as well. @@ -67,17 +67,17 @@ You can override this in individual cases by starting the pathspec with `:(glob) The final creation of a Git commit object is usually done by `git-commit-tree`, which uses these environment variables as its primary source of information, falling back to configuration values only if these aren't present. -*`GIT_AUTHOR_NAME`* is the human-readable name in the ``author'' field. +*`GIT_AUTHOR_NAME`* is the human-readable name in the "`author`" field. -*`GIT_AUTHOR_EMAIL`* is the email for the ``author'' field. +*`GIT_AUTHOR_EMAIL`* is the email for the "`author`" field. -*`GIT_AUTHOR_DATE`* is the timestamp used for the ``author'' field. +*`GIT_AUTHOR_DATE`* is the timestamp used for the "`author`" field. -*`GIT_COMMITTER_NAME`* sets the human name for the ``committer'' field. +*`GIT_COMMITTER_NAME`* sets the human name for the "`committer`" field. -*`GIT_COMMITTER_EMAIL`* is the email address for the ``committer'' field. +*`GIT_COMMITTER_EMAIL`* is the email address for the "`committer`" field. -*`GIT_COMMITTER_DATE`* is used for the timestamp in the ``committer'' field. +*`GIT_COMMITTER_DATE`* is used for the timestamp in the "`committer`" field. *`EMAIL`* is the fallback email address in case the `user.email` configuration value isn't set. If _this_ isn't set, Git falls back to the system user and host names. @@ -128,7 +128,7 @@ Want to _really_ know what Git is up to? Git has a fairly complete set of traces embedded, and all you need to do is turn them on. The possible values of these variables are as follows: -* ``true'', ``1'', or ``2'' – the trace category is written to stderr. +* "`true`", "`1`", or "`2`" – the trace category is written to stderr. * An absolute path starting with `/` – the trace output will be written to that file. *`GIT_TRACE`* controls general traces, which don't fit into any specific category. diff --git a/book/10-git-internals/sections/maintenance.asc b/book/10-git-internals/sections/maintenance.asc index b28cf131c..1cdfcd527 100644 --- a/book/10-git-internals/sections/maintenance.asc +++ b/book/10-git-internals/sections/maintenance.asc @@ -6,10 +6,10 @@ This section will cover some of these scenarios. [[_git_gc]] ==== Maintenance -Occasionally, Git automatically runs a command called ``auto gc''. +Occasionally, Git automatically runs a command called "`auto gc`". Most of the time, this command does nothing. However, if there are too many loose objects (objects not in a packfile) or too many packfiles, Git launches a full-fledged `git gc` command. -The ``gc'' stands for garbage collect, and the command does a number of things: it gathers up all the loose objects and places them in packfiles, it consolidates packfiles into one big packfile, and it removes objects that aren't reachable from any commit and are a few months old. +The "`gc`" stands for garbage collect, and the command does a number of things: it gathers up all the loose objects and places them in packfiles, it consolidates packfiles into one big packfile, and it removes objects that aren't reachable from any commit and are a few months old. You can run auto gc manually as follows: @@ -168,7 +168,7 @@ dangling tree aea790b9a58f6cf6f2804eeac9f0abbe9631e4c9 dangling blob 7108f7ecb345ee9d0084193f147cdad4d2998293 ---- -In this case, you can see your missing commit after the string ``dangling commit''. +In this case, you can see your missing commit after the string "`dangling commit`". You can recover it the same way, by adding a branch that points to that SHA-1. [[_removing_objects]] diff --git a/book/10-git-internals/sections/objects.asc b/book/10-git-internals/sections/objects.asc index 916b4e7fa..04e37f1ca 100644 --- a/book/10-git-internals/sections/objects.asc +++ b/book/10-git-internals/sections/objects.asc @@ -219,7 +219,7 @@ $ git cat-file -p 0155eb4229851634a0f03eb265b69f5a2d56f341 100644 blob 1f7a7a472abf3dd9643fd615f6da379c4acb3e3a test.txt ---- -Notice that this tree has both file entries and also that the `test.txt` SHA-1 is the ``version 2'' SHA-1 from earlier (`1f7a7a`). +Notice that this tree has both file entries and also that the `test.txt` SHA-1 is the "`version 2`" SHA-1 from earlier (`1f7a7a`). Just for fun, you'll add the first tree as a subdirectory into this one. You can read trees into your staging area by calling `git read-tree`. In this case, you can read an existing tree into your staging area as a subtree by using the `--prefix` option with this command: @@ -354,7 +354,7 @@ image::images/data-model-3.png[All the reachable objects in your Git directory] We mentioned earlier that there is a header stored with every object you commit to your Git object database. Let's take a minute to see how Git stores its objects. -You'll see how to store a blob object -- in this case, the string ``what is up, doc?'' -- interactively in the Ruby scripting language. +You'll see how to store a blob object -- in this case, the string "`what is up, doc?`" -- interactively in the Ruby scripting language. You can start up interactive Ruby mode with the `irb` command: diff --git a/book/10-git-internals/sections/packfiles.asc b/book/10-git-internals/sections/packfiles.asc index b1229c088..d77b8c65d 100644 --- a/book/10-git-internals/sections/packfiles.asc +++ b/book/10-git-internals/sections/packfiles.asc @@ -85,8 +85,8 @@ You have two nearly identical 22K objects on your disk (each compressed to appro Wouldn't it be nice if Git could store one of them in full but then the second object only as the delta between it and the first? It turns out that it can. -The initial format in which Git saves objects on disk is called a ``loose'' object format. -However, occasionally Git packs up several of these objects into a single binary file called a ``packfile'' in order to save space and be more efficient. +The initial format in which Git saves objects on disk is called a "`loose`" object format. +However, occasionally Git packs up several of these objects into a single binary file called a "`packfile`" in order to save space and be more efficient. Git does this if you have too many loose objects around, if you run the `git gc` command manually, or if you push to a remote server. To see what happens, you can manually ask Git to pack up the objects by calling the `git gc` command: @@ -112,7 +112,7 @@ $ find .git/objects -type f .git/objects/pack/pack-978e03944f5c581011e6998cd0e9e30000905586.pack ---- -The objects that remain are the blobs that aren't pointed to by any commit -- in this case, the ``what is up, doc?'' example and the ``test content'' example blobs you created earlier. +The objects that remain are the blobs that aren't pointed to by any commit -- in this case, the "`what is up, doc?`" example and the "`test content`" example blobs you created earlier. Because you never added them to any commits, they're considered dangling and aren't packed up in your new packfile. The other files are your new packfile and an index. diff --git a/book/10-git-internals/sections/plumbing-porcelain.asc b/book/10-git-internals/sections/plumbing-porcelain.asc index e7a26a154..53b409554 100644 --- a/book/10-git-internals/sections/plumbing-porcelain.asc +++ b/book/10-git-internals/sections/plumbing-porcelain.asc @@ -3,7 +3,7 @@ This book covers primarily how to use Git with 30 or so subcommands such as `checkout`, `branch`, `remote`, and so on. But because Git was initially a toolkit for a version control system rather than a full user-friendly VCS, it has a number of subcommands that do low-level work and were designed to be chained together UNIX-style or called from scripts. -These commands are generally referred to as Git's ``plumbing'' commands, while the more user-friendly commands are called ``porcelain'' commands. +These commands are generally referred to as Git's "`plumbing`" commands, while the more user-friendly commands are called "`porcelain`" commands. As you will have noticed by now, this book's first nine chapters deal almost exclusively with porcelain commands. But in this chapter, you'll be dealing mostly with the lower-level plumbing commands, because they give you access to the inner workings of Git, and help demonstrate how and why Git does what it does. diff --git a/book/10-git-internals/sections/refs.asc b/book/10-git-internals/sections/refs.asc index 0f794b33b..cac0ff0cb 100644 --- a/book/10-git-internals/sections/refs.asc +++ b/book/10-git-internals/sections/refs.asc @@ -4,7 +4,7 @@ If you were interested in seeing the history of your repository reachable from commit, say, `1a410e`, you could run something like `git log 1a410e` to display that history, but you would still have to remember that `1a410e` is the commit you want to use as the starting point for that history. Instead, it would be easier if you had a file in which you could store that SHA-1 value under a simple name so you could use that simple name rather than the raw SHA-1 value. -In Git, these simple names are called ``references'' or ``refs''; you can find the files that contain those SHA-1 values in the `.git/refs` directory. +In Git, these simple names are called "`references`" or "`refs`"; you can find the files that contain those SHA-1 values in the `.git/refs` directory. In the current project, this directory contains no files, but it does contain a simple structure: [source,console] diff --git a/book/10-git-internals/sections/transfer-protocols.asc b/book/10-git-internals/sections/transfer-protocols.asc index 9b9e6dec1..2a127ab69 100644 --- a/book/10-git-internals/sections/transfer-protocols.asc +++ b/book/10-git-internals/sections/transfer-protocols.asc @@ -1,12 +1,12 @@ === Transfer Protocols -Git can transfer data between two repositories in two major ways: the ``dumb'' protocol and the ``smart'' protocol. +Git can transfer data between two repositories in two major ways: the "`dumb`" protocol and the "`smart`" protocol. This section will quickly cover how these two main protocols operate. ==== The Dumb Protocol If you're setting up a repository to be served read-only over HTTP, the dumb protocol is likely what will be used. -This protocol is called ``dumb'' because it requires no Git-specific code on the server side during the transport process; the fetch process is a series of HTTP `GET` requests, where the client can assume the layout of the Git repository on the server. +This protocol is called "`dumb`" because it requires no Git-specific code on the server side during the transport process; the fetch process is a series of HTTP `GET` requests, where the client can assume the layout of the Git repository on the server. [NOTE] ==== @@ -243,9 +243,9 @@ After `fetch-pack` connects, `upload-pack` sends back something like this: This is very similar to what `receive-pack` responds with, but the capabilities are different. In addition, it sends back what HEAD points to (`symref=HEAD:refs/heads/master`) so the client knows what to check out if this is a clone. -At this point, the `fetch-pack` process looks at what objects it has and responds with the objects that it needs by sending ``want'' and then the SHA-1 it wants. -It sends all the objects it already has with ``have'' and then the SHA-1. -At the end of this list, it writes ``done'' to initiate the `upload-pack` process to begin sending the packfile of the data it needs: +At this point, the `fetch-pack` process looks at what objects it has and responds with the objects that it needs by sending "`want`" and then the SHA-1 it wants. +It sends all the objects it already has with "`have`" and then the SHA-1. +At the end of this list, it writes "`done`" to initiate the `upload-pack` process to begin sending the packfile of the data it needs: [source] ---- diff --git a/book/A-git-in-other-environments/sections/guis.asc b/book/A-git-in-other-environments/sections/guis.asc index eae5e3690..156ed6afa 100644 --- a/book/A-git-in-other-environments/sections/guis.asc +++ b/book/A-git-in-other-environments/sections/guis.asc @@ -7,7 +7,7 @@ But plain text isn't the best choice for all tasks; sometimes a visual represent It's important to note that different interfaces are tailored for different workflows. Some clients expose only a carefully curated subset of Git functionality, in order to support a specific way of working that the author considers effective. -When viewed in this light, none of these tools can be called ``better'' than any of the others, they're simply more fit for their intended purpose. +When viewed in this light, none of these tools can be called "`better`" than any of the others, they're simply more fit for their intended purpose. Also note that there's nothing these graphical clients can do that the command-line client can't; the command-line is still where you'll have the most power and control when working with your repositories. ==== `gitk` and `git-gui` @@ -59,9 +59,9 @@ At top right is the diff view, which shows the changes for the currently-selecte You can stage individual hunks (or individual lines) by right-clicking in this area. At the bottom right is the message and action area. -Type your message into the text box and click ``Commit'' to do something similar to `git commit`. -You can also choose to amend the last commit by choosing the ``Amend'' radio button, which will update the ``Staged Changes'' area with the contents of the last commit. -Then you can simply stage or unstage some changes, alter the commit message, and click ``Commit'' again to replace the old commit with a new one. +Type your message into the text box and click "`Commit`" to do something similar to `git commit`. +You can also choose to amend the last commit by choosing the "`Amend`" radio button, which will update the "`Staged Changes`" area with the contents of the last commit. +Then you can simply stage or unstage some changes, alter the commit message, and click "`Commit`" again to replace the old commit with a new one. `gitk` and `git-gui` are examples of task-oriented tools. Each of them is tailored for a specific purpose (viewing history and creating commits, respectively), and omit the features not necessary for that task. @@ -80,13 +80,13 @@ image::images/github_mac.png[GitHub for macOS] image::images/github_win.png[GitHub for Windows] They are designed to look and work very much alike, so we'll treat them like a single product in this chapter. -We won't be doing a detailed rundown of these tools (they have their own documentation), but a quick tour of the ``changes'' view (which is where you'll spend most of your time) is in order. +We won't be doing a detailed rundown of these tools (they have their own documentation), but a quick tour of the "`changes`" view (which is where you'll spend most of your time) is in order. -* On the left is the list of repositories the client is tracking; you can add a repository (either by cloning or attaching locally) by clicking the ``+'' icon at the top of this area. +* On the left is the list of repositories the client is tracking; you can add a repository (either by cloning or attaching locally) by clicking the "`+`" icon at the top of this area. * In the center is a commit-input area, which lets you input a commit message, and select which files should be included. On Windows, the commit history is displayed directly below this; on macOS, it's on a separate tab. * On the right is a diff view, which shows what's changed in your working directory, or which changes were included in the selected commit. -* The last thing to notice is the ``Sync'' button at the top-right, which is the primary way you interact over the network. +* The last thing to notice is the "`Sync`" button at the top-right, which is the primary way you interact over the network. [NOTE] ==== @@ -99,7 +99,7 @@ While they're designed to highlight GitHub's service and recommended workflow, t GitHub for Windows can be downloaded from https://windows.github.com[], and GitHub for macOS from https://mac.github.com[]. When the applications are first run, they walk you through all the first-time Git setup, such as configuring your name and email address, and both set up sane defaults for many common configuration options, such as credential caches and CRLF behavior. -Both are ``evergreen'' – updates are downloaded and installed in the background while the applications are open. +Both are "`evergreen`" – updates are downloaded and installed in the background while the applications are open. This helpfully includes a bundled version of Git, which means you probably won't have to worry about manually updating it again. On Windows, the client includes a shortcut to launch PowerShell with Posh-git, which we'll talk more about later in this chapter. @@ -110,14 +110,14 @@ If you already have a local repository, just drag its directory from the Finder ===== Recommended Workflow Once it's installed and configured, you can use the GitHub client for many common Git tasks. -The intended workflow for this tool is sometimes called the ``GitHub Flow.'' +The intended workflow for this tool is sometimes called the "`GitHub Flow.`" We cover this in more detail in <>, but the general gist is that (a) you'll be committing to a branch, and (b) you'll be syncing up with a remote repository fairly regularly. Branch management is one of the areas where the two tools diverge. On macOS, there's a button at the top of the window for creating a new branch: -.``Create Branch'' button on macOS -image::images/branch_widget_mac.png[``Create Branch'' button on macOS] +."`Create Branch`" button on macOS +image::images/branch_widget_mac.png["`Create Branch`" button on macOS] On Windows, this is done by typing the new branch's name in the branch-switching widget: @@ -126,9 +126,9 @@ image::images/branch_widget_win.png[Creating a branch on Windows] Once your branch is created, making new commits is fairly straightforward. Make some changes in your working directory, and when you switch to the GitHub client window, it will show you which files changed. -Enter a commit message, select the files you'd like to include, and click the ``Commit'' button (ctrl-enter or ⌘-enter). +Enter a commit message, select the files you'd like to include, and click the "`Commit`" button (ctrl-enter or ⌘-enter). -The main way you interact with other repositories over the network is through the ``Sync'' feature. +The main way you interact with other repositories over the network is through the "`Sync`" feature. Git internally has separate operations for pushing, fetching, merging, and rebasing, but the GitHub clients collapse all of these into one multi-step feature. Here's what happens when you click the Sync button: diff --git a/book/B-embedding-git/sections/jgit.asc b/book/B-embedding-git/sections/jgit.asc index b8c79499c..9e4161731 100644 --- a/book/B-embedding-git/sections/jgit.asc +++ b/book/B-embedding-git/sections/jgit.asc @@ -93,7 +93,7 @@ There's quite a bit going on here, so let's go through it one section at a time. The first line gets a pointer to the `master` reference. JGit automatically grabs the _actual_ `master` ref, which lives at `refs/heads/master`, and returns an object that lets you fetch information about the reference. You can get the name (`.getName()`), and either the target object of a direct reference (`.getObjectId()`) or the reference pointed to by a symbolic ref (`.getTarget()`). -Ref objects are also used to represent tag refs and objects, so you can ask if the tag is ``peeled,'' meaning that it points to the final target of a (potentially long) string of tag objects. +Ref objects are also used to represent tag refs and objects, so you can ask if the tag is "`peeled,`" meaning that it points to the final target of a (potentially long) string of tag objects. The second line gets the target of the `master` reference, which is returned as an ObjectId instance. ObjectId represents the SHA-1 hash of an object, which might or might not exist in Git's object database. diff --git a/book/B-embedding-git/sections/libgit2.asc b/book/B-embedding-git/sections/libgit2.asc index 00139ca20..9edca885b 100644 --- a/book/B-embedding-git/sections/libgit2.asc +++ b/book/B-embedding-git/sections/libgit2.asc @@ -37,7 +37,7 @@ There's also the `git_repository_open_ext` which includes options for searching, The second chunk of code uses rev-parse syntax (see <> for more on this) to get the commit that HEAD eventually points to. The type returned is a `git_object` pointer, which represents something that exists in the Git object database for a repository. -`git_object` is actually a ``parent'' type for several different kinds of objects; the memory layout for each of the ``child'' types is the same as for `git_object`, so you can safely cast to the right one. +`git_object` is actually a "`parent`" type for several different kinds of objects; the memory layout for each of the "`child`" types is the same as for `git_object`, so you can safely cast to the right one. In this case, `git_object_type(commit)` would return `GIT_OBJ_COMMIT`, so it's safe to cast to a `git_commit` pointer. The next chunk shows how to access the commit's properties. @@ -111,7 +111,7 @@ If you're not a rubyist, we touch on some other bindings in <<_libgit2_bindings> ==== Advanced Functionality Libgit2 has a couple of capabilities that are outside the scope of core Git. -One example is pluggability: Libgit2 allows you to provide custom ``backends'' for several types of operation, so you can store things in a different way than stock Git does. +One example is pluggability: Libgit2 allows you to provide custom "`backends`" for several types of operation, so you can store things in a different way than stock Git does. Libgit2 allows custom backends for configuration, ref storage, and the object database, among other things. Let's take a look at how this works. @@ -135,7 +135,7 @@ error = git_repository_set_odb(repo, odb); // <4> _Note that errors are captured, but not handled. We hope your code is better than ours._ -<1> Initialize an empty object database (ODB) ``frontend,'' which will act as a container for the ``backends'' which are the ones doing the real work. +<1> Initialize an empty object database (ODB) "`frontend,`" which will act as a container for the "`backends`" which are the ones doing the real work. <2> Initialize a custom ODB backend. <3> Add the backend to the frontend. <4> Open a repository, and set it to use our ODB to look up objects. diff --git a/ch03-git-branching.asc b/ch03-git-branching.asc index d1528f224..60d1a1934 100644 --- a/ch03-git-branching.asc +++ b/ch03-git-branching.asc @@ -6,7 +6,7 @@ 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. -Some people refer to Git's branching model as its ``killer feature,'' and it certainly sets Git apart in the VCS community. +Some people refer to Git's branching model as its "`killer feature,`" and it certainly sets Git apart in the VCS community. Why is it so special? The way Git branches is incredibly lightweight, making branching operations nearly instantaneous, and switching back and forth between branches generally just as fast. Unlike many other VCSs, Git encourages workflows that branch and merge often, even multiple times in a day. diff --git a/ch09-git-and-other-systems.asc b/ch09-git-and-other-systems.asc index 7c4c9114b..ac6a1589e 100644 --- a/ch09-git-and-other-systems.asc +++ b/ch09-git-and-other-systems.asc @@ -13,7 +13,7 @@ The second part of this chapter covers how to migrate your project into Git from (((Git as a client))) Git provides such a nice experience for developers that many people have figured out how to use it on their workstation, even if the rest of their team is using an entirely different VCS. -There are a number of these adapters, called ``bridges,'' available. +There are a number of these adapters, called "`bridges,`" available. Here we'll cover the ones you're most likely to run into in the wild. include::book/09-git-and-other-scms/sections/client-svn.asc[] diff --git a/progit.asc b/progit.asc index 30d0c5ea5..8c85ad177 100644 --- a/progit.asc +++ b/progit.asc @@ -1,5 +1,4 @@ -Pro Git -======= += Pro Git Scott Chacon; Ben Straub :doctype: book :docinfo: