diff --git a/book/A-git-in-other-environments/1-git-other-environments.asc b/A-git-in-other-environments.asc similarity index 63% rename from book/A-git-in-other-environments/1-git-other-environments.asc rename to A-git-in-other-environments.asc index f0d972c5a..eacaa52fe 100644 --- a/book/A-git-in-other-environments/1-git-other-environments.asc +++ b/A-git-in-other-environments.asc @@ -1,4 +1,4 @@ -[[_git_in_other_environments]] +[[A-git-in-other-environments]] [appendix] == Git in Other Environments @@ -7,18 +7,18 @@ You can work with local files, connect your repository to others over a network, But the story doesn't end there; Git is usually used as part of a larger ecosystem, and the terminal isn't always the best way to work with it. Now we'll take a look at some of the other kinds of environments where Git can be useful, and how other applications (including yours) work alongside Git. -include::sections/guis.asc[] +include::book/A-git-in-other-environments/sections/guis.asc[] -include::sections/visualstudio.asc[] +include::book/A-git-in-other-environments/sections/visualstudio.asc[] -include::sections/eclipse.asc[] +include::book/A-git-in-other-environments/sections/eclipse.asc[] -include::sections/bash.asc[] +include::book/A-git-in-other-environments/sections/bash.asc[] -include::sections/zsh.asc[] +include::book/A-git-in-other-environments/sections/zsh.asc[] -include::sections/powershell.asc[] +include::book/A-git-in-other-environments/sections/powershell.asc[] === Summary diff --git a/book/B-embedding-git/1-embedding-git.asc b/B-embedding-git-in-your-applications.asc similarity index 71% rename from book/B-embedding-git/1-embedding-git.asc rename to B-embedding-git-in-your-applications.asc index 746d59595..5a59a81c4 100644 --- a/book/B-embedding-git/1-embedding-git.asc +++ b/B-embedding-git-in-your-applications.asc @@ -1,4 +1,4 @@ -[[_embedding_git_in_your_applications]] +[[B-embedding-git-in-your-applications]] [appendix] == Embedding Git in your Applications @@ -7,8 +7,8 @@ Even non-developer applications, such as document editors, could potentially ben If you need to integrate Git with your application, you have essentially three choices: spawning a shell and using the Git command-line tool; Libgit2; and JGit. -include::sections/command-line.asc[] +include::book/B-embedding-git/sections/command-line.asc[] -include::sections/libgit2.asc[] +include::book/B-embedding-git/sections/libgit2.asc[] -include::sections/jgit.asc[] +include::book/B-embedding-git/sections/jgit.asc[] diff --git a/book/C-git-commands/1-git-commands.asc b/C-git-commands.asc similarity index 58% rename from book/C-git-commands/1-git-commands.asc rename to C-git-commands.asc index 383fef1ef..28518d5b5 100644 --- a/book/C-git-commands/1-git-commands.asc +++ b/C-git-commands.asc @@ -1,4 +1,4 @@ -[[_git_commands]] +[[C-git-commands]] [appendix] == Git Commands @@ -22,24 +22,24 @@ There are several files this command will read from and write to so you can set The `git config` command has been used in nearly every chapter of the book. -In <<_getting_started#_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git. +In <> we used it to specify our name, email address and editor preference before we even got started using Git. -In <<_git_basics_chapter#_git_aliases>> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. +In <> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. -In <<_git_branching#_rebasing>> we used it to make `--rebase` the default when you run `git pull`. +In <> we used it to make `--rebase` the default when you run `git pull`. -In <<_git_tools#_credential_caching>> we used it to set up a default store for your HTTP passwords. +In <> we used it to set up a default store for your HTTP passwords. -In <<_customizing_git#_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git. +In <> we showed how to set up smudge and clean filters on content coming in and out of Git. -Finally, basically the entirety of <<_git_config>> is dedicated to the command. +Finally, basically the entirety of <> is dedicated to the command. ==== git help The `git help` command is used to show you all the documentation shipped with Git about any command. While we're giving a rough overview of most of the more popular ones in this appendix, for a full listing of all of the possible options and flags for every command, you can always run `git help `. -We introduced the `git help` command in <<_git_help>> and showed you how to use it to find more information about the `git shell` in <<_git_on_the_server#_setting_up_server>>. +We introduced the `git help` command in <> and showed you how to use it to find more information about the `git shell` in <>. === Getting and Creating Projects @@ -51,13 +51,13 @@ One is to copy it from an existing repository on the network or elsewhere and th To take a directory and turn it into a new Git repository so you can start version controlling it, you can simply run `git init`. -We first introduce this in <<_git_basics_chapter#_getting_a_repo>>, where we show creating a brand new repository to start working with. +We first introduce this in <>, where we show creating a brand new repository to start working with. -We talk briefly about how you can change the default branch from ``master'' in <<_git_branching#_remote_branches>>. +We talk briefly about how you can change the default branch from ``master'' in <>. -We use this command to create an empty bare repository for a server in <<_git_on_the_server#_bare_repo>>. +We use this command to create an empty bare repository for a server in <>. -Finally, we go through some of the details of what it actually does behind the scenes in <<_git_internals#_plumbing_porcelain>>. +Finally, we go through some of the details of what it actually does behind the scenes in <>. ==== git clone @@ -66,13 +66,13 @@ It creates a new directory, goes into it and runs `git init` to make it an empty The `git clone` command is used in dozens of places throughout the book, but we'll just list a few interesting places. -It's basically introduced and explained in <<_git_basics_chapter#_git_cloning>>, where we go through a few examples. +It's basically introduced and explained in <>, where we go through a few examples. -In <<_git_on_the_server#_getting_git_on_a_server>> we look at using the `--bare` option to create a copy of a Git repository with no working directory. +In <> we look at using the `--bare` option to create a copy of a Git repository with no working directory. -In <<_git_tools#_bundling>> we use it to unbundle a bundled Git repository. +In <> we use it to unbundle a bundled Git repository. -Finally, in <<_git_tools#_cloning_submodules>> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler. +Finally, in <> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler. Though it's used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different. @@ -89,13 +89,13 @@ When the `git commit` command is run, by default it only looks at this staging a This command is an incredibly important command in Git and is mentioned or used dozens of times in this book. We'll quickly cover some of the unique uses that can be found. -We first introduce and explain `git add` in detail in <<_git_basics_chapter#_tracking_files>>. +We first introduce and explain `git add` in detail in <>. -We mention how to use it to resolve merge conflicts in <<_git_branching#_basic_merge_conflicts>>. +We mention how to use it to resolve merge conflicts in <>. -We go over using it to interactively stage only specific parts of a modified file in <<_git_tools#_interactive_staging>>. +We go over using it to interactively stage only specific parts of a modified file in <>. -Finally, we emulate it at a low level in <<_git_internals#_tree_objects>>, so you can get an idea of what it's doing behind the scenes. +Finally, we emulate it at a low level in <>, so you can get an idea of what it's doing behind the scenes. ==== git status @@ -103,7 +103,7 @@ The `git status` command will show you the different states of files in your wor Which files are modified and unstaged and which are staged but not yet committed. In its normal form, it also will show you some basic hints on how to move files between these stages. -We first cover `status` in <<_git_basics_chapter#_checking_status>>, both in its basic and simplified forms. +We first cover `status` in <>, both in its basic and simplified forms. While we use it throughout the book, pretty much everything you can do with the `git status` command is covered there. ==== git diff @@ -111,36 +111,36 @@ While we use it throughout the book, pretty much everything you can do with the The `git diff` command is used when you want to see differences between any two trees. This could be the difference between your working environment and your staging area (`git diff` by itself), between your staging area and your last commit (`git diff --staged`), or between two commits (`git diff master branchB`). -We first look at the basic uses of `git diff` in <<_git_basics_chapter#_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged. +We first look at the basic uses of `git diff` in <>, where we show how to see what changes are staged and which are not yet staged. -We use it to look for possible whitespace issues before committing with the `--check` option in <<_distributed_git#_commit_guidelines>>. +We use it to look for possible whitespace issues before committing with the `--check` option in <>. -We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<_distributed_git#_what_is_introduced>>. +We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <>. -We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <<_git_tools#_advanced_merging>>. +We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <>. -Finally, we use it to effectively compare submodule changes with `--submodule` in <<_git_tools#_starting_submodules>>. +Finally, we use it to effectively compare submodule changes with `--submodule` in <>. ==== git difftool The `git difftool` command simply launches an external tool to show you the difference between two trees in case you want to use something other than the built in `git diff` command. -We only briefly mention this in <<_git_basics_chapter#_git_diff_staged>>. +We only briefly mention this in <>. ==== git commit The `git commit` command takes all the file contents that have been staged with `git add` and records a new permanent snapshot in the database and then moves the branch pointer on the current branch up to it. -We first cover the basics of committing in <<_git_basics_chapter#_committing_changes>>. +We first cover the basics of committing in <>. There we also demonstrate how to use the `-a` flag to skip the `git add` step in daily workflows and how to use the `-m` flag to pass a commit message in on the command line instead of firing up an editor. -In <<_git_basics_chapter#_undoing>> we cover using the `--amend` option to redo the most recent commit. +In <> we cover using the `--amend` option to redo the most recent commit. -In <<_git_branching#_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that. +In <>, we go into much more detail about what `git commit` does and why it does it like that. -We looked at how to sign commits cryptographically with the `-S` flag in <<_git_tools#_signing_commits>>. +We looked at how to sign commits cryptographically with the `-S` flag in <>. -Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<_git_internals#_git_commit_objects>>. +Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <>. ==== git reset @@ -148,34 +148,34 @@ The `git reset` command is primarily used to undo things, as you can possibly te It moves around the `HEAD` pointer and optionally changes the `index` or staging area and can also optionally change the working directory if you use `--hard`. This final option makes it possible for this command to lose your work if used incorrectly, so make sure you understand it before using it. -We first effectively cover the simplest use of `git reset` in <<_git_basics_chapter#_unstaging>>, where we use it to unstage a file we had run `git add` on. +We first effectively cover the simplest use of `git reset` in <>, where we use it to unstage a file we had run `git add` on. -We then cover it in quite some detail in <<_git_tools#_git_reset>>, which is entirely devoted to explaining this command. +We then cover it in quite some detail in <>, which is entirely devoted to explaining this command. -We use `git reset --hard` to abort a merge in <<_git_tools#_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. +We use `git reset --hard` to abort a merge in <>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. ==== git rm The `git rm` command is used to remove files from the staging area and working directory for Git. It is similar to `git add` in that it stages a removal of a file for the next commit. -We cover the `git rm` command in some detail in <<_git_basics_chapter#_removing_files>>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. +We cover the `git rm` command in some detail in <>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. -The only other differing use of `git rm` in the book is in <<_git_internals#_removing_objects>> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. +The only other differing use of `git rm` in the book is in <> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. This can be useful for scripting purposes. ==== git mv The `git mv` command is a thin convenience command to move a file and then run `git add` on the new file and `git rm` on the old file. -We only briefly mention this command in <<_git_mv>>. +We only briefly mention this command in <>. ==== git clean The `git clean` command is used to remove unwanted files from your working directory. This could include removing temporary build artifacts or merge conflict files. -We cover many of the options and scenarios in which you might used the clean command in <<_git_clean>>. +We cover many of the options and scenarios in which you might used the clean command in <>. === Branching and Merging @@ -186,48 +186,48 @@ There are just a handful of commands that implement most of the branching and me The `git branch` command is actually something of a branch management tool. It can list the branches you have, create a new branch, delete branches and rename branches. -Most of <<_git_branching#_git_branching>> is dedicated to the `branch` command and it's used throughout the entire chapter. -We first introduce it in <<_git_branching#_create_new_branch>> and we go through most of its other features (listing and deleting) in <<_git_branching#_branch_management>>. +Most of <> is dedicated to the `branch` command and it's used throughout the entire chapter. +We first introduce it in <> and we go through most of its other features (listing and deleting) in <>. -In <<_git_branching#_tracking_branches>> we use the `git branch -u` option to set up a tracking branch. +In <> we use the `git branch -u` option to set up a tracking branch. -Finally, we go through some of what it does in the background in <<_git_internals#_git_refs>>. +Finally, we go through some of what it does in the background in <>. ==== git checkout The `git checkout` command is used to switch branches and check content out into your working directory. -We first encounter the command in <<_git_branching#_switching_branches>> along with the `git branch` command. +We first encounter the command in <> along with the `git branch` command. -We see how to use it to start tracking branches with the `--track` flag in <<_git_branching#_tracking_branches>>. +We see how to use it to start tracking branches with the `--track` flag in <>. -We use it to reintroduce file conflicts with `--conflict=diff3` in <<_git_tools#_checking_out_conflicts>>. +We use it to reintroduce file conflicts with `--conflict=diff3` in <>. -We go into closer detail on its relationship with `git reset` in <<_git_tools#_git_reset>>. +We go into closer detail on its relationship with `git reset` in <>. -Finally, we go into some implementation detail in <<_git_internals#_the_head>>. +Finally, we go into some implementation detail in <>. ==== git merge The `git merge` tool is used to merge one or more branches into the branch you have checked out. It will then advance the current branch to the result of the merge. -The `git merge` command was first introduced in <<_git_branching#_basic_branching>>. +The `git merge` command was first introduced in <>. Though it is used in various places in the book, there are very few variations of the `merge` command -- generally just `git merge ` with the name of the single branch you want to merge in. -We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <<_distributed_git#_public_project>>. +We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <>. -We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <<_git_tools#_advanced_merging>>. +We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <>. -We learned how to verify signatures before merging if your project is using GPG signing in <<_git_tools#_signing_commits>>. +We learned how to verify signatures before merging if your project is using GPG signing in <>. -Finally, we learned about Subtree merging in <<_git_tools#_subtree_merge>>. +Finally, we learned about Subtree merging in <>. ==== git mergetool The `git mergetool` command simply launches an external merge helper in case you have issues with a merge in Git. -We mention it quickly in <<_git_branching#_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<_customizing_git#_external_merge_tools>>. +We mention it quickly in <> and go into detail on how to implement your own external merge tool in <>. ==== git log @@ -237,37 +237,37 @@ It is also often used to show differences between two or more branches at the co This command is used in nearly every chapter of the book to demonstrate the history of a project. -We introduce the command and cover it in some depth in <<_git_basics_chapter#_viewing_history>>. +We introduce the command and cover it in some depth in <>. There we look at the `-p` and `--stat` option to get an idea of what was introduced in each commit and the `--pretty` and `--oneline` options to view the history more concisely, along with some simple date and author filtering options. -In <<_git_branching#_create_new_branch>> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. +In <> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. -In <<_distributed_git#_private_team>> and <<_git_tools#_commit_ranges>> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. -In <<_git_tools#_commit_ranges>> we go through this fairly extensively. +In <> and <> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. +In <> we go through this fairly extensively. -In <<_git_tools#_merge_log>> and <<_git_tools#_triple_dot>> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. -In <<_git_tools#_merge_log>> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. +In <> and <> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. +In <> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. -In <<_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. +In <> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. -In <<_git_tools#_searching>> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. +In <> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. -In <<_git_tools#_signing_commits>> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. +In <> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. ==== git stash The `git stash` command is used to temporarily store uncommitted work in order to clean out your working directory without having to commit unfinished work on a branch. -This is basically entirely covered in <<_git_tools#_git_stashing>>. +This is basically entirely covered in <>. ==== git tag The `git tag` command is used to give a permanent bookmark to a specific point in the code history. Generally this is used for things like releases. -This command is introduced and covered in detail in <<_git_basics_chapter#_git_tagging>> and we use it in practice in <<_distributed_git#_tagging_releases>>. +This command is introduced and covered in detail in <> and we use it in practice in <>. -We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<_git_tools#_signing>>. +We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <>. === Sharing and Updating Projects @@ -279,45 +279,45 @@ When you are ready to share your work or pull changes from elsewhere, there are The `git fetch` command communicates with a remote repository and fetches down all the information that is in that repository that is not in your current one and stores it in your local database. -We first look at this command in <<_git_basics_chapter#_fetching_and_pulling>> and we continue to see examples of it use in <<_git_branching#_remote_branches>>. +We first look at this command in <> and we continue to see examples of it use in <>. -We also use it in several of the examples in <<_distributed_git#_contributing_project>>. +We also use it in several of the examples in <>. -We use it to fetch a single specific reference that is outside of the default space in <<_github#_pr_refs>> and we see how to fetch from a bundle in <<_git_tools#_bundling>>. +We use it to fetch a single specific reference that is outside of the default space in <> and we see how to fetch from a bundle in <>. -We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<_git_internals#_refspec>>. +We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <>. ==== git pull The `git pull` command is basically a combination of the `git fetch` and `git merge` commands, where Git will fetch from the remote you specify and then immediately try to merge it into the branch you're on. -We introduce it quickly in <<_git_basics_chapter#_fetching_and_pulling>> and show how to see what it will merge if you run it in <<_git_basics_chapter#_inspecting_remote>>. +We introduce it quickly in <> and show how to see what it will merge if you run it in <>. -We also see how to use it to help with rebasing difficulties in <<_git_branching#_rebase_rebase>>. +We also see how to use it to help with rebasing difficulties in <>. -We show how to use it with a URL to pull in changes in a one-off fashion in <<_distributed_git#_checking_out_remotes>>. +We show how to use it with a URL to pull in changes in a one-off fashion in <>. -Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <<_git_tools#_signing_commits>>. +Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <>. ==== git push The `git push` command is used to communicate with another repository, calculate what your local database has that the remote one does not, and then pushes the difference into the other repository. It requires write access to the other repository and so normally is authenticated somehow. -We first look at the `git push` command in <<_git_basics_chapter#_pushing_remotes>>. +We first look at the `git push` command in <>. Here we cover the basics of pushing a branch to a remote repository. -In <<_git_branching#_pushing_branches>> we go a little deeper into pushing specific branches and in <<_git_branching#_tracking_branches>> we see how to set up tracking branches to automatically push to. -In <<_git_branching#_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`. +In <> we go a little deeper into pushing specific branches and in <> we see how to set up tracking branches to automatically push to. +In <> we use the `--delete` flag to delete a branch on the server with `git push`. -Throughout <<_distributed_git#_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes. +Throughout <> we see several examples of using `git push` to share work on branches through multiple remotes. -We see how to use it to share tags that you have made with the `--tags` option in <<_git_basics_chapter#_sharing_tags>>. +We see how to use it to share tags that you have made with the `--tags` option in <>. -In <<_git_tools#_publishing_submodules>> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. +In <> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. -In <<_customizing_git#_other_client_hooks>> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. +In <> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. -Finally, in <<_git_internals#_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used. +Finally, in <> we look at pushing with a full refspec instead of the general shortcuts that are normally used. This can help you be very specific about what work you wish to share. ==== git remote @@ -326,7 +326,7 @@ The `git remote` command is a management tool for your record of remote reposito 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 <<_git_basics_chapter#_remote_repos>>, including listing, adding, removing and renaming them. +This command is covered in detail in <>, including listing, adding, removing and renaming them. It is used in nearly every subsequent chapter in the book too, but always in the standard `git remote add ` format. @@ -334,7 +334,7 @@ It is used in nearly every subsequent chapter in the book too, but always in the The `git archive` command is used to create an archive file of a specific snapshot of the project. -We use `git archive` to create a tarball of a project for sharing in <<_distributed_git#_preparing_release>>. +We use `git archive` to create a tarball of a project for sharing in <>. ==== git submodule @@ -342,7 +342,7 @@ The `git submodule` command is used to manage external repositories within a nor This could be for libraries or other types of shared resources. The `submodule` command has several sub-commands (`add`, `update`, `sync`, etc) for managing these resources. -This command is only mentioned and entirely covered in <<_git_tools#_git_submodules>>. +This command is only mentioned and entirely covered in <>. === Inspection and Comparison @@ -351,25 +351,25 @@ This command is only mentioned and entirely covered in <<_git_tools#_git_submodu The `git show` command can show a Git object in a simple and human readable way. Normally you would use this to show the information about a tag or a commit. -We first use it to show annotated tag information in <<_git_basics_chapter#_annotated_tags>>. +We first use it to show annotated tag information in <>. -Later we use it quite a bit in <<_git_tools#_revision_selection>> to show the commits that our various revision selections resolve to. +Later we use it quite a bit in <> to show the commits that our various revision selections resolve to. -One of the more interesting things we do with `git show` is in <<_git_tools#_manual_remerge>> to extract specific file contents of various stages during a merge conflict. +One of the more interesting things we do with `git show` is in <> to extract specific file contents of various stages during a merge conflict. ==== git shortlog The `git shortlog` command is used to summarize the output of `git log`. It will take many of the same options that the `git log` command will but instead of listing out all of the commits it will present a summary of the commits grouped by author. -We showed how to use it to create a nice changelog in <<_distributed_git#_the_shortlog>>. +We showed how to use it to create a nice changelog in <>. ==== git describe The `git describe` command is used to take anything that resolves to a commit and produces a string that is somewhat human-readable and will not change. It's a way to get a description of a commit that is as unambiguous as a commit SHA-1 but more understandable. -We use `git describe` in <<_distributed_git#_build_number>> and <<_distributed_git#_preparing_release>> to get a string to name our release file after. +We use `git describe` in <> and <> to get a string to name our release file after. === Debugging @@ -381,20 +381,20 @@ This ranges from figuring out where something was introduced to figuring out who The `git bisect` tool is an incredibly helpful debugging tool used to find which specific commit was the first one to introduce a bug or problem by doing an automatic binary search. -It is fully covered in <<_git_tools#_binary_search>> and is only mentioned in that section. +It is fully covered in <> and is only mentioned in that section. ==== git blame The `git blame` command annotates the lines of any file with which commit was the last one to introduce a change to each line of the file and what person authored that commit. This is helpful in order to find the person to ask for more information about a specific section of your code. -It is covered in <<_git_tools#_file_annotation>> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. ==== git grep The `git grep` command can help you find any string or regular expression in any of the files in your source code, even older versions of your project. -It is covered in <<_git_grep>> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. === Patching @@ -406,27 +406,27 @@ These commands help you manage your branches in this manner. The `git cherry-pick` command is used to take the change introduced in a single Git commit and try to re-introduce it as a new commit on the branch you're currently on. This can be useful to only take one or two commits from a branch individually rather than merging in the branch which takes all the changes. -Cherry picking is described and demonstrated in <<_distributed_git#_rebase_cherry_pick>>. +Cherry picking is described and demonstrated in <>. ==== git rebase The `git rebase` command is basically an automated `cherry-pick`. It determines a series of commits and then cherry-picks them one by one in the same order somewhere else. -Rebasing is covered in detail in <<_git_branching#_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public. +Rebasing is covered in detail in <>, including covering the collaborative issues involved with rebasing branches that are already public. -We use it in practice during an example of splitting your history into two separate repositories in <<_git_tools#_replace>>, using the `--onto` flag as well. +We use it in practice during an example of splitting your history into two separate repositories in <>, using the `--onto` flag as well. -We go through running into a merge conflict during rebasing in <<_git_tools#_rerere>>. +We go through running into a merge conflict during rebasing in <>. -We also use it in an interactive scripting mode with the `-i` option in <<_git_tools#_changing_multiple>>. +We also use it in an interactive scripting mode with the `-i` option in <>. ==== git revert The `git revert` command is essentially a reverse `git cherry-pick`. It creates a new commit that applies the exact opposite of the change introduced in the commit you're targeting, essentially undoing or reverting it. -We use this in <<_git_tools#_reverse_commit>> to undo a merge commit. +We use this in <> to undo a merge commit. === Email @@ -438,43 +438,43 @@ Git has a number of tools built into it that help make this process easier, from The `git apply` command applies a patch created with the `git diff` or even GNU diff command. It is similar to what the `patch` command might do with a few small differences. -We demonstrate using it and the circumstances in which you might do so in <<_distributed_git#_patches_from_email>>. +We demonstrate using it and the circumstances in which you might do so in <>. ==== git am The `git am` command is used to apply patches from an email inbox, specifically one that is mbox formatted. This is useful for receiving patches over email and applying them to your project easily. -We covered usage and workflow around `git am` in <<_git_am>> including using the `--resolved`, `-i` and `-3` options. +We covered usage and workflow around `git am` in <> including using the `--resolved`, `-i` and `-3` options. -There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<_customizing_git#_email_hooks>>. +There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <>. -We also use it to apply patch formatted GitHub Pull Request changes in <<_github#_email_notifications>>. +We also use it to apply patch formatted GitHub Pull Request changes in <>. ==== git format-patch The `git format-patch` command is used to generate a series of patches in mbox format that you can use to send to a mailing list properly formatted. -We go through an example of contributing to a project using the `git format-patch` tool in <<_distributed_git#_project_over_email>>. +We go through an example of contributing to a project using the `git format-patch` tool in <>. ==== git imap-send The `git imap-send` command uploads a mailbox generated with `git format-patch` into an IMAP drafts folder. -We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<_distributed_git#_project_over_email>>. +We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <>. ==== git send-email The `git send-email` command is used to send patches that are generated with `git format-patch` over email. -We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<_distributed_git#_project_over_email>>. +We go through an example of contributing to a project by sending patches with the `git send-email` tool in <>. ==== git request-pull The `git request-pull` command is simply used to generate an example message body to email to someone. If you have a branch on a public server and want to let someone know how to integrate those changes without sending the patches over email, you can run this command and send the output to the person you want to pull the changes in. -We demonstrate how to use `git request-pull` to generate a pull message in <<_distributed_git#_public_project>>. +We demonstrate how to use `git request-pull` to generate a pull message in <>. === External Systems @@ -485,13 +485,13 @@ Git comes with a few commands to integrate with other version control systems. The `git svn` command is used to communicate with the Subversion version control system as a client. This means you can use Git to checkout from and commit to a Subversion server. -This command is covered in depth in <<_git_svn>>. +This command is covered in depth in <>. ==== git fast-import For other version control systems or importing from nearly any format, you can use `git fast-import` to quickly map the other format to something Git can easily record. -This command is covered in depth in <<_git_and_other_systems#_custom_importer>>. +This command is covered in depth in <>. === Administration @@ -502,40 +502,40 @@ If you're administering a Git repository or need to fix something in a big way, 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 <<_git_gc>>. +We go over some examples of this in <>. ==== git fsck The `git fsck` command is used to check the internal database for problems or inconsistencies. -We only quickly use this once in <<_git_internals#_data_recovery>> to search for dangling objects. +We only quickly use this once in <> to search for dangling objects. ==== git reflog The `git reflog` command goes through a log of where all the heads of your branches have been as you work to find commits you may have lost through rewriting histories. -We cover this command mainly in <<_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. +We cover this command mainly in <>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. -We also go through a practical example of recovering such a lost branch in <<_git_internals#_data_recovery>>. +We also go through a practical example of recovering such a lost branch in <>. ==== git filter-branch The `git filter-branch` command is used to rewrite loads of commits according to certain patterns, like removing a file everywhere or filtering the entire repository down to a single subdirectory for extracting a project. -In <<_git_tools#_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. +In <> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. -In <<_git_and_other_systems#_git_p4>> and <<_git_and_other_systems#_git_tfs>> we use it to fix up imported external repositories. +In <> and <> we use it to fix up imported external repositories. === Plumbing Commands There were also quite a number of lower level plumbing commands that we encountered in the book. -The first one we encounter is `ls-remote` in <<_github#_pr_refs>> which we use to look at the raw references on the server. +The first one we encounter is `ls-remote` in <> which we use to look at the raw references on the server. -We use `ls-files` in <<_git_tools#_manual_remerge>>, <<_git_tools#_rerere>> and <<_git_tools#_the_index>> to take a more raw look at what your staging area looks like. +We use `ls-files` in <>, <> and <> to take a more raw look at what your staging area looks like. -We also mention `rev-parse` in <<_git_tools#_branch_references>> to take just about any string and turn it into an object SHA-1. +We also mention `rev-parse` in <> to take just about any string and turn it into an object SHA-1. -However, most of the low level plumbing commands we cover are in <<_git_internals#_git_internals>>, which is more or less what the chapter is focused on. +However, most of the low level plumbing commands we cover are in <>, which is more or less what the chapter is focused on. We tried to avoid use of them throughout most of the rest of the book. diff --git a/Gemfile b/Gemfile index d7bd91223..4ecffb4fd 100644 --- a/Gemfile +++ b/Gemfile @@ -1,13 +1,13 @@ source 'https://rubygems.org' gem 'rake' -gem 'asciidoctor', '1.5.0' +gem 'asciidoctor', '1.5.6.1' gem 'json' gem 'awesome_print' -gem 'asciidoctor-epub3', '1.0.0.alpha.2' -gem 'asciidoctor-pdf', '1.5.0.alpha.5' +gem 'asciidoctor-epub3', :git => 'https://github.com/asciidoctor/asciidoctor-epub3' +gem 'asciidoctor-pdf', '1.5.0.alpha.16' gem 'coderay' gem 'pygments.rb' diff --git a/book/01-introduction/sections/basics.asc b/book/01-introduction/sections/basics.asc index 70ad4dd6f..cd08d19bd 100644 --- a/book/01-introduction/sections/basics.asc +++ b/book/01-introduction/sections/basics.asc @@ -26,7 +26,7 @@ image::images/snapshots.png[Git stores data as snapshots of the project over tim This is an important distinction between Git and nearly all other VCSs. It makes Git reconsider almost every aspect of version control that most other systems copied from the previous generation. This makes Git more like a mini filesystem with some incredibly powerful tools built on top of it, rather than simply a VCS. -We'll explore some of the benefits you gain by thinking of your data this way when we cover Git branching in <<_git_branching#_git_branching>>. +We'll explore some of the benefits you gain by thinking of your data this way when we cover Git branching in <>. ==== Nearly Every Operation Is Local @@ -71,7 +71,7 @@ It is hard to get the system to do anything that is not undoable or to make it e As with any VCS, you can lose or mess up changes you haven't committed yet, but after you commit a snapshot into Git, it is very difficult to lose, especially if you regularly push your database to another repository. This makes using Git a joy because we know we can experiment without the danger of severely screwing things up. -For a more in-depth look at how Git stores its data and how you can recover data that seems lost, see <<_git_basics_chapter#_undoing>>. +For a more in-depth look at how Git stores its data and how you can recover data that seems lost, see <>. ==== The Three States @@ -105,4 +105,4 @@ The basic Git workflow goes something like this: If a particular version of a file is in the Git directory, it's considered committed. If it has been modified and was added to the staging area, it is staged. And if it was changed since it was checked out but has not been staged, it is modified. -In <<_git_basics_chapter#_git_basics_chapter>>, you'll learn more about these states and how you can either take advantage of them or skip the staged part entirely. +In <>, you'll learn more about these states and how you can either take advantage of them or skip the staged part entirely. diff --git a/book/01-introduction/sections/history.asc b/book/01-introduction/sections/history.asc index 4f24ca8fa..dd1d096f9 100644 --- a/book/01-introduction/sections/history.asc +++ b/book/01-introduction/sections/history.asc @@ -17,4 +17,4 @@ Some of the goals of the new system were as follows: * Able to handle large projects like the Linux kernel efficiently (speed and data size) Since its birth in 2005, Git has evolved and matured to be easy to use and yet retain these initial qualities. -It's amazingly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<_git_branching#_git_branching>>). +It's amazingly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <>). diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc index b569e8b7c..c3c29ee95 100644 --- a/book/02-git-basics/sections/getting-a-repository.asc +++ b/book/02-git-basics/sections/getting-a-repository.asc @@ -38,7 +38,7 @@ $ git init This creates a new subdirectory named `.git` that contains all of your necessary repository files -- a Git repository skeleton. At this point, nothing in your project is tracked yet. -(See <<_git_internals#_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)(((git commands, init))) +(See <> for more information about exactly what files are contained in the `.git` directory you just created.)(((git commands, init))) If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit. You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`: @@ -60,7 +60,7 @@ If you want to get a copy of an existing Git repository -- for example, a projec If you're familiar with other VCS systems such as Subversion, you'll notice that the command is "clone" and not "checkout". This is an important distinction -- instead of getting just a working copy, Git receives a full copy of nearly all data that the server has. Every version of every file for the history of the project is pulled down by default when you run `git clone`. -In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there -- see <<_git_on_the_server#_getting_git_on_a_server>> for more details). +In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there -- see <> for more details). You clone a repository with `git clone `.(((git commands, clone))) For example, if you want to clone the Git linkable library called `libgit2`, you can do so like this: @@ -84,4 +84,4 @@ That command does the same thing as the previous one, but the target directory i Git has a number of different transfer protocols you can use. The previous example uses the `https://` protocol, but you may also see `git://` or `user@server:path/to/repo.git`, which uses the SSH transfer protocol. -<<_git_on_the_server#_getting_git_on_a_server>> will introduce all of the available options the server can set up to access your Git repository and the pros and cons of each. +<> will introduce all of the available options the server can set up to access your Git repository and the pros and cons of each. diff --git a/book/02-git-basics/sections/recording-changes.asc b/book/02-git-basics/sections/recording-changes.asc index 5fbdc5e0c..a778c9225 100644 --- a/book/02-git-basics/sections/recording-changes.asc +++ b/book/02-git-basics/sections/recording-changes.asc @@ -34,7 +34,7 @@ This means you have a clean working directory -- in other words, none of your tr Git also doesn't see any untracked files, or they would be listed here. Finally, the command tells you which branch you're on and informs you that it has not diverged from the same branch on the server. For now, that branch is always ``master'', which is the default; you won't worry about it here. -<<_git_branching#_git_branching>> will go over branches and references in detail. +<> will go over branches and references in detail. Let's say you add a new file to your project, a simple `README` file. If the file didn't exist before, and you run `git status`, you see your untracked file like so: @@ -420,7 +420,7 @@ $ git commit ---- Doing so launches your editor of choice. -(This is set by your shell's `EDITOR` environment variable -- usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started#_getting_started>>).(((editor, changing default)))(((git commands, config))) +(This is set by your shell's `EDITOR` environment variable -- usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <>).(((editor, changing default)))(((git commands, config))) The editor displays the following text (this example is a Vim screen): diff --git a/book/02-git-basics/sections/remotes.asc b/book/02-git-basics/sections/remotes.asc index 656f7bdc5..a150fbf6b 100644 --- a/book/02-git-basics/sections/remotes.asc +++ b/book/02-git-basics/sections/remotes.asc @@ -67,7 +67,7 @@ origin git@github.com:mojombo/grit.git (push) This means we can pull contributions from any of these users pretty easily. We may additionally have permission to push to one or more of these, though we can't tell that here. -Notice that these remotes use a variety of protocols; we'll cover more about this in <<_git_on_the_server#_getting_git_on_a_server>>. +Notice that these remotes use a variety of protocols; we'll cover more about this in <>. ==== Adding Remote Repositories @@ -103,7 +103,7 @@ From https://github.com/paulboone/ticgit ---- Paul's master branch is now accessible locally as `pb/master` -- you can merge it into one of your branches, or you can check out a local branch at that point if you want to inspect it. -(We'll go over what branches are and how to use them in much more detail in <<_git_branching#_git_branching>>.) +(We'll go over what branches are and how to use them in much more detail in <>.) [[_fetching_and_pulling]] ==== Fetching and Pulling from Your Remotes @@ -123,7 +123,7 @@ So, `git fetch origin` fetches any new work that has been pushed to that server It's important to note that the `git fetch` command 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. -If your current branch is set up to track a remote branch (see the next section and <<_git_branching#_git_branching>> for more information), you can use the `git pull` command to automatically fetch and then merge that remote branch into your current branch.(((git commands, pull))) +If your current branch is set up to track a remote branch (see the next section and <> for more information), you can use the `git pull` command to automatically fetch and then merge that remote branch into your current branch.(((git commands, pull))) This may be an easier or more comfortable workflow for you; and by default, the `git clone` command automatically sets up your local master branch to track the remote master branch (or whatever the default branch is called) on the server you cloned from. Running `git pull` generally fetches data from the server you originally cloned from and automatically tries to merge it into the code you're currently working on. @@ -142,7 +142,7 @@ $ git push origin master This command works only if you cloned from a server to which you have write access and if nobody has pushed in the meantime. If you and someone else clone at the same time and they push upstream and then you push upstream, your push will rightly be rejected. You'll have to fetch their work first and incorporate it into yours before you'll be allowed to push. -See <<_git_branching#_git_branching>> for more detailed information on how to push to remote servers. +See <> for more detailed information on how to push to remote servers. [[_inspecting_remote]] ==== Inspecting a Remote diff --git a/book/02-git-basics/sections/undoing.asc b/book/02-git-basics/sections/undoing.asc index 5cf9af9aa..dd75fb7f7 100644 --- a/book/02-git-basics/sections/undoing.asc +++ b/book/02-git-basics/sections/undoing.asc @@ -92,7 +92,7 @@ However, in the scenario described above, the file in your working directory is ===== For now this magic invocation is all you need to know about the `git reset` command. -We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<_git_tools#_git_reset>>. +We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <>. ==== Unmodifying a Modified File @@ -134,8 +134,8 @@ Any changes you made to that file are gone -- Git just copied another file over Don't ever use this command unless you absolutely know that you don't want the file. ===== -If you would like to keep the changes you've made to that file but still need to get it out of the way for now, we'll go over stashing and branching in <<_git_branching#_git_branching>>; these are generally better ways to go. +If you would like to keep the changes you've made to that file but still need to get it out of the way for now, we'll go over stashing and branching in <>; these are generally better ways to go. Remember, anything that is _committed_ in Git can almost always be recovered. -Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<_git_internals#_data_recovery>> for data recovery). +Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <> for data recovery). However, anything you lose that was never committed is likely never to be seen again. diff --git a/book/02-git-basics/sections/viewing-history.asc b/book/02-git-basics/sections/viewing-history.asc index 8f31c2df8..8c5be5e49 100644 --- a/book/02-git-basics/sections/viewing-history.asc +++ b/book/02-git-basics/sections/viewing-history.asc @@ -182,7 +182,7 @@ a11bef0 - Scott Chacon, 6 years ago : first commit You may be wondering what the difference is between _author_ and _committer_. The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit -- you as the author, and the core member as the committer. -We'll cover this distinction a bit more in <<_distributed_git#_distributed_git>>. +We'll cover this distinction a bit more in <>. The `oneline` and `format` options are particularly useful with another `log` option called `--graph`. This option adds a nice little ASCII graph showing your branch and merge history: 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 c22a09f28..23c06ff5e 100644 --- a/book/03-git-branching/sections/basic-branching-and-merging.asc +++ b/book/03-git-branching/sections/basic-branching-and-merging.asc @@ -62,7 +62,7 @@ All you have to do is switch back to your `master` branch. However, before you do that, note that if your working directory or staging area has uncommitted changes that conflict with the branch you're checking out, Git won't let you switch branches. It's best to have a clean working state when you switch branches. -There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<_git_tools#_git_stashing>>. +There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <>. For now, let's assume you've committed all your changes, so you can switch back to your `master` branch: [source,console] @@ -273,7 +273,7 @@ Just type the name of the tool you'd rather use. [NOTE] ==== -If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<_git_tools#_advanced_merging>>. +If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <>. ==== After you exit the merge tool, Git asks you if the merge was successful. diff --git a/book/03-git-branching/sections/nutshell.asc b/book/03-git-branching/sections/nutshell.asc index 767e7772b..169583517 100644 --- a/book/03-git-branching/sections/nutshell.asc +++ b/book/03-git-branching/sections/nutshell.asc @@ -3,13 +3,13 @@ To really understand the way Git does branching, we need to take a step back and examine how Git stores its data. -As you may remember from <<_getting_started#_getting_started>>, Git doesn't store data as a series of changesets or differences, but instead as a series of snapshots. +As you may remember from <>, Git doesn't store data as a series of changesets or differences, but instead as a series of snapshots. When you make a commit, Git stores a commit object that contains a pointer to the snapshot of the content you staged. This object also contains the author's name and email, the message that you typed, and pointers to the commit or commits that directly came before this commit (its parent or parents): zero parents for the initial commit, one parent for a normal commit, and multiple parents for a commit that results from a merge of two or more branches. To visualize this, let's assume that you have a directory containing three files, and you stage them all and commit. -Staging the files computes a checksum for each one (the SHA-1 hash we mentioned in <<_getting_started#_getting_started>>), stores that version of the file in the Git repository (Git refers to them as blobs), and adds that checksum to the staging area: +Staging the files computes a checksum for each one (the SHA-1 hash we mentioned in <>), stores that version of the file in the Git repository (Git refers to them as blobs), and adds that checksum to the staging area: [source,console] ---- diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc index ed0d28ac6..19ceef421 100644 --- a/book/03-git-branching/sections/remote-branches.asc +++ b/book/03-git-branching/sections/remote-branches.asc @@ -44,7 +44,7 @@ image::images/remote-branches-3.png[`git fetch` updates your remote references.] To demonstrate having multiple remote servers and what remote branches for those remote projects look like, let's assume you have another internal Git server that is used only for development by one of your sprint teams. This server is at `git.team1.ourcompany.com`. -You can add it as a new remote reference to the project you're currently working on by running the `git remote add` command as we covered in <<_git_basics_chapter#_git_basics_chapter>>. +You can add it as a new remote reference to the project you're currently working on by running the `git remote add` command as we covered in <>. Name this remote `teamone`, which will be your shortname for that whole URL. .Adding another server as a remote @@ -81,7 +81,7 @@ 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.'' -We'll go over the `refs/heads/` part in detail in <<_git_internals#_git_internals>>, but you can generally leave it off. +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 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. @@ -95,7 +95,7 @@ By default it will prompt you on the terminal for this information so the server 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 <<_git_tools#_credential_caching>>. +For more information on the various credential caching options available, see <>. ==== The next time one of your collaborators fetches from the server, they will get a reference to where the server's version of `serverfix` is under the remote branch `origin/serverfix`: diff --git a/book/03-git-branching/sections/workflows.asc b/book/03-git-branching/sections/workflows.asc index 79fa76bb9..dae38d5c6 100644 --- a/book/03-git-branching/sections/workflows.asc +++ b/book/03-git-branching/sections/workflows.asc @@ -57,7 +57,7 @@ Your history then looks like this: .History after merging `dumbidea` and `iss91v2` image::images/topic-branches-2.png[History after merging `dumbidea` and `iss91v2`.] -We will go into more detail about the various possible workflows for your Git project in <<_distributed_git#_distributed_git>>, so before you decide which branching scheme your next project will use, be sure to read that chapter. +We will go into more detail about the various possible workflows for your Git project in <>, so before you decide which branching scheme your next project will use, be sure to read that chapter. It's important to remember when you're doing all this that these branches are completely local. When you're branching and merging, everything is being done only in your Git repository -- no server communication is happening. diff --git a/book/04-git-server/sections/hosted.asc b/book/04-git-server/sections/hosted.asc index 22edf5fb8..6828f64e5 100644 --- a/book/04-git-server/sections/hosted.asc +++ b/book/04-git-server/sections/hosted.asc @@ -7,4 +7,4 @@ Even if you set up and run your own server internally, you may still want to use These days, you have a huge number of hosting options to choose from, each with different advantages and disadvantages. To see an up-to-date list, check out the GitHosting page on the main Git wiki at https://git.wiki.kernel.org/index.php/GitHosting[] -We'll cover using GitHub in detail in <<_github#_github>>, as it is the largest Git host out there and you may need to interact with projects hosted on it in any case, but there are dozens more to choose from should you not want to set up your own Git server. +We'll cover using GitHub in detail in <>, as it is the largest Git host out there and you may need to interact with projects hosted on it in any case, but there are dozens more to choose from should you not want to set up your own Git server. diff --git a/book/04-git-server/sections/protocols.asc b/book/04-git-server/sections/protocols.asc index f8387bc40..a3f5305e0 100644 --- a/book/04-git-server/sections/protocols.asc +++ b/book/04-git-server/sections/protocols.asc @@ -29,7 +29,7 @@ $ git clone file:///srv/git/project.git Git operates slightly differently if you explicitly specify `file://` at the beginning of the URL. If you just specify the path, Git tries to use hardlinks or directly copy the files it needs. If you specify `file://`, Git fires up the processes that it normally uses to transfer data over a network, which is generally much less efficient. -The main reason to specify the `file://` prefix is if you want a clean copy of the repository with extraneous references or objects left out -- generally after an import from another VCS or something similar (see <<_git_internals#_git_internals>> for maintenance tasks). +The main reason to specify the `file://` prefix is if you want a clean copy of the repository with extraneous references or objects left out -- generally after an import from another VCS or something similar (see <> for maintenance tasks). We'll use the normal path here because doing so is almost always faster. To add a local repository to an existing Git project, you can run something like this: @@ -46,7 +46,7 @@ Then, you can push to and pull from that remote via your new remote name `local_ The pros of file-based repositories are that they're simple and they use existing file permissions and network access. If you already have a shared filesystem to which your whole team has access, setting up a repository is very easy. You stick the bare repository copy somewhere everyone has shared access to and set the read/write permissions as you would for any other shared directory. -We'll discuss how to export a bare repository copy for this purpose in <<_git_on_the_server#_getting_git_on_a_server>>. +We'll discuss how to export a bare repository copy for this purpose in <>. This is also a nice option for quickly grabbing work from someone else's working repository. If you and a co-worker are working on the same project and they want you to check something out, running a command like `git pull /home/john/project` is often easier than them pushing to a remote server and you subsequently fetching from it. @@ -90,7 +90,7 @@ In fact, for services like GitHub, the URL you use to view the repository online If the server does not respond with a Git HTTP smart service, the Git client will try to fall back to the simpler _Dumb_ HTTP protocol. The Dumb protocol expects the bare Git repository to be served like normal files from the web server. The beauty of Dumb HTTP is the simplicity of setting it up. -Basically, all you have to do is put a bare Git repository under your HTTP document root and set up a specific `post-update` hook, and you're done (See <<_customizing_git#_git_hooks>>). +Basically, all you have to do is put a bare Git repository under your HTTP document root and set up a specific `post-update` hook, and you're done (See <>). At that point, anyone who can access the web server under which you put the repository can also clone your repository. To allow read access to your repository over HTTP, do something like this: @@ -113,7 +113,7 @@ $ git clone https://example.com/gitproject.git ---- In this particular case, we're using the `/var/www/htdocs` path that is common for Apache setups, but you can use any static web server -- just put the bare repository in its path. -The Git data is served as basic static files (see the <<_git_internals#_git_internals>> chapter for details about exactly how it's served). +The Git data is served as basic static files (see the <> chapter for details about exactly how it's served). Generally you would either choose to run a read/write Smart HTTP server or simply have the files accessible as read-only in the Dumb manner. It's rare to run a mix of the two services. @@ -138,7 +138,7 @@ Other than that, there is very little advantage that other protocols have over S If you're using HTTP for authenticated pushing, providing your credentials is sometimes more complicated than using keys over SSH. There are, however, several credential caching tools you can use, including Keychain access on macOS and Credential Manager on Windows, to make this pretty painless. -Read <<_git_tools#_credential_caching>> to see how to set up secure HTTP password caching on your system. +Read <> to see how to set up secure HTTP password caching on your system. ==== The SSH Protocol diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc index 7e775ab17..ccea933c9 100644 --- a/book/05-distributed-git/sections/contributing.asc +++ b/book/05-distributed-git/sections/contributing.asc @@ -49,11 +49,11 @@ If you run that command before committing, you can tell if you're about to commi Next, try to make each commit a logically separate changeset. If you can, try to make your changes digestible -- don't code for a whole weekend on five different issues and then submit them all as one massive commit on Monday. Even if you don't commit during the weekend, use the staging area on Monday to split your work into at least one commit per issue, with a useful message per commit. -If some of the changes modify the same file, try to use `git add --patch` to partially stage files (covered in detail in <<_git_tools#_interactive_staging>>). +If some of the changes modify the same file, try to use `git add --patch` to partially stage files (covered in detail in <>). The project snapshot at the tip of the branch is identical whether you do one commit or five, as long as all the changes are added at some point, so try to make things easier on your fellow developers when they have to review your changes. This approach also makes it easier to pull out or revert one of the changesets if you need to later. -<<_git_tools#_rewriting_history>> describes a number of useful Git tricks for rewriting history and interactively staging files -- use these tools to help craft a clean and understandable history before sending the work to someone else. +<> describes a number of useful Git tricks for rewriting history and interactively staging files -- use these tools to help craft a clean and understandable history before sending the work to someone else. The last thing to keep in mind is the commit message. Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. @@ -252,7 +252,7 @@ Date: Fri May 29 16:01:27 2009 -0700 ---- The `issue54..origin/master` syntax is a log filter that asks Git to display only those commits that are on the latter branch (in this case `origin/master`) that are not on the first branch (in this case `issue54`). -We'll go over this syntax in detail in <<_git_tools#_commit_ranges>>. +We'll go over this syntax in detail in <>. From the above output, we can see that there is a single commit that John has made that Jessica has not merged into her local work. If she merges `origin/master`, that is the single commit that will modify her local work. @@ -424,7 +424,7 @@ To jessica@githost:simplegit.git ---- This is called a _refspec_. -See <<_git_internals#_refspec>> for a more detailed discussion of Git refspecs and different things you can do with them. +See <> for a more detailed discussion of Git refspecs and different things you can do with them. Also notice the `-u` flag; this is short for `--set-upstream`, which configures the branches for easier pushing and pulling later. Suddenly, Jessica gets email from John, who tells her he's pushed some changes to the `featureA` branch on which they are collaborating, and he asks Jessica to take a look at them. @@ -520,7 +520,7 @@ $ git commit [NOTE] ==== -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 <<_git_tools#_rewriting_history>> for more information about interactive rebasing. +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. @@ -533,7 +533,7 @@ $ git remote add myfork You then need to push your new work to this repository. It's easiest to push the topic branch you're working on to your forked repository, rather than merging that work into your master branch and pushing that. -The reason is that if your work isn't accepted or is cherry-picked, you don't have to rewind your master branch (the Git `cherry-pick` operation is covered in more detail in <<_distributed_git#_rebase_cherry_pick>>). +The reason is that if your work isn't accepted or is cherry-picked, you don't have to rewind your master branch (the Git `cherry-pick` operation is covered in more detail in <>). If the maintainers `merge`, `rebase`, or `cherry-pick` your work, you'll eventually get it back via pulling from their repository anyhow. In any event, you can push your work with: @@ -545,7 +545,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 <<_github#_github>> -- 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: diff --git a/book/05-distributed-git/sections/maintaining.asc b/book/05-distributed-git/sections/maintaining.asc index dc318acea..a841b7e92 100644 --- a/book/05-distributed-git/sections/maintaining.asc +++ b/book/05-distributed-git/sections/maintaining.asc @@ -422,14 +422,14 @@ Now, whenever you do a merge that resolves conflicts, the resolution will be rec If you need to, you can interact with the rerere cache using the `git rerere` command. When it's invoked alone, Git checks its database of resolutions and tries to find a match with any current merge conflicts and resolve them (although this is done automatically if `rerere.enabled` is set to `true`). There are also subcommands to see what will be recorded, to erase specific resolution from the cache, and to clear the entire cache. -We will cover rerere in more detail in <<_git_tools#_rerere>>. +We will cover rerere in more detail in <>. [[_tagging_releases]] ==== Tagging Your Releases (((tags)))(((tags, signing))) When you've decided to cut a release, you'll probably want to assign a tag so you can re-create that release at any point going forward. -You can create a new tag as discussed in <<_git_basics_chapter#_git_basics_chapter>>. +You can create a new tag as discussed in <>. If you decide to sign the tag as the maintainer, the tagging may look something like this: [source,console] diff --git a/book/06-github/sections/1-setting-up-account.asc b/book/06-github/sections/1-setting-up-account.asc index eba44feb3..77e85e6c8 100644 --- a/book/06-github/sections/1-setting-up-account.asc +++ b/book/06-github/sections/1-setting-up-account.asc @@ -27,7 +27,7 @@ As of right now, you're fully able to connect with Git repositories using the `h However, to simply clone public projects, you don't even need to sign up - the account we just created comes into play when we fork projects and push to our forks a bit later. If you'd like to use SSH remotes, you'll need to configure a public key. -(If you don't already have one, see <<_git_on_the_server#_generate_ssh_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. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 1a0503c77..1f351b83d 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -26,13 +26,13 @@ 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. -[[_github_flow]] +[[ch06-github_flow]] ==== The GitHub Flow (((GitHub, Flow))) GitHub is designed around a particular collaboration workflow, centered on Pull Requests. This flow works whether you're collaborating with a tightly-knit team in a single shared repository, or a globally-distributed company or network of strangers contributing to a project through dozens of forks. -It is centered on the <<_git_branching#_topic_branch>> workflow covered in <<_git_branching#_git_branching>>. +It is centered on the <> workflow covered in <>. Here's how it generally works: @@ -44,7 +44,7 @@ Here's how it generally works: 6. Discuss, and optionally continue committing. 7. The project owner merges or closes the Pull Request. -This is basically the Integration Manager workflow covered in <<_distributed_git#_integration_manager>>, but instead of using email to communicate and review changes, teams use GitHub's web based tools. +This is basically the Integration Manager workflow covered in <>, but instead of using email to communicate and review changes, teams use GitHub's web based tools. Let's walk through an example of proposing a change to an open source project hosted on GitHub using this flow. @@ -139,7 +139,7 @@ Though Pull Requests are used commonly for public projects like this when the co At this point, the project owner can look at the suggested change and merge it, reject it or comment on it. Let's say that he likes the idea, but would prefer a slightly longer time for the light to be off than on. -Where this conversation may take place over email in the workflows presented in <<_distributed_git#_distributed_git>>, on GitHub this happens online. The project owner can review the unified diff and leave a comment by clicking on any of the lines. +Where this conversation may take place over email in the workflows presented in <>, on GitHub this happens online. The project owner can review the unified diff and leave a comment by clicking on any of the lines. .Comment on a specific line of code in a Pull Request image::images/blink-04-pr-comment.png[PR line comment] @@ -167,7 +167,7 @@ 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. In `git diff` terms, it basically automatically shows you `git diff master...` for the branch this Pull Request is based on. See <<_distributed_git#_what_is_introduced>> for more about this type of diff. +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. @@ -258,7 +258,7 @@ image::images/pr-02-merge-fix.png[PR fixed] One of the great things about Git is that you can do that continuously. If you have a very long-running project, you can easily merge from the target branch over and over again and only have to deal with conflicts that have arisen since the last time that you merged, making the process very manageable. -If you absolutely wish to rebase the branch to clean it up, you can certainly do so, but it is highly encouraged to not force push over the branch that the Pull Request is already opened on. If other people have pulled it down and done more work on it, you run into all of the issues outlined in <<_git_branching#_rebase_peril>>. Instead, push the rebased branch to a new branch on GitHub and open a brand new Pull Request referencing the old one, then close the original. +If you absolutely wish to rebase the branch to clean it up, you can certainly do so, but it is highly encouraged to not force push over the branch that the Pull Request is already opened on. If other people have pulled it down and done more work on it, you run into all of the issues outlined in <>. Instead, push the rebased branch to a new branch on GitHub and open a brand new Pull Request referencing the old one, then close the original. ===== References diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index e8b851376..5e254f801 100644 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -24,7 +24,7 @@ All you really have to do here is provide a project name; the rest of the fields 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 <<_git_basics_chapter#_git_basics_chapter>>. +We won't belabor this here; if you need a refresher, check out <>. Now that your project is hosted on GitHub, you can give the URL to anyone you want to share your project with. Every project on GitHub is accessible over HTTPS as `https://github.com//`, and over SSH as `git@github.com:/`. @@ -81,7 +81,7 @@ It gives you a link to the Pull Request on GitHub. It also gives you a few URLs that you can use from the command line. If you notice the line that says `git pull patch-1`, this is a simple way to merge in a remote branch without having to add a remote. -We went over this quickly in <<_distributed_git#_checking_out_remotes>>. +We went over this quickly in <>. If you wish, you can create and switch to a topic branch and then run this command to merge in the Pull Request changes. The other interesting URLs are the `.diff` and `.patch` URLs, which as you may guess, provide unified diff and patch versions of the Pull Request. @@ -94,7 +94,7 @@ $ curl http://github.com/tonychacon/fade/pull/1.patch | git am ===== Collaborating on the Pull Request -As we covered in <<_github#_github_flow>>, you can now have a conversation with the person who opened the Pull Request. +As we covered in <>, you can now have a conversation with the person who opened the Pull Request. You can comment on specific lines of code, comment on whole commits or comment on the entire Pull Request itself, using GitHub Flavored Markdown everywhere. Every time someone else comments on the Pull Request you will continue to get email notifications so you know there is activity happening. @@ -120,12 +120,12 @@ If you decide you don't want to merge it, you can also just close the Pull Reque ===== Pull Request Refs If you're dealing with a *lot* of Pull Requests and don't want to add a bunch of remotes or do one time pulls every time, there is a neat trick that GitHub allows you to do. -This is a bit of an advanced trick and we'll go over the details of this a bit more in <<_git_internals#_refspec>>, but it can be pretty useful. +This is a bit of an advanced trick and we'll go over the details of this a bit more in <>, but it can be pretty useful. 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 <<_git_internals#_plumbing_porcelain>>) 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. diff --git a/book/06-github/sections/4-managing-organization.asc b/book/06-github/sections/4-managing-organization.asc index 2f048c853..f3137e5dc 100644 --- a/book/06-github/sections/4-managing-organization.asc +++ b/book/06-github/sections/4-managing-organization.asc @@ -1,4 +1,4 @@ -[[_github_orgs]] +[[ch06-github_orgs]] === Managing an organization (((GitHub, organizations))) diff --git a/book/07-git-tools/sections/advanced-merging.asc b/book/07-git-tools/sections/advanced-merging.asc index b17dafa39..24e66221b 100644 --- a/book/07-git-tools/sections/advanced-merging.asc +++ b/book/07-git-tools/sections/advanced-merging.asc @@ -14,7 +14,7 @@ We'll also cover some of the different, non-standard types of merges you can do, ==== Merge Conflicts -While we covered some basics on resolving merge conflicts in <<_git_branching#_basic_merge_conflicts>>, for more complex conflicts, Git provides a few tools to help you figure out what's going on and how to better deal with the conflict. +While we covered some basics on resolving merge conflicts in <>, for more complex conflicts, Git provides a few tools to help you figure out what's going on and how to better deal with the conflict. First of all, if at all possible, try to make sure your working directory is clean before doing a merge that may have conflicts. If you have work in progress, either commit it to a temporary branch or stash it. @@ -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 <<_git_tools#_triple_dot>>. +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] ---- @@ -547,7 +547,7 @@ In most cases, if you follow the errant `git merge` with `git reset --hard HEAD~ .History after `git reset --hard HEAD~` image::images/undomerge-reset.png[History after `git reset --hard HEAD~`.] -We covered `reset` back in <<_git_tools#_git_reset>>, so it shouldn't be too hard to figure out what's going on here. +We covered `reset` back in <>, so it shouldn't be too hard to figure out what's going on here. Here's a quick refresher: `reset --hard` usually goes through three steps: . Move the branch HEAD points to. @@ -556,7 +556,7 @@ Here's a quick refresher: `reset --hard` usually goes through three steps: . Make the working directory look like the index. The downside of this approach is that it's rewriting history, which can be problematic with a shared repository. -Check out <<_git_branching#_rebase_peril>> for more on what can happen; the short version is that if other people have the commits you're rewriting, you should probably avoid `reset`. +Check out <> for more on what can happen; the short version is that if other people have the commits you're rewriting, you should probably avoid `reset`. This approach also won't work if any other commits have been created since the merge; moving the refs would effectively lose those changes. [[_reverse_commit]] diff --git a/book/07-git-tools/sections/bundling.asc b/book/07-git-tools/sections/bundling.asc index df5a8fe21..85dbf8235 100644 --- a/book/07-git-tools/sections/bundling.asc +++ b/book/07-git-tools/sections/bundling.asc @@ -83,7 +83,7 @@ Unlike the network protocols which figure out the minimum set of data to transfe Now, you could just do the same thing and bundle the entire repository, which will work, but it's better to just bundle up the difference - just the three commits we just made locally. In order to do that, you'll have to calculate the difference. -As we described in <<_git_tools#_commit_ranges>>, you can specify a range of commits in a number of ways. +As we described in <>, you can specify a range of commits in a number of ways. To get the three commits that we have in our master branch that weren't in the branch we originally cloned, we can use something like `origin/master..master` or `master ^origin/master`. You can test that with the `log` command. diff --git a/book/07-git-tools/sections/replace.asc b/book/07-git-tools/sections/replace.asc index 759d0af77..95cf842a2 100644 --- a/book/07-git-tools/sections/replace.asc +++ b/book/07-git-tools/sections/replace.asc @@ -94,7 +94,7 @@ $ echo 'get history from blah blah blah' | git commit-tree 9c68fdc^{tree} The `commit-tree` command is one of a set of commands that are commonly referred to as 'plumbing' commands. These are commands that are not generally meant to be used directly, but instead are used by *other* Git commands to do smaller jobs. On occasions when we're doing weirder things like this, they allow us to do really low-level things but are not meant for daily use. -You can read more about plumbing commands in <<_git_internals#_plumbing_porcelain>> +You can read more about plumbing commands in <> ===== image::images/replace3.png[] diff --git a/book/07-git-tools/sections/rerere.asc b/book/07-git-tools/sections/rerere.asc index be780dcf5..a030104c3 100644 --- a/book/07-git-tools/sections/rerere.asc +++ b/book/07-git-tools/sections/rerere.asc @@ -1,4 +1,4 @@ -[[_rerere]] +[[ref_rerere]] === Rerere The `git rerere` functionality is a bit of a hidden feature. @@ -146,7 +146,7 @@ You can see that it "Recorded resolution for FILE". image::images/rerere2.png[] Now, let's undo that merge and then rebase it on top of our master branch instead. -We can move our branch back by using `git reset` as we saw in <<_git_tools#_git_reset>>. +We can move our branch back by using `git reset` as we saw in <>. [source,console] ---- @@ -224,7 +224,7 @@ def hello end ---- -We saw an example of this in <<_git_tools#_advanced_merging>>. +We saw an example of this in <>. For now though, let's re-resolve it by just running `git rerere` again: [source,console] diff --git a/book/07-git-tools/sections/reset.asc b/book/07-git-tools/sections/reset.asc index 08da2224a..0c4fb87d4 100644 --- a/book/07-git-tools/sections/reset.asc +++ b/book/07-git-tools/sections/reset.asc @@ -221,7 +221,7 @@ If we look at the diagram for that command and think about what `git add` does, 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 <<_git_basics_chapter#_unstaging>> for more on this.) +(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 would just run something like `git reset eb43bf file.txt`. diff --git a/book/07-git-tools/sections/revision-selection.asc b/book/07-git-tools/sections/revision-selection.asc index 22cf291d2..7a9b48398 100644 --- a/book/07-git-tools/sections/revision-selection.asc +++ b/book/07-git-tools/sections/revision-selection.asc @@ -99,7 +99,7 @@ $ git show topic1 ---- If you want to see which specific SHA-1 a branch points to, or if you want to see what any of these examples boils down to in terms of SHA-1s, you can use a Git plumbing tool called `rev-parse`. -You can see <<_git_internals#_git_internals>> for more information about plumbing tools; basically, `rev-parse` exists for lower-level operations and isn’t designed to be used in day-to-day operations. +You can see <> for more information about plumbing tools; basically, `rev-parse` exists for lower-level operations and isn’t designed to be used in day-to-day operations. However, it can be helpful sometimes when you need to see what’s really going on. Here you can run `rev-parse` on your branch. diff --git a/book/07-git-tools/sections/submodules.asc b/book/07-git-tools/sections/submodules.asc index f5da2cf4a..798b00810 100644 --- a/book/07-git-tools/sections/submodules.asc +++ b/book/07-git-tools/sections/submodules.asc @@ -776,7 +776,7 @@ This is obviously a simplified example, but hopefully it gives you an idea of ho ===== Useful Aliases You may want to set up some aliases for some of these commands as they can be quite long and you can't set configuration options for most of them to make them defaults. -We covered setting up Git aliases in <<_git_basics_chapter#_git_aliases>>, but here is an example of what you may want to set up if you plan on working with submodules in Git a lot. +We covered setting up Git aliases in <>, but here is an example of what you may want to set up if you plan on working with submodules in Git a lot. [source,console] ---- diff --git a/book/07-git-tools/sections/subtree-merges.asc b/book/07-git-tools/sections/subtree-merges.asc index e9c26d64f..78a0b03f8 100644 --- a/book/07-git-tools/sections/subtree-merges.asc +++ b/book/07-git-tools/sections/subtree-merges.asc @@ -49,7 +49,7 @@ It's not common, because it's rarely helpful, but it's fairly easy to have branc In this case, we want to pull the Rack project into our `master` project as a subdirectory. We can do that in Git with `git read-tree`. -You’ll learn more about `read-tree` and its friends in <<_git_internals#_git_internals>>, but for now know that it reads the root tree of one branch into your current staging area and working directory. +You’ll learn more about `read-tree` and its friends in <>, but for now know that it reads the root tree of one branch into your current staging area and working directory. We just switched back to your `master` branch, and we pull the `rack_branch` branch into the `rack` subdirectory of our `master` branch of our main project: [source,console] @@ -82,7 +82,7 @@ Automatic merge went well; stopped before committing as requested All the changes from the Rack project are merged in and ready to be committed locally. You can also do the opposite – make changes in the `rack` subdirectory of your master branch and then merge them into your `rack_branch` branch later to submit them to the maintainers or push them upstream. -This gives us a way to have a workflow somewhat similar to the submodule workflow without using submodules (which we will cover in <<_git_tools#_git_submodules>>). +This gives us a way to have a workflow somewhat similar to the submodule workflow without using submodules (which we will cover in <>). We can keep branches with other related projects in our repository and subtree merge them into our project occasionally. It is nice in some ways, for example all the code is committed to a single place. However, it has other drawbacks in that it's a bit more complex and easier to make mistakes in reintegrating changes or accidentally pushing a branch into an unrelated repository. diff --git a/book/08-customizing-git/sections/config.asc b/book/08-customizing-git/sections/config.asc index b5a890e4e..cb5d0eded 100644 --- a/book/08-customizing-git/sections/config.asc +++ b/book/08-customizing-git/sections/config.asc @@ -2,7 +2,7 @@ === Git Configuration (((git commands, config))) -As you read briefly in <<_getting_started#_getting_started>>, you can specify Git configuration settings with the `git config` command. +As you read briefly in <>, you can specify Git configuration settings with the `git config` command. One of the first things you did was set up your name and email address: [source,console] @@ -129,7 +129,7 @@ If you run that, Git will page the entire output of all commands, no matter how ===== `user.signingkey` (((GPG))) -If you're making signed annotated tags (as discussed in <<_git_tools#_signing>>), setting your GPG signing key as a configuration setting makes things easier. +If you're making signed annotated tags (as discussed in <>), setting your GPG signing key as a configuration setting makes things easier. Set your key ID like so: [source,console] @@ -147,7 +147,7 @@ $ git tag -s ===== `core.excludesfile` (((excludes)))(((.gitignore))) -You can put patterns in your project's `.gitignore` file to have Git not see them as untracked files or try to stage them when you run `git add` on them, as discussed in <<_git_basics_chapter#_ignoring>>. +You can put patterns in your project's `.gitignore` file to have Git not see them as untracked files or try to stage them when you run `git add` on them, as discussed in <>. But sometimes you want to ignore certain files for all repositories that you work with. If your computer is running macOS, you're probably familiar with `.DS_Store` files. @@ -507,4 +507,4 @@ $ git config --system receive.denyDeletes true This denies any deletion of branches or tags -- no user can do it. To remove remote branches, you must remove the ref files from the server manually. -There are also more interesting ways to do this on a per-user basis via ACLs, as you'll learn in <<_customizing_git#_an_example_git_enforced_policy>>. +There are also more interesting ways to do this on a per-user basis via ACLs, as you'll learn in <>. diff --git a/book/08-customizing-git/sections/hooks.asc b/book/08-customizing-git/sections/hooks.asc index 09268709d..6e7d8251a 100644 --- a/book/08-customizing-git/sections/hooks.asc +++ b/book/08-customizing-git/sections/hooks.asc @@ -27,7 +27,7 @@ This section splits them into committing-workflow hooks, email-workflow scripts, [NOTE] ==== It's important to note that client-side hooks are *not* copied when you clone a repository. -If your intent with these scripts is to enforce a policy, you'll probably want to do that on the server side; see the example in <<_customizing_git#_an_example_git_enforced_policy>>. +If your intent with these scripts is to enforce a policy, you'll probably want to do that on the server side; see the example in <>. ==== ===== Committing-Workflow Hooks diff --git a/book/08-customizing-git/sections/policy.asc b/book/08-customizing-git/sections/policy.asc index 1ea85fc92..d83ba2c24 100644 --- a/book/08-customizing-git/sections/policy.asc +++ b/book/08-customizing-git/sections/policy.asc @@ -62,7 +62,7 @@ You can take that output, loop through each of those commit SHA-1s, grab the mes You have to figure out how to get the commit message from each of these commits to test. To get the raw commit data, you can use another plumbing command called `git cat-file`. -We'll go over all these plumbing commands in detail in <<_git_internals#_git_internals>>; but for now, here's what that command gives you: +We'll go over all these plumbing commands in detail in <>; but for now, here's what that command gives you: [source,console] ---- @@ -167,7 +167,7 @@ On the ACL file you looked at earlier, this `get_acl_access_data` method returns Now that you have the permissions sorted out, you need to determine what paths the commits being pushed have modified, so you can make sure the user who's pushing has access to all of them. -You can pretty easily see what files have been modified in a single commit with the `--name-only` option to the `git log` command (mentioned briefly in <<_git_basics_chapter#_git_basics_chapter>>): +You can pretty easily see what files have been modified in a single commit with the `--name-only` option to the `git log` command (mentioned briefly in <>): [source,console] ---- @@ -428,7 +428,7 @@ target_shas.each do |sha| end ---- -This script uses a syntax that wasn't covered in <<_git_tools#_revision_selection>>. +This script uses a syntax that wasn't covered in <>. You get a list of commits that have already been pushed up by running this: [source,ruby] 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 90ff64cf6..14bc9c00b 100644 --- a/book/09-git-and-other-scms/sections/import-custom.asc +++ b/book/09-git-and-other-scms/sections/import-custom.asc @@ -6,7 +6,7 @@ If your system isn't one of the above, you should look for an importer online – quality importers are available for many other systems, including CVS, Clear Case, Visual Source Safe, even a directory of archives. If none of these tools works for you, you have a more obscure tool, or you otherwise need a more custom importing process, you should use `git fast-import`. This command reads simple instructions from stdin to write specific Git data. -It's much easier to create Git objects this way than to run the raw Git commands or try to write the raw objects (see <<_git_internals#_git_internals>> for more information). +It's much easier to create Git objects this way than to run the raw Git commands or try to write the raw objects (see <> for more information). This way, you can write an import script that reads the necessary information out of the system you're importing from and prints straightforward instructions to stdout. You can then run this program and pipe its output through `git fast-import`. @@ -29,7 +29,7 @@ As you may remember, Git is fundamentally a linked list of commit objects that p All you have to do is tell `fast-import` what the content snapshots are, what commit data points to them, and the order they go in. Your strategy will be to go through the snapshots one at a time and create commits with the contents of each directory, linking each commit back to the previous one. -As we did in <<_customizing_git#_an_example_git_enforced_policy>>, we'll write this in Ruby, because it's what we generally work with and it tends to be easy to read. +As we did in <>, we'll write this in Ruby, because it's what we generally work with and it tends to be easy to read. You can write this example pretty easily in anything you're familiar with – it just needs to print the appropriate information to `stdout`. And, if you are running on Windows, this means you'll need to take special care to not introduce carriage returns at the end your lines – `git fast-import` is very particular about just wanting line feeds (LF) not the carriage return line feeds (CRLF) that Windows uses. diff --git a/book/10-git-internals/sections/environment.asc b/book/10-git-internals/sections/environment.asc index d303ee0fd..37785eb33 100644 --- a/book/10-git-internals/sections/environment.asc +++ b/book/10-git-internals/sections/environment.asc @@ -220,7 +220,7 @@ It's probably easier just to use the `~/.ssh/config` file for that. *`GIT_ASKPASS`* is an override for the `core.askpass` configuration value. This is the program invoked whenever Git needs to ask the user for credentials, which can expect a text prompt as a command-line argument, and should return the answer on `stdout`. -(See <<_git_tools#_credential_caching>> for more on this subsystem.) +(See <> for more on this subsystem.) *`GIT_NAMESPACE`* controls access to namespaced refs, and is equivalent to the `--namespace` flag. This is mostly useful on the server side, where you may want to store multiple forks of a single repository in one repository, only keeping the refs separate. diff --git a/book/10-git-internals/sections/maintenance.asc b/book/10-git-internals/sections/maintenance.asc index 1f2e61733..5d22cfd2f 100644 --- a/book/10-git-internals/sections/maintenance.asc +++ b/book/10-git-internals/sections/maintenance.asc @@ -94,7 +94,7 @@ The trick is finding that latest commit SHA-1 – it's not like you've memorized Often, the quickest way is to use a tool called `git reflog`. As you're working, Git silently records what your HEAD is every time you change it. Each time you commit or change branches, the reflog is updated. -The reflog is also updated by the `git update-ref` command, which is another reason to use it instead of just writing the SHA-1 value to your ref files, as we covered in <<_git_internals#_git_refs>>. +The reflog is also updated by the `git update-ref` command, which is another reason to use it instead of just writing the SHA-1 value to your ref files, as we covered in <>. You can see where you've been at any time by running `git reflog`: [source,console] @@ -262,7 +262,7 @@ dadf7258d699da2c8d89b09ef6670edb7d5f91b4 commit 229 159 12 ---- The big object is at the bottom: 5MB. -To find out what file it is, you'll use the `rev-list` command, which you used briefly in <<_customizing_git#_enforcing_commit_message_format>>. +To find out what file it is, you'll use the `rev-list` command, which you used briefly in <>. If you pass `--objects` to `rev-list`, it lists all the commit SHA-1s and also the blob SHA-1s with the file paths associated with them. You can use this to find your blob's name: @@ -283,7 +283,7 @@ dadf725 oops - removed large tarball ---- You must rewrite all the commits downstream from `7b30847` to fully remove this file from your Git history. -To do so, you use `filter-branch`, which you used in <<_git_tools#_rewriting_history>>: +To do so, you use `filter-branch`, which you used in <>: [source,console] ---- @@ -294,7 +294,7 @@ Rewrite dadf7258d699da2c8d89b09ef6670edb7d5f91b4 (2/2) Ref 'refs/heads/master' was rewritten ---- -The `--index-filter` option is similar to the `--tree-filter` option used in <<_git_tools#_rewriting_history>>, except that instead of passing a command that modifies files checked out on disk, you're modifying your staging area or index each time. +The `--index-filter` option is similar to the `--tree-filter` option used in <>, except that instead of passing a command that modifies files checked out on disk, you're modifying your staging area or index each time. Rather than remove a specific file with something like `rm file`, you have to remove it with `git rm --cached` – you must remove it from the index, not from disk. The reason to do it this way is speed – because Git doesn't have to check out each revision to disk before running your filter, the process can be much, much faster. diff --git a/book/10-git-internals/sections/plumbing-porcelain.asc b/book/10-git-internals/sections/plumbing-porcelain.asc index 72b568665..e7a26a154 100644 --- a/book/10-git-internals/sections/plumbing-porcelain.asc +++ b/book/10-git-internals/sections/plumbing-porcelain.asc @@ -29,7 +29,7 @@ refs/ Depending on your version of Git, you may see some additional content there, but this is a fresh `git init` repository -- it's what you see by default. The `description` file is used only by the GitWeb program, so don't worry about it. The `config` file contains your project-specific configuration options, and the `info` directory keeps a global exclude file (((excludes))) for ignored patterns that you don't want to track in a `.gitignore` file. -The `hooks` directory contains your client- or server-side hook scripts, which are discussed in detail in <<_customizing_git#_git_hooks>>. +The `hooks` directory contains your client- or server-side hook scripts, which are discussed in detail in <>. This leaves four important entries: the `HEAD` and (yet to be created) `index` files, and the `objects` and `refs` directories. These are the core parts of Git. diff --git a/book/10-git-internals/sections/refs.asc b/book/10-git-internals/sections/refs.asc index e4efc2f70..ad812f42c 100644 --- a/book/10-git-internals/sections/refs.asc +++ b/book/10-git-internals/sections/refs.asc @@ -64,7 +64,7 @@ image::images/data-model-4.png[Git directory objects with branch head references When you run commands like `git branch `, Git basically runs that `update-ref` command to add the SHA-1 of the last commit of the branch you're on into whatever new reference you want to create. -[[_the_head]] +[[ref_the_ref]] ==== The HEAD The question now is, when you run `git branch `, how does Git know the SHA-1 of the last commit? @@ -123,7 +123,7 @@ The _tag_ object is very much like a commit object -- it contains a tagger, a da The main difference is that a tag object generally points to a commit rather than a tree. It's like a branch reference, but it never moves -- it always points to the same commit but gives it a friendlier name. -As discussed in <<_git_basics_chapter#_git_basics_chapter>>, there are two types of tags: annotated and lightweight. +As discussed in <>, there are two types of tags: annotated and lightweight. You can make a lightweight tag by running something like this: [source,console] diff --git a/book/A-git-in-other-environments/sections/guis.asc b/book/A-git-in-other-environments/sections/guis.asc index 843cfcd18..91030fa6c 100644 --- a/book/A-git-in-other-environments/sections/guis.asc +++ b/book/A-git-in-other-environments/sections/guis.asc @@ -112,7 +112,7 @@ If you already have a local repository, just drag its directory from the Finder Once it's installed and configured, you can use the GitHub client for many common Git tasks. The intended workflow for this tool is sometimes called the ``GitHub Flow.'' -We cover this in more detail in <<_github#_github_flow>>, 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. +We cover this in more detail in <>, but the general gist is that (a) you'll be committing to a branch, and (b) you'll be syncing up with a remote repository fairly regularly. Branch management is one of the areas where the two tools diverge. On Mac, there's a button at the top of the window for creating a new branch: diff --git a/book/B-embedding-git/sections/jgit.asc b/book/B-embedding-git/sections/jgit.asc index 52830e731..aaccc3308 100644 --- a/book/B-embedding-git/sections/jgit.asc +++ b/book/B-embedding-git/sections/jgit.asc @@ -97,7 +97,7 @@ Ref objects are also used to represent tag refs and objects, so you can ask if t The second line gets the target of the `master` reference, which is returned as an ObjectId instance. ObjectId represents the SHA-1 hash of an object, which might or might not exist in Git's object database. -The third line is similar, but shows how JGit handles the rev-parse syntax (for more on this, see <<_git_tools#_branch_references>>); you can pass any object specifier that Git understands, and JGit will return either a valid ObjectId for that object, or `null`. +The third line is similar, but shows how JGit handles the rev-parse syntax (for more on this, see <>); you can pass any object specifier that Git understands, and JGit will return either a valid ObjectId for that object, or `null`. The next two lines show how to load the raw contents of an object. In this example, we call `ObjectLoader.copyTo()` to stream the contents of the object directly to stdout, but ObjectLoader also has methods to read the type and size of an object, as well as return it as a byte array. diff --git a/book/B-embedding-git/sections/libgit2.asc b/book/B-embedding-git/sections/libgit2.asc index d5af4ee9d..049925098 100644 --- a/book/B-embedding-git/sections/libgit2.asc +++ b/book/B-embedding-git/sections/libgit2.asc @@ -35,7 +35,7 @@ The `git_repository` type represents a handle to a repository with a cache in me This is the simplest method, for when you know the exact path to a repository's working directory or `.git` folder. There's also the `git_repository_open_ext` which includes options for searching, `git_clone` and friends for making a local clone of a remote repository, and `git_repository_init` for creating an entirely new repository. -The second chunk of code uses rev-parse syntax (see <<_git_tools#_branch_references>> for more on this) to get the commit that HEAD eventually points to. +The second chunk of code uses rev-parse syntax (see <> for more on this) to get the commit that HEAD eventually points to. The type returned is a `git_object` pointer, which represents something that exists in the Git object database for a repository. `git_object` is actually a ``parent'' type for several different kinds of objects; the memory layout for each of the ``child'' types is the same as for `git_object`, so you can safely cast to the right one. In this case, `git_object_type(commit)` would return `GIT_OBJ_COMMIT`, so it's safe to cast to a `git_commit` pointer. diff --git a/book/01-introduction/1-introduction.asc b/ch01-getting-started.asc similarity index 62% rename from book/01-introduction/1-introduction.asc rename to ch01-getting-started.asc index 613064951..211b41eca 100644 --- a/book/01-introduction/1-introduction.asc +++ b/ch01-getting-started.asc @@ -1,23 +1,23 @@ -[[_getting_started]] +[[ch01-getting-started]] == Getting Started This chapter will be about getting started with Git. We will begin by explaining some background on version control tools, then move on to how to get Git running on your system and finally how to get it set up to start working with. At the end of this chapter you should understand why Git is around, why you should use it and you should be all set up to do so. -include::sections/about-version-control.asc[] +include::book/01-introduction/sections/about-version-control.asc[] -include::sections/history.asc[] +include::book/01-introduction/sections/history.asc[] -include::sections/basics.asc[] +include::book/01-introduction/sections/basics.asc[] -include::sections/command-line.asc[] +include::book/01-introduction/sections/command-line.asc[] -include::sections/installing.asc[] +include::book/01-introduction/sections/installing.asc[] -include::sections/first-time-setup.asc[] +include::book/01-introduction/sections/first-time-setup.asc[] -include::sections/help.asc[] +include::book/01-introduction/sections/help.asc[] === Summary diff --git a/book/02-git-basics/1-git-basics.asc b/ch02-git-basics-chapter.asc similarity index 69% rename from book/02-git-basics/1-git-basics.asc rename to ch02-git-basics-chapter.asc index 14d3d34b0..77fff9863 100644 --- a/book/02-git-basics/1-git-basics.asc +++ b/ch02-git-basics-chapter.asc @@ -1,4 +1,4 @@ -[[_git_basics_chapter]] +[[ch02-git-basics-chapter]] == Git Basics If you can read only one chapter to get going with Git, this is it. @@ -6,19 +6,19 @@ This chapter covers every basic command you need to do the vast majority of the By the end of the chapter, you should be able to configure and initialize a repository, begin and stop tracking files, and stage and commit changes. We'll also show you how to set up Git to ignore certain files and file patterns, how to undo mistakes quickly and easily, how to browse the history of your project and view changes between commits, and how to push and pull from remote repositories. -include::sections/getting-a-repository.asc[] +include::book/02-git-basics/sections/getting-a-repository.asc[] -include::sections/recording-changes.asc[] +include::book/02-git-basics/sections/recording-changes.asc[] -include::sections/viewing-history.asc[] +include::book/02-git-basics/sections/viewing-history.asc[] -include::sections/undoing.asc[] +include::book/02-git-basics/sections/undoing.asc[] -include::sections/remotes.asc[] +include::book/02-git-basics/sections/remotes.asc[] -include::sections/tagging.asc[] +include::book/02-git-basics/sections/tagging.asc[] -include::sections/aliases.asc[] +include::book/02-git-basics/sections/aliases.asc[] === Summary diff --git a/book/03-git-branching/1-git-branching.asc b/ch03-git-branching.asc similarity index 78% rename from book/03-git-branching/1-git-branching.asc rename to ch03-git-branching.asc index 77fb9e603..d1528f224 100644 --- a/book/03-git-branching/1-git-branching.asc +++ b/ch03-git-branching.asc @@ -1,4 +1,4 @@ -[[_git_branching]] +[[ch03-git-branching]] == Git Branching (((branches))) @@ -12,17 +12,17 @@ The way Git branches is incredibly lightweight, making branching operations near Unlike many other VCSs, Git encourages workflows that branch and merge often, even multiple times in a day. Understanding and mastering this feature gives you a powerful and unique tool and can entirely change the way that you develop. -include::sections/nutshell.asc[] +include::book/03-git-branching/sections/nutshell.asc[] -include::sections/basic-branching-and-merging.asc[] +include::book/03-git-branching/sections/basic-branching-and-merging.asc[] -include::sections/branch-management.asc[] +include::book/03-git-branching/sections/branch-management.asc[] -include::sections/workflows.asc[] +include::book/03-git-branching/sections/workflows.asc[] -include::sections/remote-branches.asc[] +include::book/03-git-branching/sections/remote-branches.asc[] -include::sections/rebasing.asc[] +include::book/03-git-branching/sections/rebasing.asc[] === Summary diff --git a/book/04-git-server/1-git-server.asc b/ch04-git-on-the-server.asc similarity index 83% rename from book/04-git-server/1-git-server.asc rename to ch04-git-on-the-server.asc index 3ea9aaeb8..7d2fc8364 100644 --- a/book/04-git-server/1-git-server.asc +++ b/ch04-git-on-the-server.asc @@ -1,4 +1,4 @@ -[[_git_on_the_server]] +[[ch04-git-on-the-server]] == Git on the Server (((serving repositories))) @@ -20,23 +20,23 @@ A remote repository is generally a _bare repository_ -- a Git repository that ha Because the repository is only used as a collaboration point, there is no reason to have a snapshot checked out on disk; it's just the Git data. In the simplest terms, a bare repository is the contents of your project's `.git` directory and nothing else. -include::sections/protocols.asc[] +include::book/04-git-server/sections/protocols.asc[] -include::sections/git-on-a-server.asc[] +include::book/04-git-server/sections/git-on-a-server.asc[] -include::sections/generating-ssh-key.asc[] +include::book/04-git-server/sections/generating-ssh-key.asc[] -include::sections/setting-up-server.asc[] +include::book/04-git-server/sections/setting-up-server.asc[] -include::sections/git-daemon.asc[] +include::book/04-git-server/sections/git-daemon.asc[] -include::sections/smart-http.asc[] +include::book/04-git-server/sections/smart-http.asc[] -include::sections/gitweb.asc[] +include::book/04-git-server/sections/gitweb.asc[] -include::sections/gitlab.asc[] +include::book/04-git-server/sections/gitlab.asc[] -include::sections/hosted.asc[] +include::book/04-git-server/sections/hosted.asc[] === Summary diff --git a/book/05-distributed-git/1-distributed-git.asc b/ch05-distributed-git.asc similarity index 81% rename from book/05-distributed-git/1-distributed-git.asc rename to ch05-distributed-git.asc index 0c6fb0bf6..588a2174b 100644 --- a/book/05-distributed-git/1-distributed-git.asc +++ b/ch05-distributed-git.asc @@ -1,4 +1,4 @@ -[[_distributed_git]] +[[ch05-distributed-git]] == Distributed Git (((distributed git))) @@ -7,11 +7,11 @@ Now that you have a remote Git repository set up as a focal point for all the de In this chapter, you'll see how to work with Git in a distributed environment as a contributor and an integrator. That is, you'll learn how to contribute code successfully to a project and make it as easy on you and the project maintainer as possible, and also how to maintain a project successfully with a number of developers contributing. -include::sections/distributed-workflows.asc[] +include::book/05-distributed-git/sections/distributed-workflows.asc[] -include::sections/contributing.asc[] +include::book/05-distributed-git/sections/contributing.asc[] -include::sections/maintaining.asc[] +include::book/05-distributed-git/sections/maintaining.asc[] === Summary diff --git a/book/06-github/1-github.asc b/ch06-github.asc similarity index 82% rename from book/06-github/1-github.asc rename to ch06-github.asc index eab6dacdb..e2cd29e7b 100644 --- a/book/06-github/1-github.asc +++ b/ch06-github.asc @@ -1,4 +1,4 @@ -[[_github]] +[[ch06-github]] == GitHub (((GitHub))) @@ -9,7 +9,7 @@ So while it's not a direct part of the Git open source project, there's a good c This chapter is about using GitHub effectively. We'll cover signing up for and managing an account, creating and using Git repositories, common workflows to contribute to projects and to accept contributions to yours, GitHub's programmatic interface and lots of little tips to make your life easier in general. -If you are not interested in using GitHub to host your own projects or to collaborate with other projects that are hosted on GitHub, you can safely skip to <<_git_tools#_git_tools>>. +If you are not interested in using GitHub to host your own projects or to collaborate with other projects that are hosted on GitHub, you can safely skip to <>. [WARNING] .Interfaces Change @@ -18,15 +18,15 @@ It's important to note that like many active websites, the UI elements in these Hopefully the general idea of what we're trying to accomplish here will still be there, but if you want more up to date versions of these screens, the online versions of this book may have newer screenshots. ==== -include::sections/1-setting-up-account.asc[] +include::book/06-github/sections/1-setting-up-account.asc[] -include::sections/2-contributing.asc[] +include::book/06-github/sections/2-contributing.asc[] -include::sections/3-maintaining.asc[] +include::book/06-github/sections/3-maintaining.asc[] -include::sections/4-managing-organization.asc[] +include::book/06-github/sections/4-managing-organization.asc[] -include::sections/5-scripting.asc[] +include::book/06-github/sections/5-scripting.asc[] === Summary diff --git a/book/07-git-tools/1-git-tools.asc b/ch07-git-tools.asc similarity index 56% rename from book/07-git-tools/1-git-tools.asc rename to ch07-git-tools.asc index 073eae5fd..b6e03c5cb 100644 --- a/book/07-git-tools/1-git-tools.asc +++ b/ch07-git-tools.asc @@ -1,4 +1,4 @@ -[[_git_tools]] +[[ch07-git-tools]] == Git Tools By now, you’ve learned most of the day-to-day commands and workflows that you need to manage or maintain a Git repository for your source code control. @@ -6,33 +6,33 @@ You’ve accomplished the basic tasks of tracking and committing files, and you Now you’ll explore a number of very powerful things that Git can do that you may not necessarily use on a day-to-day basis but that you may need at some point. -include::sections/revision-selection.asc[] +include::book/07-git-tools/sections/revision-selection.asc[] -include::sections/interactive-staging.asc[] +include::book/07-git-tools/sections/interactive-staging.asc[] -include::sections/stashing-cleaning.asc[] +include::book/07-git-tools/sections/stashing-cleaning.asc[] -include::sections/signing.asc[] +include::book/07-git-tools/sections/signing.asc[] -include::sections/searching.asc[] +include::book/07-git-tools/sections/searching.asc[] -include::sections/rewriting-history.asc[] +include::book/07-git-tools/sections/rewriting-history.asc[] -include::sections/reset.asc[] +include::book/07-git-tools/sections/reset.asc[] -include::sections/advanced-merging.asc[] +include::book/07-git-tools/sections/advanced-merging.asc[] -include::sections/rerere.asc[] +include::book/07-git-tools/sections/rerere.asc[] -include::sections/debugging.asc[] +include::book/07-git-tools/sections/debugging.asc[] -include::sections/submodules.asc[] +include::book/07-git-tools/sections/submodules.asc[] -include::sections/bundling.asc[] +include::book/07-git-tools/sections/bundling.asc[] -include::sections/replace.asc[] +include::book/07-git-tools/sections/replace.asc[] -include::sections/credentials.asc[] +include::book/07-git-tools/sections/credentials.asc[] === Summary diff --git a/book/08-customizing-git/1-customizing-git.asc b/ch08-customizing-git.asc similarity index 77% rename from book/08-customizing-git/1-customizing-git.asc rename to ch08-customizing-git.asc index 333ad16ae..2af938c0a 100644 --- a/book/08-customizing-git/1-customizing-git.asc +++ b/ch08-customizing-git.asc @@ -1,17 +1,17 @@ -[[_customizing_git]] +[[ch08-customizing-git]] == Customizing Git So far, we've covered the basics of how Git works and how to use it, and we've introduced a number of tools that Git provides to help you use it easily and efficiently. In this chapter, we'll see how you can make Git operate in a more customized fashion, by introducing several important configuration settings and the hooks system. With these tools, it's easy to get Git to work exactly the way you, your company, or your group needs it to. -include::sections/config.asc[] +include::book/08-customizing-git/sections/config.asc[] -include::sections/attributes.asc[] +include::book/08-customizing-git/sections/attributes.asc[] -include::sections/hooks.asc[] +include::book/08-customizing-git/sections/hooks.asc[] -include::sections/policy.asc[] +include::book/08-customizing-git/sections/policy.asc[] === Summary diff --git a/book/09-git-and-other-scms/1-git-and-other-scms.asc b/ch09-git-and-other-systems.asc similarity index 71% rename from book/09-git-and-other-scms/1-git-and-other-scms.asc rename to ch09-git-and-other-systems.asc index 9ac9db874..43b0b3590 100644 --- a/book/09-git-and-other-scms/1-git-and-other-scms.asc +++ b/ch09-git-and-other-systems.asc @@ -1,4 +1,4 @@ -[[_git_and_other_systems]] +[[ch09-git-and-other-systems]] == Git and Other Systems The world isn't perfect. @@ -16,15 +16,15 @@ Git provides such a nice experience for developers that many people have figured 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::sections/client-svn.asc[] +include::book/09-git-and-other-scms/sections/client-svn.asc[] -include::sections/client-hg.asc[] +include::book/09-git-and-other-scms/sections/client-hg.asc[] -include::sections/client-bzr.asc[] +include::book/09-git-and-other-scms/sections/client-bzr.asc[] -include::sections/client-p4.asc[] +include::book/09-git-and-other-scms/sections/client-p4.asc[] -include::sections/client-tfs.asc[] +include::book/09-git-and-other-scms/sections/client-tfs.asc[] [[_migrating]] === Migrating to Git @@ -34,17 +34,17 @@ If you have an existing codebase in another VCS but you've decided to start usin This section goes over some importers for common systems, and then demonstrates how to develop your own custom importer. You'll learn how to import data from several of the bigger professionally used SCM systems, because they make up the majority of users who are switching, and because high-quality tools for them are easy to come by. -include::sections/import-svn.asc[] +include::book/09-git-and-other-scms/sections/import-svn.asc[] -include::sections/import-hg.asc[] +include::book/09-git-and-other-scms/sections/import-hg.asc[] -include::sections/import-bzr.asc[] +include::book/09-git-and-other-scms/sections/import-bzr.asc[] -include::sections/import-p4.asc[] +include::book/09-git-and-other-scms/sections/import-p4.asc[] -include::sections/import-tfs.asc[] +include::book/09-git-and-other-scms/sections/import-tfs.asc[] -include::sections/import-custom.asc[] +include::book/09-git-and-other-scms/sections/import-custom.asc[] === Summary diff --git a/book/10-git-internals/1-git-internals.asc b/ch10-git-internals.asc similarity index 82% rename from book/10-git-internals/1-git-internals.asc rename to ch10-git-internals.asc index 698da3d20..a82f2fbc5 100644 --- a/book/10-git-internals/1-git-internals.asc +++ b/ch10-git-internals.asc @@ -1,4 +1,4 @@ -[[_git_internals]] +[[ch10-git-internals]] == Git Internals You may have skipped to this chapter from a much earlier chapter, or you may have gotten here after sequentially reading the entire book up to this point -- in either case, this is where we'll go over the inner workings and implementation of Git. @@ -15,21 +15,21 @@ In the last few years, the UI has been refined until it's as clean and easy to u The content-addressable filesystem layer is amazingly cool, so we'll cover that first in this chapter; then, you'll learn about the transport mechanisms and the repository maintenance tasks that you may eventually have to deal with. -include::sections/plumbing-porcelain.asc[] +include::book/10-git-internals/sections/plumbing-porcelain.asc[] -include::sections/objects.asc[] +include::book/10-git-internals/sections/objects.asc[] -include::sections/refs.asc[] +include::book/10-git-internals/sections/refs.asc[] -include::sections/packfiles.asc[] +include::book/10-git-internals/sections/packfiles.asc[] -include::sections/refspec.asc[] +include::book/10-git-internals/sections/refspec.asc[] -include::sections/transfer-protocols.asc[] +include::book/10-git-internals/sections/transfer-protocols.asc[] -include::sections/maintenance.asc[] +include::book/10-git-internals/sections/maintenance.asc[] -include::sections/environment.asc[] +include::book/10-git-internals/sections/environment.asc[] === Summary diff --git a/progit.asc b/progit.asc index 8374486f5..e2fddff00 100644 --- a/progit.asc +++ b/progit.asc @@ -10,28 +10,28 @@ Pro Git include::book/preface.asc[] ifdef::ebook-format[:leveloffset: -1] -include::book/01-introduction/1-introduction.asc[] +include::ch01-getting-started.asc[] -include::book/02-git-basics/1-git-basics.asc[] +include::ch02-git-basics-chapter.asc[] -include::book/03-git-branching/1-git-branching.asc[] +include::ch03-git-branching.asc[] -include::book/04-git-server/1-git-server.asc[] +include::ch04-git-on-the-server.asc[] -include::book/05-distributed-git/1-distributed-git.asc[] +include::ch05-distributed-git.asc[] -include::book/06-github/1-github.asc[] +include::ch06-github.asc[] -include::book/07-git-tools/1-git-tools.asc[] +include::ch07-git-tools.asc[] -include::book/08-customizing-git/1-customizing-git.asc[] +include::ch08-customizing-git.asc[] -include::book/09-git-and-other-scms/1-git-and-other-scms.asc[] +include::ch09-git-and-other-systems.asc[] -include::book/10-git-internals/1-git-internals.asc[] +include::ch10-git-internals.asc[] -include::book/A-git-in-other-environments/1-git-other-environments.asc[] +include::A-git-in-other-environments.asc[] -include::book/B-embedding-git/1-embedding-git.asc[] +include::B-embedding-git-in-your-applications.asc[] -include::book/C-git-commands/1-git-commands.asc[] +include::C-git-commands.asc[]