From 18 Jan, 2021 0:00 UTC: All services will be temporary unavailable for maintenance
  • R/O
  • HTTP
  • SSH
  • HTTPS

Commit

Tags
No Tags

Frequently used words (click to add to your profile)

javaandroidc++linuxc#objective-ccocoa誰得qtrubypythonwindowsphpgamebathyscaphegui翻訳comegattwitterframeworkbtronvb.net計画中(planning stage)testdomarduinodirectxpreviewerゲームエンジン

Commit MetaInfo

Revision2742188a9bc84bcfc634282b3297de3897041f79 (tree)
Time2020-10-25 11:08:11
Authormatsuand <30614168+matsuand@user...>
Commitermatsuand

Log Message

日本語訳段落に続いた正規のオリジナル文への対処(includeのみへの対処)。20201025結果修正。

Change Summary

Incremental Difference

--- a/progit2ja_diff/20201025.result.txt
+++ b/progit2ja_diff/20201025.result.txt
@@ -1,3720 +1,3710 @@
1-diff -au ../../git/progit2/progit2/A-git-in-other-environments.asc /tmp/A-git-in-other-environments.asc.tmp
2---- ../../git/progit2/progit2/A-git-in-other-environments.asc 2020-08-29 09:58:24.046195489 +0900
3-+++ /tmp/A-git-in-other-environments.asc.tmp 2020-10-25 09:24:25.507959693 +0900
1+diff -au /tmp/A-git-in-other-environments.asc.tmp ../../git/progit2/progit2/A-git-in-other-environments.asc
2+--- /tmp/A-git-in-other-environments.asc.tmp 2020-10-25 11:05:02.074629892 +0900
3++++ ../../git/progit2/progit2/A-git-in-other-environments.asc 2020-08-29 09:58:24.046195489 +0900
44 @@ -1,4 +1,4 @@
5--[[A-git-in-other-environments]]
6-+[#A-git-in-other-environments]
5+-[#A-git-in-other-environments]
6++[[A-git-in-other-environments]]
77 [appendix]
88 == Git in Other Environments
99
10-@@ -7,22 +7,6 @@
11- 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.
12- 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.
10+@@ -11,7 +11,11 @@
1311
14--include::book/A-git-in-other-environments/sections/guis.asc[]
15--
16--include::book/A-git-in-other-environments/sections/visualstudio.asc[]
17--
18--include::book/A-git-in-other-environments/sections/visualstudiocode.asc[]
19--
20--include::book/A-git-in-other-environments/sections/jetbrainsides.asc[]
21--
22--include::book/A-git-in-other-environments/sections/sublimetext.asc[]
23--
24--include::book/A-git-in-other-environments/sections/bash.asc[]
25--
26--include::book/A-git-in-other-environments/sections/zsh.asc[]
27--
28--include::book/A-git-in-other-environments/sections/powershell.asc[]
29--
30- === Summary
12+ include::book/A-git-in-other-environments/sections/visualstudio.asc[]
13+
14+-include::book/A-git-in-other-environments/sections/eclipse.asc[]
15++include::book/A-git-in-other-environments/sections/visualstudiocode.asc[]
16++
17++include::book/A-git-in-other-environments/sections/jetbrainsides.asc[]
18++
19++include::book/A-git-in-other-environments/sections/sublimetext.asc[]
20+
21+ include::book/A-git-in-other-environments/sections/bash.asc[]
3122
32- You've learned how to harness Git's power from inside the tools that you use during your everyday work, and also how to access Git repositories from your own programs.
3323 Warning: file not found: ../../git/progit2/progit2-ja/B-embedding-git-in-your-applications.asc
34-diff -au ../../git/progit2/progit2/C-git-commands.asc /tmp/C-git-commands.asc.tmp
35---- ../../git/progit2/progit2/C-git-commands.asc 2020-08-17 16:38:51.074694961 +0900
36-+++ /tmp/C-git-commands.asc.tmp 2020-10-25 09:24:25.545961483 +0900
24+diff -au /tmp/C-git-commands.asc.tmp ../../git/progit2/progit2/C-git-commands.asc
25+--- /tmp/C-git-commands.asc.tmp 2020-10-25 11:05:02.082630342 +0900
26++++ ../../git/progit2/progit2/C-git-commands.asc 2020-08-17 16:38:51.074694961 +0900
3727 @@ -1,4 +1,4 @@
38--[[C-git-commands]]
39-+[#C-git-commands]
28+-[#C-git-commands]
29++[[C-git-commands]]
4030 [appendix]
4131 == Git Commands
4232
43-@@ -8,20 +8,10 @@
33+@@ -8,10 +8,20 @@
4434 In this appendix, we'll go through all the Git commands we addressed throughout the book, grouped roughly by what they're used for.
4535 We'll talk about what each command very generally does and then point out where in the book you can find us having used it.
4636
47--[TIP]
48--====
49--You can abbreviate long options.
50--For example, you can type in `git commit --a`, which acts as if you typed `git commit --amend`.
51--This only works when the letters after `--` are unique for one option.
52--Do use the full option when writing scripts.
53--====
54--
37++[TIP]
38++====
39++You can abbreviate long options.
40++For example, you can type in `git commit --a`, which acts as if you typed `git commit --amend`.
41++This only works when the letters after `--` are unique for one option.
42++Do use the full option when writing scripts.
43++====
44++
5545 === Setup and Config
5646
5747 There are two commands that are used quite a lot, from the first invocations of Git to common every day tweaking and referencing, the `config` and `help` commands.
5848
59--==== git config
60--
49++==== git config
50++
6151 Git has a default way of doing hundreds of things.
6252 For a lot of these things, you can tell Git to default to doing them a different way, or set your preferences.
6353 This involves everything from telling Git what your name is to specific terminal color preferences or what editor you use.
64-@@ -29,251 +19,178 @@
54+@@ -19,178 +29,251 @@
6555
6656 The `git config` command has been used in nearly every chapter of the book.
6757
68--In <<ch01-getting-started#_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git.
69-+In <<ch01-introduction#r_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git.
58+-In <<ch01-introduction#r_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git.
59++In <<ch01-getting-started#_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git.
7060
71--In <<ch02-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.
72-+In <<ch02-git-basics#r_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.
61+-In <<ch02-git-basics#r_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.
62++In <<ch02-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.
7363
74--In <<ch03-git-branching#_rebasing>> we used it to make `--rebase` the default when you run `git pull`.
75-+In <<ch03-git-branching#r_rebasing>> we used it to make `--rebase` the default when you run `git pull`.
64+-In <<ch03-git-branching#r_rebasing>> we used it to make `--rebase` the default when you run `git pull`.
65++In <<ch03-git-branching#_rebasing>> we used it to make `--rebase` the default when you run `git pull`.
7666
77--In <<ch07-git-tools#_credential_caching>> we used it to set up a default store for your HTTP passwords.
78-+In <<ch07-git-tools#r_credential_caching>> we used it to set up a default store for your HTTP passwords.
67+-In <<ch07-git-tools#r_credential_caching>> we used it to set up a default store for your HTTP passwords.
68++In <<ch07-git-tools#_credential_caching>> we used it to set up a default store for your HTTP passwords.
7969
80--In <<ch08-customizing-git#_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git.
81--
82--Finally, basically the entirety of <<ch08-customizing-git#_git_config>> is dedicated to the command.
83--
84--[[_core_editor]]
85--==== git config core.editor commands
86--
87--Accompanying the configuration instructions in <<ch01-getting-started#_editor>>, many editors can be set as follows:
88--
89--.Exhaustive list of `core.editor` configuration commands
90--[cols="1,2",options="header"]
91--|==============================
92--|Editor | Configuration command
93--|Atom |`git config --global core.editor "atom --wait"`
94--|BBEdit (Mac, with command line tools) |`git config --global core.editor "bbedit -w"`
95--|Emacs |`git config --global core.editor emacs`
96--|Gedit (Linux) |`git config --global core.editor "gedit --wait --new-window"`
97--|Gvim (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Vim\vim72\gvim.exe' --nofork '%*'"` (Also see note below)
98--|Kate (Linux) |`git config --global core.editor "kate"`
99--|nano |`git config --global core.editor "nano -w"`
100--|Notepad (Windows 64-bit) |`git config core.editor notepad`
101--|Notepad++ (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` (Also see note below)
102--|Scratch (Linux)|`git config --global core.editor "scratch-text-editor"`
103--|Sublime Text (macOS) |`git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl --new-window --wait"`
104--|Sublime Text (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Sublime Text 3\sublime_text.exe' -w"` (Also see note below)
105--|TextEdit (macOS)|`git config --global --add core.editor "open -W -n"`
106--|Textmate |`git config --global core.editor "mate -w"`
107--|Textpad (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\TextPad 5\TextPad.exe' -m` (Also see note below)
108--|UltraEdit (Windows 64-bit) | `git config --global core.editor Uedit32`
109--|Vim |`git config --global core.editor "vim"`
110--|Visual Studio Code |`git config --global core.editor "code --wait"`
111--|VSCodium (Free/Libre Open Source Software Binaries of VSCode) | `git config --global core.editor "codium --wait"`
112--|WordPad |`git config --global core.editor '"C:\Program Files\Windows NT\Accessories\wordpad.exe"'"`
113--|Xi | `git config --global core.editor "xi --wait"`
114--|==============================
115--
116--[NOTE]
117--====
118--If you have a 32-bit editor on a Windows 64-bit system, the program will be installed in `C:\Program Files (x86)\` rather than `C:\Program Files\` as in the table above.
119--====
120-+In <<ch08-customizing-git#r_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git.
70+-In <<ch08-customizing-git#r_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git.
71++In <<ch08-customizing-git#_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git.
72++
73++Finally, basically the entirety of <<ch08-customizing-git#_git_config>> is dedicated to the command.
74++
75++[[_core_editor]]
76++==== git config core.editor commands
77++
78++Accompanying the configuration instructions in <<ch01-getting-started#_editor>>, many editors can be set as follows:
79++
80++.Exhaustive list of `core.editor` configuration commands
81++[cols="1,2",options="header"]
82++|==============================
83++|Editor | Configuration command
84++|Atom |`git config --global core.editor "atom --wait"`
85++|BBEdit (Mac, with command line tools) |`git config --global core.editor "bbedit -w"`
86++|Emacs |`git config --global core.editor emacs`
87++|Gedit (Linux) |`git config --global core.editor "gedit --wait --new-window"`
88++|Gvim (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Vim\vim72\gvim.exe' --nofork '%*'"` (Also see note below)
89++|Kate (Linux) |`git config --global core.editor "kate"`
90++|nano |`git config --global core.editor "nano -w"`
91++|Notepad (Windows 64-bit) |`git config core.editor notepad`
92++|Notepad++ (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` (Also see note below)
93++|Scratch (Linux)|`git config --global core.editor "scratch-text-editor"`
94++|Sublime Text (macOS) |`git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl --new-window --wait"`
95++|Sublime Text (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\Sublime Text 3\sublime_text.exe' -w"` (Also see note below)
96++|TextEdit (macOS)|`git config --global --add core.editor "open -W -n"`
97++|Textmate |`git config --global core.editor "mate -w"`
98++|Textpad (Windows 64-bit) |`git config --global core.editor "'C:\Program Files\TextPad 5\TextPad.exe' -m` (Also see note below)
99++|UltraEdit (Windows 64-bit) | `git config --global core.editor Uedit32`
100++|Vim |`git config --global core.editor "vim"`
101++|Visual Studio Code |`git config --global core.editor "code --wait"`
102++|VSCodium (Free/Libre Open Source Software Binaries of VSCode) | `git config --global core.editor "codium --wait"`
103++|WordPad |`git config --global core.editor '"C:\Program Files\Windows NT\Accessories\wordpad.exe"'"`
104++|Xi | `git config --global core.editor "xi --wait"`
105++|==============================
106++
107++[NOTE]
108++====
109++If you have a 32-bit editor on a Windows 64-bit system, the program will be installed in `C:\Program Files (x86)\` rather than `C:\Program Files\` as in the table above.
110++====
121111
122--==== git help
123-+Finally, basically the entirety of <<ch08-customizing-git#r_git_config>> is dedicated to the command.
112+-Finally, basically the entirety of <<ch08-customizing-git#r_git_config>> is dedicated to the command.
113++==== git help
124114
125115 The `git help` command is used to show you all the documentation shipped with Git about any command.
126116 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 <command>`.
127117
128--We introduced the `git help` command in <<ch01-getting-started#_git_help>> and showed you how to use it to find more information about the `git shell` in <<ch04-git-on-the-server#_setting_up_server>>.
129--
130-+We introduced the `git help` command in <<ch01-introduction#r_git_help>> and showed you how to use it to find more information about the `git shell` in <<ch04-git-server#r_setting_up_server>>.
118+-We introduced the `git help` command in <<ch01-introduction#r_git_help>> and showed you how to use it to find more information about the `git shell` in <<ch04-git-server#r_setting_up_server>>.
119++We introduced the `git help` command in <<ch01-getting-started#_git_help>> and showed you how to use it to find more information about the `git shell` in <<ch04-git-on-the-server#_setting_up_server>>.
120++
131121
132122 === Getting and Creating Projects
133123
134124 There are two ways to get a Git repository.
135125 One is to copy it from an existing repository on the network or elsewhere and the other is to create a new one in an existing directory.
136126
137--==== git init
138--
127++==== git init
128++
139129 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`.
140130
141--We first introduce this in <<ch02-git-basics-chapter#_getting_a_repo>>, where we show creating a brand new repository to start working with.
142-+We first introduce this in <<ch02-git-basics#r_getting_a_repo>>, where we show creating a brand new repository to start working with.
131+-We first introduce this in <<ch02-git-basics#r_getting_a_repo>>, where we show creating a brand new repository to start working with.
132++We first introduce this in <<ch02-git-basics-chapter#_getting_a_repo>>, where we show creating a brand new repository to start working with.
143133
144--We talk briefly about how you can change the default branch name from ``master'' in <<ch03-git-branching#_remote_branches>>.
145-+We talk briefly about how you can change the default branch from ``master'' in <<ch03-git-branching#r_remote_branches>>.
134+-We talk briefly about how you can change the default branch from ``master'' in <<ch03-git-branching#r_remote_branches>>.
135++We talk briefly about how you can change the default branch name from ``master'' in <<ch03-git-branching#_remote_branches>>.
146136
147--We use this command to create an empty bare repository for a server in <<ch04-git-on-the-server#_bare_repo>>.
148-+We use this command to create an empty bare repository for a server in <<ch04-git-server#r_bare_repo>>.
137+-We use this command to create an empty bare repository for a server in <<ch04-git-server#r_bare_repo>>.
138++We use this command to create an empty bare repository for a server in <<ch04-git-on-the-server#_bare_repo>>.
149139
150--Finally, we go through some of the details of what it actually does behind the scenes in <<ch10-git-internals#_plumbing_porcelain>>.
151--
152--==== git clone
153-+Finally, we go through some of the details of what it actually does behind the scenes in <<ch10-git-internals#r_plumbing_porcelain>>.
140+-Finally, we go through some of the details of what it actually does behind the scenes in <<ch10-git-internals#r_plumbing_porcelain>>.
141++Finally, we go through some of the details of what it actually does behind the scenes in <<ch10-git-internals#_plumbing_porcelain>>.
142++
143++==== git clone
154144
155145 The `git clone` command is actually something of a wrapper around several other commands.
156146 It creates a new directory, goes into it and runs `git init` to make it an empty Git repository, adds a remote (`git remote add`) to the URL that you pass it (by default named `origin`), runs a `git fetch` from that remote repository and then checks out the latest commit into your working directory with `git checkout`.
157147
158148 The `git clone` command is used in dozens of places throughout the book, but we'll just list a few interesting places.
159149
160--It's basically introduced and explained in <<ch02-git-basics-chapter#_git_cloning>>, where we go through a few examples.
161-+It's basically introduced and explained in <<ch02-git-basics#r_git_cloning>>, where we go through a few examples.
150+-It's basically introduced and explained in <<ch02-git-basics#r_git_cloning>>, where we go through a few examples.
151++It's basically introduced and explained in <<ch02-git-basics-chapter#_git_cloning>>, where we go through a few examples.
162152
163--In <<ch04-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.
164-+In <<ch04-git-server#r_git_on_the_server>> we look at using the `--bare` option to create a copy of a Git repository with no working directory.
153+-In <<ch04-git-server#r_git_on_the_server>> we look at using the `--bare` option to create a copy of a Git repository with no working directory.
154++In <<ch04-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.
165155
166--In <<ch07-git-tools#_bundling>> we use it to unbundle a bundled Git repository.
167-+In <<ch07-git-tools#r_bundling>> we use it to unbundle a bundled Git repository.
156+-In <<ch07-git-tools#r_bundling>> we use it to unbundle a bundled Git repository.
157++In <<ch07-git-tools#_bundling>> we use it to unbundle a bundled Git repository.
168158
169--Finally, in <<ch07-git-tools#_cloning_submodules>> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler.
170-+Finally, in <<ch07-git-tools#r_cloning_submodules>> we learn the `--recursive` option to make cloning a repository with submodules a little simpler.
159+-Finally, in <<ch07-git-tools#r_cloning_submodules>> we learn the `--recursive` option to make cloning a repository with submodules a little simpler.
160++Finally, in <<ch07-git-tools#_cloning_submodules>> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler.
171161
172162 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.
173163
174--
164++
175165 === Basic Snapshotting
176166
177167 For the basic workflow of staging content and committing it to your history, there are only a few basic commands.
178168
179--==== git add
180--
169++==== git add
170++
181171 The `git add` command adds content from the working directory into the staging area (or ``index'') for the next commit.
182172 When the `git commit` command is run, by default it only looks at this staging area, so `git add` is used to craft what exactly you would like your next commit snapshot to look like.
183173
184174 This command is an incredibly important command in Git and is mentioned or used dozens of times in this book.
185175 We'll quickly cover some of the unique uses that can be found.
186176
187--We first introduce and explain `git add` in detail in <<ch02-git-basics-chapter#_tracking_files>>.
188-+We first introduce and explain `git add` in detail in <<ch02-git-basics#r_tracking_files>>.
177+-We first introduce and explain `git add` in detail in <<ch02-git-basics#r_tracking_files>>.
178++We first introduce and explain `git add` in detail in <<ch02-git-basics-chapter#_tracking_files>>.
189179
190--We mention how to use it to resolve merge conflicts in <<ch03-git-branching#_basic_merge_conflicts>>.
191-+We mention how to use it to resolve merge conflicts in <<ch03-git-branching#r_basic_merge_conflicts>>.
180+-We mention how to use it to resolve merge conflicts in <<ch03-git-branching#r_basic_merge_conflicts>>.
181++We mention how to use it to resolve merge conflicts in <<ch03-git-branching#_basic_merge_conflicts>>.
192182
193--We go over using it to interactively stage only specific parts of a modified file in <<ch07-git-tools#_interactive_staging>>.
194-+We go over using it to interactively stage only specific parts of a modified file in <<ch07-git-tools#r_interactive_staging>>.
183+-We go over using it to interactively stage only specific parts of a modified file in <<ch07-git-tools#r_interactive_staging>>.
184++We go over using it to interactively stage only specific parts of a modified file in <<ch07-git-tools#_interactive_staging>>.
195185
196--Finally, we emulate it at a low level in <<ch10-git-internals#_tree_objects>>, so you can get an idea of what it's doing behind the scenes.
197--
198--==== git status
199-+Finally, we emulate it at a low level in <<ch10-git-internals#r_tree_objects>>, so you can get an idea of what it's doing behind the scenes.
186+-Finally, we emulate it at a low level in <<ch10-git-internals#r_tree_objects>>, so you can get an idea of what it's doing behind the scenes.
187++Finally, we emulate it at a low level in <<ch10-git-internals#_tree_objects>>, so you can get an idea of what it's doing behind the scenes.
188++
189++==== git status
200190
201191 The `git status` command will show you the different states of files in your working directory and staging area.
202192 Which files are modified and unstaged and which are staged but not yet committed.
203193 In its normal form, it also will show you some basic hints on how to move files between these stages.
204194
205--We first cover `status` in <<ch02-git-basics-chapter#_checking_status>>, both in its basic and simplified forms.
206-+We first cover `status` in <<ch02-git-basics#r_checking_status>>, both in its basic and simplified forms.
195+-We first cover `status` in <<ch02-git-basics#r_checking_status>>, both in its basic and simplified forms.
196++We first cover `status` in <<ch02-git-basics-chapter#_checking_status>>, both in its basic and simplified forms.
207197 While we use it throughout the book, pretty much everything you can do with the `git status` command is covered there.
208198
209--==== git diff
210--
199++==== git diff
200++
211201 The `git diff` command is used when you want to see differences between any two trees.
212202 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`).
213203
214--We first look at the basic uses of `git diff` in <<ch02-git-basics-chapter#_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged.
215--
216--We use it to look for possible whitespace issues before committing with the `--check` option in <<ch05-distributed-git#_commit_guidelines>>.
217-+We first look at the basic uses of `git diff` in <<ch02-git-basics#r_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged.
204+-We first look at the basic uses of `git diff` in <<ch02-git-basics#r_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged.
205++We first look at the basic uses of `git diff` in <<ch02-git-basics-chapter#_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged.
206++
207++We use it to look for possible whitespace issues before committing with the `--check` option in <<ch05-distributed-git#_commit_guidelines>>.
218208
219--We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<ch05-distributed-git#_what_is_introduced>>.
220-+We use it to look for possible whitespace issues before committing with the `--check` option in <<ch05-distributed-git#r_commit_guidelines>>.
209+-We use it to look for possible whitespace issues before committing with the `--check` option in <<ch05-distributed-git#r_commit_guidelines>>.
210++We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<ch05-distributed-git#_what_is_introduced>>.
221211
222--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 <<ch07-git-tools#_advanced_merging>>.
223-+We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<ch05-distributed-git#r_what_is_introduced>>.
212+-We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<ch05-distributed-git#r_what_is_introduced>>.
213++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 <<ch07-git-tools#_advanced_merging>>.
224214
225--Finally, we use it to effectively compare submodule changes with `--submodule` in <<ch07-git-tools#_starting_submodules>>.
226-+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 <<ch07-git-tools#r_advanced_merging>>.
215+-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 <<ch07-git-tools#r_advanced_merging>>.
216++Finally, we use it to effectively compare submodule changes with `--submodule` in <<ch07-git-tools#_starting_submodules>>.
227217
228--==== git difftool
229-+Finally, we use it to effectively compare submodule changes with `--submodule` in <<ch07-git-tools#r_starting_submodules>>.
218+-Finally, we use it to effectively compare submodule changes with `--submodule` in <<ch07-git-tools#r_starting_submodules>>.
219++==== git difftool
230220
231221 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.
232222
233--We only briefly mention this in <<ch02-git-basics-chapter#_git_diff_staged>>.
234--
235--==== git commit
236-+We only briefly mention this in <<ch02-git-basics#r_git_diff_staged>>.
223+-We only briefly mention this in <<ch02-git-basics#r_git_diff_staged>>.
224++We only briefly mention this in <<ch02-git-basics-chapter#_git_diff_staged>>.
225++
226++==== git commit
237227
238228 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.
239229
240--We first cover the basics of committing in <<ch02-git-basics-chapter#_committing_changes>>.
241-+We first cover the basics of committing in <<ch02-git-basics#r_committing_changes>>.
230+-We first cover the basics of committing in <<ch02-git-basics#r_committing_changes>>.
231++We first cover the basics of committing in <<ch02-git-basics-chapter#_committing_changes>>.
242232 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.
243233
244--In <<ch02-git-basics-chapter#_undoing>> we cover using the `--amend` option to redo the most recent commit.
245--
246--In <<ch03-git-branching#_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that.
247-+In <<ch02-git-basics#r_undoing>> we cover using the `--amend` option to redo the most recent commit.
234+-In <<ch02-git-basics#r_undoing>> we cover using the `--amend` option to redo the most recent commit.
235++In <<ch02-git-basics-chapter#_undoing>> we cover using the `--amend` option to redo the most recent commit.
236++
237++In <<ch03-git-branching#_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that.
248238
249--We looked at how to sign commits cryptographically with the `-S` flag in <<ch07-git-tools#_signing_commits>>.
250-+In <<ch03-git-branching#r_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that.
239+-In <<ch03-git-branching#r_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that.
240++We looked at how to sign commits cryptographically with the `-S` flag in <<ch07-git-tools#_signing_commits>>.
251241
252--Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<ch10-git-internals#_git_commit_objects>>.
253-+We looked at how to sign commits cryptographically with the `-S` flag in <<ch07-git-tools#r_signing_commits>>.
242+-We looked at how to sign commits cryptographically with the `-S` flag in <<ch07-git-tools#r_signing_commits>>.
243++Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<ch10-git-internals#_git_commit_objects>>.
254244
255--==== git reset
256-+Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<ch10-git-internals#r_git_commit_objects>>.
245+-Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<ch10-git-internals#r_git_commit_objects>>.
246++==== git reset
257247
258248 The `git reset` command is primarily used to undo things, as you can possibly tell by the verb.
259249 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`.
260250 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.
261251
262--We first effectively cover the simplest use of `git reset` in <<ch02-git-basics-chapter#_unstaging>>, where we use it to unstage a file we had run `git add` on.
263--
264--We then cover it in quite some detail in <<ch07-git-tools#_git_reset>>, which is entirely devoted to explaining this command.
265-+We first effectively cover the simplest use of `git reset` in <<ch02-git-basics#r_unstaging>>, where we use it to unstage a file we had run `git add` on.
252+-We first effectively cover the simplest use of `git reset` in <<ch02-git-basics#r_unstaging>>, where we use it to unstage a file we had run `git add` on.
253++We first effectively cover the simplest use of `git reset` in <<ch02-git-basics-chapter#_unstaging>>, where we use it to unstage a file we had run `git add` on.
254++
255++We then cover it in quite some detail in <<ch07-git-tools#_git_reset>>, which is entirely devoted to explaining this command.
266256
267--We use `git reset --hard` to abort a merge in <<ch07-git-tools#_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command.
268-+We then cover it in quite some detail in <<ch07-git-tools#r_git_reset>>, which is entirely devoted to explaining this command.
257+-We then cover it in quite some detail in <<ch07-git-tools#r_git_reset>>, which is entirely devoted to explaining this command.
258++We use `git reset --hard` to abort a merge in <<ch07-git-tools#_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command.
269259
270--==== git rm
271-+We use `git reset --hard` to abort a merge in <<ch07-git-tools#r_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command.
260+-We use `git reset --hard` to abort a merge in <<ch07-git-tools#r_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command.
261++==== git rm
272262
273263 The `git rm` command is used to remove files from the staging area and working directory for Git.
274264 It is similar to `git add` in that it stages a removal of a file for the next commit.
275265
276--We cover the `git rm` command in some detail in <<ch02-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`.
277-+We cover the `git rm` command in some detail in <<ch02-git-basics#r_removing_files>>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`.
266+-We cover the `git rm` command in some detail in <<ch02-git-basics#r_removing_files>>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`.
267++We cover the `git rm` command in some detail in <<ch02-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`.
278268
279--The only other differing use of `git rm` in the book is in <<ch10-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.
280-+The only other differing use of `git rm` in the book is in <<ch10-git-internals#r_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.
269+-The only other differing use of `git rm` in the book is in <<ch10-git-internals#r_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.
270++The only other differing use of `git rm` in the book is in <<ch10-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.
281271 This can be useful for scripting purposes.
282272
283--==== git mv
284--
273++==== git mv
274++
285275 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.
286276
287--We only briefly mention this command in <<ch02-git-basics-chapter#_git_mv>>.
288--
289--==== git clean
290-+We only briefly mention this command in <<ch02-git-basics#r_git_mv>>.
277+-We only briefly mention this command in <<ch02-git-basics#r_git_mv>>.
278++We only briefly mention this command in <<ch02-git-basics-chapter#_git_mv>>.
279++
280++==== git clean
291281
292282 The `git clean` command is used to remove unwanted files from your working directory.
293283 This could include removing temporary build artifacts or merge conflict files.
294284
295--We cover many of the options and scenarios in which you might used the clean command in <<ch07-git-tools#_git_clean>>.
296-+We cover many of the options and scenarios in which you might used the clean command in <<ch07-git-tools#r_git_clean>>.
285+-We cover many of the options and scenarios in which you might used the clean command in <<ch07-git-tools#r_git_clean>>.
286++We cover many of the options and scenarios in which you might used the clean command in <<ch07-git-tools#_git_clean>>.
297287
298288 === Branching and Merging
299289
300290 There are just a handful of commands that implement most of the branching and merging functionality in Git.
301291
302--==== git branch
303--
292++==== git branch
293++
304294 The `git branch` command is actually something of a branch management tool.
305295 It can list the branches you have, create a new branch, delete branches and rename branches.
306296
307297 Most of <<ch03-git-branching#ch03-git-branching>> is dedicated to the `branch` command and it's used throughout the entire chapter.
308--We first introduce it in <<ch03-git-branching#_create_new_branch>> and we go through most of its other features (listing and deleting) in <<ch03-git-branching#_branch_management>>.
309--
310--In <<ch03-git-branching#_tracking_branches>> we use the `git branch -u` option to set up a tracking branch.
311-+We first introduce it in <<ch03-git-branching#r_create_new_branch>> and we go through most of its other features (listing and deleting) in <<ch03-git-branching#r_branch_management>>.
298+-We first introduce it in <<ch03-git-branching#r_create_new_branch>> and we go through most of its other features (listing and deleting) in <<ch03-git-branching#r_branch_management>>.
299++We first introduce it in <<ch03-git-branching#_create_new_branch>> and we go through most of its other features (listing and deleting) in <<ch03-git-branching#_branch_management>>.
300++
301++In <<ch03-git-branching#_tracking_branches>> we use the `git branch -u` option to set up a tracking branch.
312302
313--Finally, we go through some of what it does in the background in <<ch10-git-internals#_git_refs>>.
314-+In <<ch03-git-branching#r_tracking_branches>> we use the `git branch -u` option to set up a tracking branch.
303+-In <<ch03-git-branching#r_tracking_branches>> we use the `git branch -u` option to set up a tracking branch.
304++Finally, we go through some of what it does in the background in <<ch10-git-internals#_git_refs>>.
315305
316--==== git checkout
317-+Finally, we go through some of what it does in the background in <<ch10-git-internals#r_git_refs>>.
306+-Finally, we go through some of what it does in the background in <<ch10-git-internals#r_git_refs>>.
307++==== git checkout
318308
319309 The `git checkout` command is used to switch branches and check content out into your working directory.
320310
321--We first encounter the command in <<ch03-git-branching#_switching_branches>> along with the `git branch` command.
322-+We first encounter the command in <<ch03-git-branching#r_switching_branches>> along with the `git branch` command.
311+-We first encounter the command in <<ch03-git-branching#r_switching_branches>> along with the `git branch` command.
312++We first encounter the command in <<ch03-git-branching#_switching_branches>> along with the `git branch` command.
323313
324--We see how to use it to start tracking branches with the `--track` flag in <<ch03-git-branching#_tracking_branches>>.
325-+We see how to use it to start tracking branches with the `--track` flag in <<ch03-git-branching#r_tracking_branches>>.
314+-We see how to use it to start tracking branches with the `--track` flag in <<ch03-git-branching#r_tracking_branches>>.
315++We see how to use it to start tracking branches with the `--track` flag in <<ch03-git-branching#_tracking_branches>>.
326316
327--We use it to reintroduce file conflicts with `--conflict=diff3` in <<ch07-git-tools#_checking_out_conflicts>>.
328-+We use it to reintroduce file conflicts with `--conflict=diff3` in <<ch07-git-tools#r_checking_out_conflicts>>.
317+-We use it to reintroduce file conflicts with `--conflict=diff3` in <<ch07-git-tools#r_checking_out_conflicts>>.
318++We use it to reintroduce file conflicts with `--conflict=diff3` in <<ch07-git-tools#_checking_out_conflicts>>.
329319
330--We go into closer detail on its relationship with `git reset` in <<ch07-git-tools#_git_reset>>.
331-+We go into closer detail on its relationship with `git reset` in <<ch07-git-tools#r_git_reset>>.
320+-We go into closer detail on its relationship with `git reset` in <<ch07-git-tools#r_git_reset>>.
321++We go into closer detail on its relationship with `git reset` in <<ch07-git-tools#_git_reset>>.
332322
333--Finally, we go into some implementation detail in <<ch10-git-internals#ref_the_ref>>.
334--
335--==== git merge
336-+Finally, we go into some implementation detail in <<ch10-git-internals#r_the_head>>.
323+-Finally, we go into some implementation detail in <<ch10-git-internals#r_the_head>>.
324++Finally, we go into some implementation detail in <<ch10-git-internals#ref_the_ref>>.
325++
326++==== git merge
337327
338328 The `git merge` tool is used to merge one or more branches into the branch you have checked out.
339329 It will then advance the current branch to the result of the merge.
340330
341--The `git merge` command was first introduced in <<ch03-git-branching#_basic_branching>>.
342-+The `git merge` command was first introduced in <<ch03-git-branching#r_basic_branching>>.
331+-The `git merge` command was first introduced in <<ch03-git-branching#r_basic_branching>>.
332++The `git merge` command was first introduced in <<ch03-git-branching#_basic_branching>>.
343333 Though it is used in various places in the book, there are very few variations of the `merge` command -- generally just `git merge <branch>` with the name of the single branch you want to merge in.
344334
345--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 <<ch05-distributed-git#_public_project>>.
346--
347--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 <<ch07-git-tools#_advanced_merging>>.
348-+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 <<ch05-distributed-git#r_public_project>>.
335+-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 <<ch05-distributed-git#r_public_project>>.
336++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 <<ch05-distributed-git#_public_project>>.
337++
338++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 <<ch07-git-tools#_advanced_merging>>.
349339
350--We learned how to verify signatures before merging if your project is using GPG signing in <<ch07-git-tools#_signing_commits>>.
351-+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 <<ch07-git-tools#r_advanced_merging>>.
340+-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 <<ch07-git-tools#r_advanced_merging>>.
341++We learned how to verify signatures before merging if your project is using GPG signing in <<ch07-git-tools#_signing_commits>>.
352342
353--Finally, we learned about Subtree merging in <<ch07-git-tools#_subtree_merge>>.
354-+We learned how to verify signatures before merging if your project is using GPG signing in <<ch07-git-tools#r_signing_commits>>.
343+-We learned how to verify signatures before merging if your project is using GPG signing in <<ch07-git-tools#r_signing_commits>>.
344++Finally, we learned about Subtree merging in <<ch07-git-tools#_subtree_merge>>.
355345
356--==== git mergetool
357-+Finally, we learned about Subtree merging in <<ch07-git-tools#r_subtree_merge>>.
346+-Finally, we learned about Subtree merging in <<ch07-git-tools#r_subtree_merge>>.
347++==== git mergetool
358348
359349 The `git mergetool` command simply launches an external merge helper in case you have issues with a merge in Git.
360350
361--We mention it quickly in <<ch03-git-branching#_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<ch08-customizing-git#_external_merge_tools>>.
362--
363--==== git log
364-+We mention it quickly in <<ch03-git-branching#r_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<ch08-customizing-git#r_external_merge_tools>>.
351+-We mention it quickly in <<ch03-git-branching#r_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<ch08-customizing-git#r_external_merge_tools>>.
352++We mention it quickly in <<ch03-git-branching#_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<ch08-customizing-git#_external_merge_tools>>.
353++
354++==== git log
365355
366356 The `git log` command is used to show the reachable recorded history of a project from the most recent commit snapshot backwards.
367357 By default it will only show the history of the branch you're currently on, but can be given different or even multiple heads or branches from which to traverse.
368-@@ -281,305 +198,244 @@
358+@@ -198,244 +281,305 @@
369359
370360 This command is used in nearly every chapter of the book to demonstrate the history of a project.
371361
372--We introduce the command and cover it in some depth in <<ch02-git-basics-chapter#_viewing_history>>.
373-+We introduce the command and cover it in some depth in <<ch02-git-basics#r_viewing_history>>.
362+-We introduce the command and cover it in some depth in <<ch02-git-basics#r_viewing_history>>.
363++We introduce the command and cover it in some depth in <<ch02-git-basics-chapter#_viewing_history>>.
374364 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.
375365
376--In <<ch03-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.
377-+In <<ch03-git-branching#r_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.
366+-In <<ch03-git-branching#r_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.
367++In <<ch03-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.
378368
379--In <<ch05-distributed-git#_private_team>> and <<ch07-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.
380--In <<ch07-git-tools#_commit_ranges>> we go through this fairly extensively.
381-+In <<ch05-distributed-git#r_private_team>> and <<ch07-git-tools#r_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.
382-+In <<ch07-git-tools#r_commit_ranges>> we go through this fairly extensively.
369+-In <<ch05-distributed-git#r_private_team>> and <<ch07-git-tools#r_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.
370+-In <<ch07-git-tools#r_commit_ranges>> we go through this fairly extensively.
371++In <<ch05-distributed-git#_private_team>> and <<ch07-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.
372++In <<ch07-git-tools#_commit_ranges>> we go through this fairly extensively.
383373
384--In <<ch07-git-tools#_merge_log>> and <<ch07-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.
385--In <<ch07-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.
386-+In <<ch07-git-tools#r_merge_log>> and <<ch07-git-tools#r_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.
387-+In <<ch07-git-tools#r_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.
374+-In <<ch07-git-tools#r_merge_log>> and <<ch07-git-tools#r_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.
375+-In <<ch07-git-tools#r_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.
376++In <<ch07-git-tools#_merge_log>> and <<ch07-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.
377++In <<ch07-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.
388378
389--In <<ch07-git-tools#_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal.
390-+In <<ch07-git-tools#r_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal.
379+-In <<ch07-git-tools#r_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal.
380++In <<ch07-git-tools#_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal.
391381
392--In <<ch07-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.
393-+In <<ch07-git-tools#r_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.
382+-In <<ch07-git-tools#r_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.
383++In <<ch07-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.
394384
395--In <<ch07-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.
396--
397--==== git stash
398-+In <<ch07-git-tools#r_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.
385+-In <<ch07-git-tools#r_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.
386++In <<ch07-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.
387++
388++==== git stash
399389
400390 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.
401391
402--This is basically entirely covered in <<ch07-git-tools#_git_stashing>>.
403--
404--==== git tag
405-+This is basically entirely covered in <<ch07-git-tools#r_git_stashing>>.
392+-This is basically entirely covered in <<ch07-git-tools#r_git_stashing>>.
393++This is basically entirely covered in <<ch07-git-tools#_git_stashing>>.
394++
395++==== git tag
406396
407397 The `git tag` command is used to give a permanent bookmark to a specific point in the code history.
408398 Generally this is used for things like releases.
409399
410--This command is introduced and covered in detail in <<ch02-git-basics-chapter#_git_tagging>> and we use it in practice in <<ch05-distributed-git#_tagging_releases>>.
411--
412--We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<ch07-git-tools#_signing>>.
413-+This command is introduced and covered in detail in <<ch02-git-basics#r_git_tagging>> and we use it in practice in <<ch05-distributed-git#r_tagging_releases>>.
400+-This command is introduced and covered in detail in <<ch02-git-basics#r_git_tagging>> and we use it in practice in <<ch05-distributed-git#r_tagging_releases>>.
401++This command is introduced and covered in detail in <<ch02-git-basics-chapter#_git_tagging>> and we use it in practice in <<ch05-distributed-git#_tagging_releases>>.
402++
403++We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<ch07-git-tools#_signing>>.
414404
415-+We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<ch07-git-tools#r_signing>>.
405+-We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<ch07-git-tools#r_signing>>.
416406
417407 === Sharing and Updating Projects
418408
419409 There are not very many commands in Git that access the network, nearly all of the commands operate on the local database.
420410 When you are ready to share your work or pull changes from elsewhere, there are a handful of commands that deal with remote repositories.
421411
422--==== git fetch
423--
412++==== git fetch
413++
424414 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.
425415
426--We first look at this command in <<ch02-git-basics-chapter#_fetching_and_pulling>> and we continue to see examples of its use in <<ch03-git-branching#_remote_branches>>.
427--
428--We also use it in several of the examples in <<ch05-distributed-git#_contributing_project>>.
429-+We first look at this command in <<ch02-git-basics#r_fetching_and_pulling>> and we continue to see examples of it use in <<ch03-git-branching#r_remote_branches>>.
416+-We first look at this command in <<ch02-git-basics#r_fetching_and_pulling>> and we continue to see examples of it use in <<ch03-git-branching#r_remote_branches>>.
417++We first look at this command in <<ch02-git-basics-chapter#_fetching_and_pulling>> and we continue to see examples of its use in <<ch03-git-branching#_remote_branches>>.
418++
419++We also use it in several of the examples in <<ch05-distributed-git#_contributing_project>>.
430420
431--We use it to fetch a single specific reference that is outside of the default space in <<ch06-github#_pr_refs>> and we see how to fetch from a bundle in <<ch07-git-tools#_bundling>>.
432-+We also use it in several of the examples in <<ch05-distributed-git#r_contributing_project>>.
421+-We also use it in several of the examples in <<ch05-distributed-git#r_contributing_project>>.
422++We use it to fetch a single specific reference that is outside of the default space in <<ch06-github#_pr_refs>> and we see how to fetch from a bundle in <<ch07-git-tools#_bundling>>.
433423
434--We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<ch10-git-internals#_refspec>>.
435-+We use it to fetch a single specific reference that is outside of the default space in <<ch06-github#r_pr_refs>> and we see how to fetch from a bundle in <<ch07-git-tools#r_bundling>>.
424+-We use it to fetch a single specific reference that is outside of the default space in <<ch06-github#r_pr_refs>> and we see how to fetch from a bundle in <<ch07-git-tools#r_bundling>>.
425++We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<ch10-git-internals#_refspec>>.
436426
437--==== git pull
438-+We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<ch10-git-internals#r_refspec>>.
427+-We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<ch10-git-internals#r_refspec>>.
428++==== git pull
439429
440430 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.
441431
442--We introduce it quickly in <<ch02-git-basics-chapter#_fetching_and_pulling>> and show how to see what it will merge if you run it in <<ch02-git-basics-chapter#_inspecting_remote>>.
443--
444--We also see how to use it to help with rebasing difficulties in <<ch03-git-branching#_rebase_rebase>>.
445-+We introduce it quickly in <<ch02-git-basics#r_fetching_and_pulling>> and show how to see what it will merge if you run it in <<ch02-git-basics#r_inspecting_remote>>.
432+-We introduce it quickly in <<ch02-git-basics#r_fetching_and_pulling>> and show how to see what it will merge if you run it in <<ch02-git-basics#r_inspecting_remote>>.
433++We introduce it quickly in <<ch02-git-basics-chapter#_fetching_and_pulling>> and show how to see what it will merge if you run it in <<ch02-git-basics-chapter#_inspecting_remote>>.
434++
435++We also see how to use it to help with rebasing difficulties in <<ch03-git-branching#_rebase_rebase>>.
446436
447--We show how to use it with a URL to pull in changes in a one-off fashion in <<ch05-distributed-git#_checking_out_remotes>>.
448-+We also see how to use it to help with rebasing difficulties in <<ch03-git-branching#r_rebase_rebase>>.
437+-We also see how to use it to help with rebasing difficulties in <<ch03-git-branching#r_rebase_rebase>>.
438++We show how to use it with a URL to pull in changes in a one-off fashion in <<ch05-distributed-git#_checking_out_remotes>>.
449439
450--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 <<ch07-git-tools#_signing_commits>>.
451-+We show how to use it with a URL to pull in changes in a one-off fashion in <<ch05-distributed-git#r_checking_out_remotes>>.
440+-We show how to use it with a URL to pull in changes in a one-off fashion in <<ch05-distributed-git#r_checking_out_remotes>>.
441++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 <<ch07-git-tools#_signing_commits>>.
452442
453--==== git push
454-+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 <<ch07-git-tools#r_signing_commits>>.
443+-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 <<ch07-git-tools#r_signing_commits>>.
444++==== git push
455445
456446 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.
457447 It requires write access to the other repository and so normally is authenticated somehow.
458448
459--We first look at the `git push` command in <<ch02-git-basics-chapter#_pushing_remotes>>.
460-+We first look at the `git push` command in <<ch02-git-basics#r_pushing_remotes>>.
449+-We first look at the `git push` command in <<ch02-git-basics#r_pushing_remotes>>.
450++We first look at the `git push` command in <<ch02-git-basics-chapter#_pushing_remotes>>.
461451 Here we cover the basics of pushing a branch to a remote repository.
462--In <<ch03-git-branching#_pushing_branches>> we go a little deeper into pushing specific branches and in <<ch03-git-branching#_tracking_branches>> we see how to set up tracking branches to automatically push to.
463--In <<ch03-git-branching#_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`.
464-+In <<ch03-git-branching#r_pushing_branches>> we go a little deeper into pushing specific branches and in <<ch03-git-branching#r_tracking_branches>> we see how to set up tracking branches to automatically push to.
465-+In <<ch03-git-branching#r_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`.
452+-In <<ch03-git-branching#r_pushing_branches>> we go a little deeper into pushing specific branches and in <<ch03-git-branching#r_tracking_branches>> we see how to set up tracking branches to automatically push to.
453+-In <<ch03-git-branching#r_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`.
454++In <<ch03-git-branching#_pushing_branches>> we go a little deeper into pushing specific branches and in <<ch03-git-branching#_tracking_branches>> we see how to set up tracking branches to automatically push to.
455++In <<ch03-git-branching#_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`.
466456
467--Throughout <<ch05-distributed-git#_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes.
468-+Throughout <<ch05-distributed-git#r_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes.
457+-Throughout <<ch05-distributed-git#r_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes.
458++Throughout <<ch05-distributed-git#_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes.
469459
470--We see how to use it to share tags that you have made with the `--tags` option in <<ch02-git-basics-chapter#_sharing_tags>>.
471-+We see how to use it to share tags that you have made with the `--tags` option in <<ch02-git-basics#r_sharing_tags>>.
460+-We see how to use it to share tags that you have made with the `--tags` option in <<ch02-git-basics#r_sharing_tags>>.
461++We see how to use it to share tags that you have made with the `--tags` option in <<ch02-git-basics-chapter#_sharing_tags>>.
472462
473--In <<ch07-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.
474-+In <<ch07-git-tools#r_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.
463+-In <<ch07-git-tools#r_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.
464++In <<ch07-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.
475465
476--In <<ch08-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.
477-+In <<ch08-customizing-git#r_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.
466+-In <<ch08-customizing-git#r_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.
467++In <<ch08-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.
478468
479--Finally, in <<ch10-git-internals#_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used.
480-+Finally, in <<ch10-git-internals#r_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used.
469+-Finally, in <<ch10-git-internals#r_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used.
470++Finally, in <<ch10-git-internals#_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used.
481471 This can help you be very specific about what work you wish to share.
482472
483--==== git remote
484--
473++==== git remote
474++
485475 The `git remote` command is a management tool for your record of remote repositories.
486476 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.
487477 You can have several of these and the `git remote` command is used to add, change and delete them.
488478
489--This command is covered in detail in <<ch02-git-basics-chapter#_remote_repos>>, including listing, adding, removing and renaming them.
490-+This command is covered in detail in <<ch02-git-basics#r_remote_repos>>, including listing, adding, removing and renaming them.
479+-This command is covered in detail in <<ch02-git-basics#r_remote_repos>>, including listing, adding, removing and renaming them.
480++This command is covered in detail in <<ch02-git-basics-chapter#_remote_repos>>, including listing, adding, removing and renaming them.
491481
492482 It is used in nearly every subsequent chapter in the book too, but always in the standard `git remote add <name> <url>` format.
493483
494--==== git archive
495--
484++==== git archive
485++
496486 The `git archive` command is used to create an archive file of a specific snapshot of the project.
497487
498--We use `git archive` to create a tarball of a project for sharing in <<ch05-distributed-git#_preparing_release>>.
499--
500--==== git submodule
501-+We use `git archive` to create a tarball of a project for sharing in <<ch05-distributed-git#r_preparing_release>>.
488+-We use `git archive` to create a tarball of a project for sharing in <<ch05-distributed-git#r_preparing_release>>.
489++We use `git archive` to create a tarball of a project for sharing in <<ch05-distributed-git#_preparing_release>>.
490++
491++==== git submodule
502492
503493 The `git submodule` command is used to manage external repositories within a normal repositories.
504494 This could be for libraries or other types of shared resources.
505495 The `submodule` command has several sub-commands (`add`, `update`, `sync`, etc) for managing these resources.
506496
507--This command is only mentioned and entirely covered in <<ch07-git-tools#_git_submodules>>.
508-+This command is only mentioned and entirely covered in <<ch07-git-tools#r_git_submodules>>.
497+-This command is only mentioned and entirely covered in <<ch07-git-tools#r_git_submodules>>.
498++This command is only mentioned and entirely covered in <<ch07-git-tools#_git_submodules>>.
509499
510500 === Inspection and Comparison
511501
512--==== git show
513--
502++==== git show
503++
514504 The `git show` command can show a Git object in a simple and human readable way.
515505 Normally you would use this to show the information about a tag or a commit.
516506
517--We first use it to show annotated tag information in <<ch02-git-basics-chapter#_annotated_tags>>.
518-+We first use it to show annotated tag information in <<ch02-git-basics#r_annotated_tags>>.
507+-We first use it to show annotated tag information in <<ch02-git-basics#r_annotated_tags>>.
508++We first use it to show annotated tag information in <<ch02-git-basics-chapter#_annotated_tags>>.
519509
520--Later we use it quite a bit in <<ch07-git-tools#_revision_selection>> to show the commits that our various revision selections resolve to.
521-+Later we use it quite a bit in <<ch07-git-tools#r_revision_selection>> to show the commits that our various revision selections resolve to.
510+-Later we use it quite a bit in <<ch07-git-tools#r_revision_selection>> to show the commits that our various revision selections resolve to.
511++Later we use it quite a bit in <<ch07-git-tools#_revision_selection>> to show the commits that our various revision selections resolve to.
522512
523--One of the more interesting things we do with `git show` is in <<ch07-git-tools#_manual_remerge>> to extract specific file contents of various stages during a merge conflict.
524--
525--==== git shortlog
526-+One of the more interesting things we do with `git show` is in <<ch07-git-tools#r_manual_remerge>> to extract specific file contents of various stages during a merge conflict.
513+-One of the more interesting things we do with `git show` is in <<ch07-git-tools#r_manual_remerge>> to extract specific file contents of various stages during a merge conflict.
514++One of the more interesting things we do with `git show` is in <<ch07-git-tools#_manual_remerge>> to extract specific file contents of various stages during a merge conflict.
515++
516++==== git shortlog
527517
528518 The `git shortlog` command is used to summarize the output of `git log`.
529519 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.
530520
531--We showed how to use it to create a nice changelog in <<ch05-distributed-git#_the_shortlog>>.
532--
533--==== git describe
534-+We showed how to use it to create a nice changelog in <<ch05-distributed-git#r_the_shortlog>>.
521+-We showed how to use it to create a nice changelog in <<ch05-distributed-git#r_the_shortlog>>.
522++We showed how to use it to create a nice changelog in <<ch05-distributed-git#_the_shortlog>>.
523++
524++==== git describe
535525
536526 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.
537527 It's a way to get a description of a commit that is as unambiguous as a commit SHA-1 but more understandable.
538528
539--We use `git describe` in <<ch05-distributed-git#_build_number>> and <<ch05-distributed-git#_preparing_release>> to get a string to name our release file after.
540--
541-+We use `git describe` in <<ch05-distributed-git#r_build_number>> and <<ch05-distributed-git#r_preparing_release>> to get a string to name our release file after.
529+-We use `git describe` in <<ch05-distributed-git#r_build_number>> and <<ch05-distributed-git#r_preparing_release>> to get a string to name our release file after.
530++We use `git describe` in <<ch05-distributed-git#_build_number>> and <<ch05-distributed-git#_preparing_release>> to get a string to name our release file after.
531++
542532
543533 === Debugging
544534
545535 Git has a couple of commands that are used to help debug an issue in your code.
546536 This ranges from figuring out where something was introduced to figuring out who introduced it.
547537
548--==== git bisect
549--
538++==== git bisect
539++
550540 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.
551541
552--It is fully covered in <<ch07-git-tools#_binary_search>> and is only mentioned in that section.
553--
554--==== git blame
555-+It is fully covered in <<ch07-git-tools#r_binary_search>> and is only mentioned in that section.
542+-It is fully covered in <<ch07-git-tools#r_binary_search>> and is only mentioned in that section.
543++It is fully covered in <<ch07-git-tools#_binary_search>> and is only mentioned in that section.
544++
545++==== git blame
556546
557547 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.
558548 This is helpful in order to find the person to ask for more information about a specific section of your code.
559549
560--It is covered in <<ch07-git-tools#_file_annotation>> and is only mentioned in that section.
561--
562--==== git grep
563-+It is covered in <<ch07-git-tools#r_file_annotation>> and is only mentioned in that section.
550+-It is covered in <<ch07-git-tools#r_file_annotation>> and is only mentioned in that section.
551++It is covered in <<ch07-git-tools#_file_annotation>> and is only mentioned in that section.
552++
553++==== git grep
564554
565555 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.
566556
567--It is covered in <<ch07-git-tools#_git_grep>> and is only mentioned in that section.
568-+It is covered in <<ch07-git-tools#r_git_grep>> and is only mentioned in that section.
557+-It is covered in <<ch07-git-tools#r_git_grep>> and is only mentioned in that section.
558++It is covered in <<ch07-git-tools#_git_grep>> and is only mentioned in that section.
569559
570560 === Patching
571561
572562 A few commands in Git are centered around the concept of thinking of commits in terms of the changes they introduce, as though the commit series is a series of patches.
573563 These commands help you manage your branches in this manner.
574564
575--==== git cherry-pick
576--
565++==== git cherry-pick
566++
577567 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.
578568 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.
579569
580--Cherry picking is described and demonstrated in <<ch05-distributed-git#_rebase_cherry_pick>>.
581--
582--==== git rebase
583-+Cherry picking is described and demonstrated in <<ch05-distributed-git#r_rebase_cherry_pick>>.
570+-Cherry picking is described and demonstrated in <<ch05-distributed-git#r_rebase_cherry_pick>>.
571++Cherry picking is described and demonstrated in <<ch05-distributed-git#_rebase_cherry_pick>>.
572++
573++==== git rebase
584574
585575 The `git rebase` command is basically an automated `cherry-pick`.
586576 It determines a series of commits and then cherry-picks them one by one in the same order somewhere else.
587577
588--Rebasing is covered in detail in <<ch03-git-branching#_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public.
589--
590--We use it in practice during an example of splitting your history into two separate repositories in <<ch07-git-tools#_replace>>, using the `--onto` flag as well.
591-+Rebasing is covered in detail in <<ch03-git-branching#r_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public.
578+-Rebasing is covered in detail in <<ch03-git-branching#r_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public.
579++Rebasing is covered in detail in <<ch03-git-branching#_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public.
580++
581++We use it in practice during an example of splitting your history into two separate repositories in <<ch07-git-tools#_replace>>, using the `--onto` flag as well.
592582
593--We go through running into a merge conflict during rebasing in <<ch07-git-tools#ref_rerere>>.
594-+We use it in practice during an example of splitting your history into two separate repositories in <<ch07-git-tools#r_replace>>, using the `--onto` flag as well.
583+-We use it in practice during an example of splitting your history into two separate repositories in <<ch07-git-tools#r_replace>>, using the `--onto` flag as well.
584++We go through running into a merge conflict during rebasing in <<ch07-git-tools#ref_rerere>>.
595585
596--We also use it in an interactive scripting mode with the `-i` option in <<ch07-git-tools#_changing_multiple>>.
597-+We go through running into a merge conflict during rebasing in <<ch07-git-tools#r_rerere>>.
586+-We go through running into a merge conflict during rebasing in <<ch07-git-tools#r_rerere>>.
587++We also use it in an interactive scripting mode with the `-i` option in <<ch07-git-tools#_changing_multiple>>.
598588
599--==== git revert
600-+We also use it in an interactive scripting mode with the `-i` option in <<ch07-git-tools#r_changing_multiple>>.
589+-We also use it in an interactive scripting mode with the `-i` option in <<ch07-git-tools#r_changing_multiple>>.
590++==== git revert
601591
602592 The `git revert` command is essentially a reverse `git cherry-pick`.
603593 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.
604594
605--We use this in <<ch07-git-tools#_reverse_commit>> to undo a merge commit.
606-+We use this in <<ch07-git-tools#r_reverse_commit>> to undo a merge commit.
595+-We use this in <<ch07-git-tools#r_reverse_commit>> to undo a merge commit.
596++We use this in <<ch07-git-tools#_reverse_commit>> to undo a merge commit.
607597
608598 === Email
609599
610600 Many Git projects, including Git itself, are entirely maintained over mailing lists.
611601 Git has a number of tools built into it that help make this process easier, from generating patches you can easily email to applying those patches from an email box.
612602
613--==== git apply
614--
603++==== git apply
604++
615605 The `git apply` command applies a patch created with the `git diff` or even GNU diff command.
616606 It is similar to what the `patch` command might do with a few small differences.
617607
618--We demonstrate using it and the circumstances in which you might do so in <<ch05-distributed-git#_patches_from_email>>.
619--
620--==== git am
621-+We demonstrate using it and the circumstances in which you might do so in <<ch05-distributed-git#r_patches_from_email>>.
608+-We demonstrate using it and the circumstances in which you might do so in <<ch05-distributed-git#r_patches_from_email>>.
609++We demonstrate using it and the circumstances in which you might do so in <<ch05-distributed-git#_patches_from_email>>.
610++
611++==== git am
622612
623613 The `git am` command is used to apply patches from an email inbox, specifically one that is mbox formatted.
624614 This is useful for receiving patches over email and applying them to your project easily.
625615
626--We covered usage and workflow around `git am` in <<ch05-distributed-git#_git_am>> including using the `--resolved`, `-i` and `-3` options.
627-+We covered usage and workflow around `git am` in <<ch05-distributed-git#r_git_am>> including using the `--resolved`, `-i` and `-3` options.
616+-We covered usage and workflow around `git am` in <<ch05-distributed-git#r_git_am>> including using the `--resolved`, `-i` and `-3` options.
617++We covered usage and workflow around `git am` in <<ch05-distributed-git#_git_am>> including using the `--resolved`, `-i` and `-3` options.
628618
629--There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<ch08-customizing-git#_email_hooks>>.
630-+There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<ch08-customizing-git#r_email_hooks>>.
619+-There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<ch08-customizing-git#r_email_hooks>>.
620++There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<ch08-customizing-git#_email_hooks>>.
631621
632--We also use it to apply patch formatted GitHub Pull Request changes in <<ch06-github#_email_notifications>>.
633--
634--==== git format-patch
635-+We also use it to apply patch formatted GitHub Pull Request changes in <<ch06-github#r_email_notifications>>.
622+-We also use it to apply patch formatted GitHub Pull Request changes in <<ch06-github#r_email_notifications>>.
623++We also use it to apply patch formatted GitHub Pull Request changes in <<ch06-github#_email_notifications>>.
624++
625++==== git format-patch
636626
637627 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.
638628
639--We go through an example of contributing to a project using the `git format-patch` tool in <<ch05-distributed-git#_project_over_email>>.
640--
641--==== git imap-send
642-+We go through an example of contributing to a project using the `git format-patch` tool in <<ch05-distributed-git#r_project_over_email>>.
629+-We go through an example of contributing to a project using the `git format-patch` tool in <<ch05-distributed-git#r_project_over_email>>.
630++We go through an example of contributing to a project using the `git format-patch` tool in <<ch05-distributed-git#_project_over_email>>.
631++
632++==== git imap-send
643633
644634 The `git imap-send` command uploads a mailbox generated with `git format-patch` into an IMAP drafts folder.
645635
646--We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<ch05-distributed-git#_project_over_email>>.
647--
648--==== git send-email
649-+We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<ch05-distributed-git#r_project_over_email>>.
636+-We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<ch05-distributed-git#r_project_over_email>>.
637++We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<ch05-distributed-git#_project_over_email>>.
638++
639++==== git send-email
650640
651641 The `git send-email` command is used to send patches that are generated with `git format-patch` over email.
652642
653--We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<ch05-distributed-git#_project_over_email>>.
654--
655--==== git request-pull
656-+We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<ch05-distributed-git#r_project_over_email>>.
643+-We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<ch05-distributed-git#r_project_over_email>>.
644++We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<ch05-distributed-git#_project_over_email>>.
645++
646++==== git request-pull
657647
658648 The `git request-pull` command is simply used to generate an example message body to email to someone.
659649 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.
660650
661--We demonstrate how to use `git request-pull` to generate a pull message in <<ch05-distributed-git#_public_project>>.
662-+We demonstrate how to use `git request-pull` to generate a pull message in <<ch05-distributed-git#r_public_project>>.
651+-We demonstrate how to use `git request-pull` to generate a pull message in <<ch05-distributed-git#r_public_project>>.
652++We demonstrate how to use `git request-pull` to generate a pull message in <<ch05-distributed-git#_public_project>>.
663653
664654 === External Systems
665655
666656 Git comes with a few commands to integrate with other version control systems.
667657
668--==== git svn
669--
658++==== git svn
659++
670660 The `git svn` command is used to communicate with the Subversion version control system as a client.
671661 This means you can use Git to checkout from and commit to a Subversion server.
672662
673--This command is covered in depth in <<ch09-git-and-other-systems#_git_svn>>.
674--
675--==== git fast-import
676-+This command is covered in depth in <<ch09-git-and-other-scms#r_git_svn>>.
663+-This command is covered in depth in <<ch09-git-and-other-scms#r_git_svn>>.
664++This command is covered in depth in <<ch09-git-and-other-systems#_git_svn>>.
665++
666++==== git fast-import
677667
678668 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.
679669
680--This command is covered in depth in <<ch09-git-and-other-systems#_custom_importer>>.
681-+This command is covered in depth in <<ch09-git-and-other-scms#r_custom_importer>>.
670+-This command is covered in depth in <<ch09-git-and-other-scms#r_custom_importer>>.
671++This command is covered in depth in <<ch09-git-and-other-systems#_custom_importer>>.
682672
683673 === Administration
684674
685675 If you're administering a Git repository or need to fix something in a big way, Git provides a number of administrative commands to help you out.
686676
687--==== git gc
688--
677++==== git gc
678++
689679 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.
690680
691681 This command normally runs in the background for you, though you can manually run it if you wish.
692--We go over some examples of this in <<ch10-git-internals#_git_gc>>.
693--
694--==== git fsck
695-+We go over some examples of this in <<ch10-git-internals#r_git_gc>>.
682+-We go over some examples of this in <<ch10-git-internals#r_git_gc>>.
683++We go over some examples of this in <<ch10-git-internals#_git_gc>>.
684++
685++==== git fsck
696686
697687 The `git fsck` command is used to check the internal database for problems or inconsistencies.
698688
699--We only quickly use this once in <<ch10-git-internals#_data_recovery>> to search for dangling objects.
700--
701--==== git reflog
702-+We only quickly use this once in <<ch10-git-internals#r_data_recovery>> to search for dangling objects.
689+-We only quickly use this once in <<ch10-git-internals#r_data_recovery>> to search for dangling objects.
690++We only quickly use this once in <<ch10-git-internals#_data_recovery>> to search for dangling objects.
691++
692++==== git reflog
703693
704694 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.
705695
706--We cover this command mainly in <<ch07-git-tools#_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output.
707--
708--We also go through a practical example of recovering such a lost branch in <<ch10-git-internals#_data_recovery>>.
709-+We cover this command mainly in <<ch07-git-tools#r_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output.
696+-We cover this command mainly in <<ch07-git-tools#r_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output.
697++We cover this command mainly in <<ch07-git-tools#_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output.
698++
699++We also go through a practical example of recovering such a lost branch in <<ch10-git-internals#_data_recovery>>.
710700
711--==== git filter-branch
712-+We also go through a practical example of recovering such a lost branch in <<ch10-git-internals#r_data_recovery>>.
701+-We also go through a practical example of recovering such a lost branch in <<ch10-git-internals#r_data_recovery>>.
702++==== git filter-branch
713703
714704 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.
715705
716--In <<ch07-git-tools#_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`.
717--
718--In <<ch09-git-and-other-systems#_git_p4>> we use it to fix up imported external repositories.
719-+In <<ch07-git-tools#r_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`.
706+-In <<ch07-git-tools#r_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`.
707++In <<ch07-git-tools#_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`.
708++
709++In <<ch09-git-and-other-systems#_git_p4>> we use it to fix up imported external repositories.
720710
721-+In <<ch09-git-and-other-scms#r_git_p4>> and <<ch09-git-and-other-scms#r_git_tfs>> we use it to fix up imported external repositories.
711+-In <<ch09-git-and-other-scms#r_git_p4>> and <<ch09-git-and-other-scms#r_git_tfs>> we use it to fix up imported external repositories.
722712
723713 === Plumbing Commands
724714
725715 There were also quite a number of lower level plumbing commands that we encountered in the book.
726716
727--The first one we encounter is `ls-remote` in <<ch06-github#_pr_refs>> which we use to look at the raw references on the server.
728-+The first one we encounter is `ls-remote` in <<ch06-github#r_pr_refs>> which we use to look at the raw references on the server.
717+-The first one we encounter is `ls-remote` in <<ch06-github#r_pr_refs>> which we use to look at the raw references on the server.
718++The first one we encounter is `ls-remote` in <<ch06-github#_pr_refs>> which we use to look at the raw references on the server.
729719
730--We use `ls-files` in <<ch07-git-tools#_manual_remerge>>, <<ch07-git-tools#ref_rerere>> and <<ch07-git-tools#_the_index>> to take a more raw look at what your staging area looks like.
731-+We use `ls-files` in <<ch07-git-tools#r_manual_remerge>>, <<ch07-git-tools#r_rerere>> and <<ch07-git-tools#r_the_index>> to take a more raw look at what your staging area looks like.
720+-We use `ls-files` in <<ch07-git-tools#r_manual_remerge>>, <<ch07-git-tools#r_rerere>> and <<ch07-git-tools#r_the_index>> to take a more raw look at what your staging area looks like.
721++We use `ls-files` in <<ch07-git-tools#_manual_remerge>>, <<ch07-git-tools#ref_rerere>> and <<ch07-git-tools#_the_index>> to take a more raw look at what your staging area looks like.
732722
733--We also mention `rev-parse` in <<ch07-git-tools#_branch_references>> to take just about any string and turn it into an object SHA-1.
734-+We also mention `rev-parse` in <<ch07-git-tools#r_branch_references>> to take just about any string and turn it into an object SHA-1.
723+-We also mention `rev-parse` in <<ch07-git-tools#r_branch_references>> to take just about any string and turn it into an object SHA-1.
724++We also mention `rev-parse` in <<ch07-git-tools#_branch_references>> to take just about any string and turn it into an object SHA-1.
735725
736726 However, most of the low level plumbing commands we cover are in <<ch10-git-internals#ch10-git-internals>>, which is more or less what the chapter is focused on.
737727 We tried to avoid use of them throughout most of the rest of the book.
738-diff -au ../../git/progit2/progit2/LICENSE.asc /tmp/LICENSE.asc.tmp
739---- ../../git/progit2/progit2/LICENSE.asc 2020-06-28 16:44:50.900011670 +0900
740-+++ /tmp/LICENSE.asc.tmp 2020-10-25 09:24:25.552961813 +0900
741-@@ -1,2 +0,0 @@
742--This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
743--To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
744-diff -au ../../git/progit2/progit2/README.asc /tmp/README.asc.tmp
745---- ../../git/progit2/progit2/README.asc 2020-09-07 09:33:11.246683703 +0900
746-+++ /tmp/README.asc.tmp 2020-10-25 09:24:25.563962332 +0900
747-@@ -1,22 +1,51 @@
748-+= Pro Git 第2版 日本語翻訳
749-+
750-+このリポジトリを使って、Pro Git第2版の日本語翻訳作業を進めています。
751-+
752-+- 翻訳を手伝ってみたい
753-+- 書いてある技術的内容or日本語が間違ってるんだけど
754-+- どうやって電子書籍データを生成してるんですか?
755-+
756-+などなど、興味を持っていただいた方を歓迎しています。何かありましたら https://github.com/progit/progit2-ja/issues/[Issue] をたてていただくか、メンテナの https://twitter.com/harupong[@harupong] までご連絡いただければ幸いです。
757-+
758-+== 翻訳作業のお約束
759-+
760-+翻訳のお手伝いは大歓迎です。以下の2点を踏まえ、ぜひご協力いただければと思っています。
761-+
762-+1. 作業を始めるときは意思表示をしてください
763-+1. 既訳を尊重してください
764-+
765-+具体的な作業手順など、詳しいことは link:TRANSLATION_NOTES.asc[TRANSLATION NOTES] を確認してください。
766-+
767-+''''''''''''''''''''''''''
768-+(Below is the translation of original README.asc in English. 以下は英語READMEの翻訳です。)
769-+
728+diff -au /tmp/LICENSE.asc.tmp ../../git/progit2/progit2/LICENSE.asc
729+--- /tmp/LICENSE.asc.tmp 2020-10-25 11:05:02.088630679 +0900
730++++ ../../git/progit2/progit2/LICENSE.asc 2020-06-28 16:44:50.900011670 +0900
731+@@ -0,0 +1,2 @@
732++This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
733++To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
734+diff -au /tmp/README.asc.tmp ../../git/progit2/progit2/README.asc
735+--- /tmp/README.asc.tmp 2020-10-25 11:05:02.092630904 +0900
736++++ ../../git/progit2/progit2/README.asc 2020-09-07 09:33:11.246683703 +0900
737+@@ -1,51 +1,22 @@
738+-= Pro Git 第2版 日本語翻訳
739+-
740+-このリポジトリを使って、Pro Git第2版の日本語翻訳作業を進めています。
741+-
742+-- 翻訳を手伝ってみたい
743+-- 書いてある技術的内容or日本語が間違ってるんだけど
744+-- どうやって電子書籍データを生成してるんですか?
745+-
746+-などなど、興味を持っていただいた方を歓迎しています。何かありましたら https://github.com/progit/progit2-ja/issues/[Issue] をたてていただくか、メンテナの https://twitter.com/harupong[@harupong] までご連絡いただければ幸いです。
747+-
748+-== 翻訳作業のお約束
749+-
750+-翻訳のお手伝いは大歓迎です。以下の2点を踏まえ、ぜひご協力いただければと思っています。
751+-
752+-1. 作業を始めるときは意思表示をしてください
753+-1. 既訳を尊重してください
754+-
755+-具体的な作業手順など、詳しいことは link:TRANSLATION_NOTES.asc[TRANSLATION NOTES] を確認してください。
756+-
757+-''''''''''''''''''''''''''
758+-(Below is the translation of original README.asc in English. 以下は英語READMEの翻訳です。)
759+-
770760 = Pro Git, Second Edition
771761
772762 Welcome to the second edition of the Pro Git book.
773763
774--You can find this book online at: https://git-scm.com/book
775-+You can find this book online at: http://git-scm.com/book
764+-You can find this book online at: http://git-scm.com/book
765++You can find this book online at: https://git-scm.com/book
776766
777767 Like the first edition, the second edition of Pro Git is open source under a Creative Commons license.
778768
779769 A couple of things have changed since open sourcing the first edition.
780--For one, we've moved from Markdown to the amazing AsciiDoc format for the text of the book; here's an https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc quick reference].
781-+For one, we've moved from Markdown to the amazing Asciidoc format for the text of the book.
782-+We've also moved to using O'Reilly's https://atlas.oreilly.com[Atlas platform] for generating continuous builds of the book so all major formats are always available in every language.
770+-For one, we've moved from Markdown to the amazing Asciidoc format for the text of the book.
771+-We've also moved to using O'Reilly's https://atlas.oreilly.com[Atlas platform] for generating continuous builds of the book so all major formats are always available in every language.
772++For one, we've moved from Markdown to the amazing AsciiDoc format for the text of the book; here's an https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc quick reference].
783773
784774 We've also moved to keeping the translations in separate repositories rather than subdirectories of the English repository.
785--See link:TRANSLATING.md[the translating document] for more information.
786-+See link:CONTRIBUTING.md[the Contributing document] for more information.
775+-See link:CONTRIBUTING.md[the Contributing document] for more information.
776++See link:TRANSLATING.md[the translating document] for more information.
787777
788778 == How To Generate the Book
789779
790--You can generate the e-book files manually with Asciidoctor.
791--We used to be able to build .mobi files (Kindle), but cannot do so now, see #1496 for more information.
792--If you run the following you _may_ actually get HTML, Epub and PDF output files:
793-+There are two ways to generate e-book content from this source code.
794-+
795-+The easiest way is simply to let us do it.
796-+A robot is standing by to look for new work on the main branch and automatically build it for everyone.
797-+
798-+You can find the current builds on http://git-scm.com/book[] and more information about the builds available at https://progit.org[].
799-+
800-+The other way to generate e-book files is to do so manually with Asciidoctor.
801-+If you run the following you _may_ actually get HTML, Epub, Mobi and PDF output files:
780+-There are two ways to generate e-book content from this source code.
781+-
782+-The easiest way is simply to let us do it.
783+-A robot is standing by to look for new work on the main branch and automatically build it for everyone.
784+-
785+-You can find the current builds on http://git-scm.com/book[] and more information about the builds available at https://progit.org[].
786+-
787+-The other way to generate e-book files is to do so manually with Asciidoctor.
788+-If you run the following you _may_ actually get HTML, Epub, Mobi and PDF output files:
789++You can generate the e-book files manually with Asciidoctor.
790++We used to be able to build .mobi files (Kindle), but cannot do so now, see #1496 for more information.
791++If you run the following you _may_ actually get HTML, Epub and PDF output files:
802792
803793 ----
804794 $ bundle install
805-@@ -25,17 +54,20 @@
795+@@ -54,20 +25,17 @@
806796 -- HTML output at progit.html
807797 Converting to EPub...
808798 -- Epub output at progit.epub
809-+Converting to Mobi (kf8)...
810-+ -- Mobi output at progit.mobi
799+-Converting to Mobi (kf8)...
800+- -- Mobi output at progit.mobi
811801 Converting to PDF...
812-- -- PDF output at progit.pdf
813-+ -- PDF output at progit.pdf
802+- -- PDF output at progit.pdf
803++ -- PDF output at progit.pdf
814804 ----
815805
816-+This uses the `asciidoctor`, `asciidoctor-pdf` and `asciidoctor-epub` projects.
817-+
806+-This uses the `asciidoctor`, `asciidoctor-pdf` and `asciidoctor-epub` projects.
807+-
818808 == Signaling an Issue
819809
820810 Before signaling an issue, please check that there isn't already a similar one in the bug tracking system.
821811
822--Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in this repo.
823--The issue may have already been corrected, but the changes have not been deployed yet.
824-+Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in the pdf version. The issue may have already been corrected, but the changes have not been deployed yet.
812+-Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in the pdf version. The issue may have already been corrected, but the changes have not been deployed yet.
813++Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in this repo.
814++The issue may have already been corrected, but the changes have not been deployed yet.
825815
826816 == Contributing
827817
828--If you'd like to help out by making a change, take a look at the link:CONTRIBUTING.md[contributor's guide].
829-+If you'd like to help out by making a change or contributing a translation, take a look at the link:CONTRIBUTING.md[contributor's guide].
830-diff -au ../../git/progit2/progit2/TRANSLATION_NOTES.asc /tmp/TRANSLATION_NOTES.asc.tmp
831---- ../../git/progit2/progit2/TRANSLATION_NOTES.asc 2020-06-28 16:44:50.919014468 +0900
832-+++ /tmp/TRANSLATION_NOTES.asc.tmp 2020-10-25 09:24:25.577962992 +0900
833-@@ -1,11 +0,0 @@
834--== Translation Notes
835--
836--After forking this repository to translate the work, this file is where the notes for coordinating the translation work would go.
837--Things like standardizing on words and expressions so that the work is consistent or notes on how the contributing process is to be handled.
838--
839--As a translation maintainer, also feel free to modify or completely rewrite the README file to contain instructions specific to your translation.
840--
841--=== Translation Status
842--
843--As the work is translated, please update the `status.json` file to indicate the rough percentage complete each file is.
844--This will be shown on various pages to let people know how much work is left to be done.
845-diff -au ../../git/progit2/progit2/book/01-introduction/sections/about-version-control.asc /tmp/book/01-introduction/sections/about-version-control.asc.tmp
846---- ../../git/progit2/progit2/book/01-introduction/sections/about-version-control.asc 2020-07-04 16:36:46.718685392 +0900
847-+++ /tmp/book/01-introduction/sections/about-version-control.asc.tmp 2020-10-25 09:24:25.587963463 +0900
848-@@ -1,60 +1,57 @@
818+-If you'd like to help out by making a change or contributing a translation, take a look at the link:CONTRIBUTING.md[contributor's guide].
819++If you'd like to help out by making a change, take a look at the link:CONTRIBUTING.md[contributor's guide].
820+diff -au /tmp/TRANSLATION_NOTES.asc.tmp ../../git/progit2/progit2/TRANSLATION_NOTES.asc
821+--- /tmp/TRANSLATION_NOTES.asc.tmp 2020-10-25 11:05:02.097631185 +0900
822++++ ../../git/progit2/progit2/TRANSLATION_NOTES.asc 2020-06-28 16:44:50.919014468 +0900
823+@@ -0,0 +1,11 @@
824++== Translation Notes
825++
826++After forking this repository to translate the work, this file is where the notes for coordinating the translation work would go.
827++Things like standardizing on words and expressions so that the work is consistent or notes on how the contributing process is to be handled.
828++
829++As a translation maintainer, also feel free to modify or completely rewrite the README file to contain instructions specific to your translation.
830++
831++=== Translation Status
832++
833++As the work is translated, please update the `status.json` file to indicate the rough percentage complete each file is.
834++This will be shown on various pages to let people know how much work is left to be done.
835+diff -au /tmp/book/01-introduction/sections/about-version-control.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/about-version-control.asc
836+--- /tmp/book/01-introduction/sections/about-version-control.asc.tmp 2020-10-25 11:05:02.101631410 +0900
837++++ ../../git/progit2/progit2/book/01-introduction/sections/about-version-control.asc 2020-07-04 16:36:46.718685392 +0900
838+@@ -1,57 +1,60 @@
849839 === About Version Control
850840
851--(((version control)))
852--What is ``version control'', and why should you care?
853-+What is "version control", and why should you care?
841+-What is "version control", and why should you care?
842++(((version control)))
843++What is ``version control'', and why should you care?
854844 Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later.
855--For the examples in this book, you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
856-+For the examples in this book you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
845+-For the examples in this book you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
846++For the examples in this book, you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
857847
858848 If you are a graphic or web designer and want to keep every version of an image or layout (which you would most certainly want to), a Version Control System (VCS) is a very wise thing to use.
859--It allows you to revert selected files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
860-+It allows you to revert files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
849+-It allows you to revert files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
850++It allows you to revert selected files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
861851 Using a VCS also generally means that if you screw things up or lose files, you can easily recover.
862852 In addition, you get all this for very little overhead.
863853
864854 ==== Local Version Control Systems
865855
866--(((version control,local)))
856++(((version control,local)))
867857 Many people's version-control method of choice is to copy files into another directory (perhaps a time-stamped directory, if they're clever).
868858 This approach is very common because it is so simple, but it is also incredibly error prone.
869859 It is easy to forget which directory you're in and accidentally write to the wrong file or copy over files you don't mean to.
870860
871861 To deal with this issue, programmers long ago developed local VCSs that had a simple database that kept all the changes to files under revision control.
872862
873--.Local version control
874-+.Local version control.
863+-.Local version control.
864++.Local version control
875865 image::images/local.png[Local version control diagram]
876866
877--One of the most popular VCS tools was a system called RCS, which is still distributed with many computers today.
878--https://www.gnu.org/software/rcs/[RCS] works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
879-+One of the more popular VCS tools was a system called RCS, which is still distributed with many computers today.
880-+Even the popular Mac OS X operating system includes the `rcs` command when you install the Developer Tools.
881-+RCS works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
867+-One of the more popular VCS tools was a system called RCS, which is still distributed with many computers today.
868+-Even the popular Mac OS X operating system includes the `rcs` command when you install the Developer Tools.
869+-RCS works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
870++One of the most popular VCS tools was a system called RCS, which is still distributed with many computers today.
871++https://www.gnu.org/software/rcs/[RCS] works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
882872
883873 ==== Centralized Version Control Systems
884874
885--(((version control,centralized)))
875++(((version control,centralized)))
886876 The next major issue that people encounter is that they need to collaborate with developers on other systems.
887877 To deal with this problem, Centralized Version Control Systems (CVCSs) were developed.
888--These systems (such as CVS, Subversion, and Perforce) have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
889-+These systems, such as CVS, Subversion, and Perforce, have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
878+-These systems, such as CVS, Subversion, and Perforce, have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
879++These systems (such as CVS, Subversion, and Perforce) have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
890880 For many years, this has been the standard for version control.
891881
892--.Centralized version control
893-+.Centralized version control.
882+-.Centralized version control.
883++.Centralized version control
894884 image::images/centralized.png[Centralized version control diagram]
895885
896886 This setup offers many advantages, especially over local VCSs.
897887 For example, everyone knows to a certain degree what everyone else on the project is doing.
898--Administrators have fine-grained control over who can do what, and it's far easier to administer a CVCS than it is to deal with local databases on every client.
899-+Administrators have fine-grained control over who can do what; and it's far easier to administer a CVCS than it is to deal with local databases on every client.
888+-Administrators have fine-grained control over who can do what; and it's far easier to administer a CVCS than it is to deal with local databases on every client.
889++Administrators have fine-grained control over who can do what, and it's far easier to administer a CVCS than it is to deal with local databases on every client.
900890
901891 However, this setup also has some serious downsides.
902892 The most obvious is the single point of failure that the centralized server represents.
903893 If that server goes down for an hour, then during that hour nobody can collaborate at all or save versioned changes to anything they're working on.
904--If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything -- the entire history of the project except whatever single snapshots people happen to have on their local machines.
905--Local VCS systems suffer from this same problem -- whenever you have the entire history of the project in a single place, you risk losing everything.
906-+If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything – the entire history of the project except whatever single snapshots people happen to have on their local machines.
907-+Local VCS systems suffer from this same problem – whenever you have the entire history of the project in a single place, you risk losing everything.
894+-If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything – the entire history of the project except whatever single snapshots people happen to have on their local machines.
895+-Local VCS systems suffer from this same problem – whenever you have the entire history of the project in a single place, you risk losing everything.
896++If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything -- the entire history of the project except whatever single snapshots people happen to have on their local machines.
897++Local VCS systems suffer from this same problem -- whenever you have the entire history of the project in a single place, you risk losing everything.
908898
909899 ==== Distributed Version Control Systems
910900
911--(((version control,distributed)))
901++(((version control,distributed)))
912902 This is where Distributed Version Control Systems (DVCSs) step in.
913--In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files; rather, they fully mirror the repository, including its full history.
914--Thus, if any server dies, and these systems were collaborating via that server, any of the client repositories can be copied back up to the server to restore it.
915-+In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files: they fully mirror the repository.
916-+Thus if any server dies, and these systems were collaborating via it, any of the client repositories can be copied back up to the server to restore it.
903+-In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files: they fully mirror the repository.
904+-Thus if any server dies, and these systems were collaborating via it, any of the client repositories can be copied back up to the server to restore it.
905++In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files; rather, they fully mirror the repository, including its full history.
906++Thus, if any server dies, and these systems were collaborating via that server, any of the client repositories can be copied back up to the server to restore it.
917907 Every clone is really a full backup of all the data.
918908
919--.Distributed version control
920-+.Distributed version control.
909+-.Distributed version control.
910++.Distributed version control
921911 image::images/distributed.png[Distributed version control diagram]
922912
923913 Furthermore, many of these systems deal pretty well with having several remote repositories they can work with, so you can collaborate with different groups of people in different ways simultaneously within the same project.
924-diff -au ../../git/progit2/progit2/book/01-introduction/sections/command-line.asc /tmp/book/01-introduction/sections/command-line.asc.tmp
925---- ../../git/progit2/progit2/book/01-introduction/sections/command-line.asc 2020-06-28 16:44:50.920014615 +0900
926-+++ /tmp/book/01-introduction/sections/command-line.asc.tmp 2020-10-25 09:24:25.591963652 +0900
914+diff -au /tmp/book/01-introduction/sections/command-line.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/command-line.asc
915+--- /tmp/book/01-introduction/sections/command-line.asc.tmp 2020-10-25 11:05:02.106631691 +0900
916++++ ../../git/progit2/progit2/book/01-introduction/sections/command-line.asc 2020-06-28 16:44:50.920014615 +0900
927917 @@ -1,11 +1,11 @@
928918 === The Command Line
929919
930920 There are a lot of different ways to use Git.
931--There are the original command-line tools, and there are many graphical user interfaces of varying capabilities.
932-+There are the original command line tools, and there are many graphical user interfaces of varying capabilities.
921+-There are the original command line tools, and there are many graphical user interfaces of varying capabilities.
922++There are the original command-line tools, and there are many graphical user interfaces of varying capabilities.
933923 For this book, we will be using Git on the command line.
934--For one, the command line is the only place you can run _all_ Git commands -- most of the GUIs implement only a partial subset of Git functionality for simplicity.
935--If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
936-+For one, the command line is the only place you can run *all* Git commands – most of the GUIs only implement some subset of Git functionality for simplicity.
937-+If you know how to run the command line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
924+-For one, the command line is the only place you can run *all* Git commands – most of the GUIs only implement some subset of Git functionality for simplicity.
925+-If you know how to run the command line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
926++For one, the command line is the only place you can run _all_ Git commands -- most of the GUIs implement only a partial subset of Git functionality for simplicity.
927++If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
938928 Also, while your choice of graphical client is a matter of personal taste, _all_ users will have the command-line tools installed and available.
939929
940--So we will expect you to know how to open Terminal in macOS or Command Prompt or PowerShell in Windows.
941-+So we will expect you to know how to open Terminal in Mac or Command Prompt or Powershell in Windows.
930+-So we will expect you to know how to open Terminal in Mac or Command Prompt or Powershell in Windows.
931++So we will expect you to know how to open Terminal in macOS or Command Prompt or PowerShell in Windows.
942932 If you don't know what we're talking about here, you may need to stop and research that quickly so that you can follow the rest of the examples and descriptions in this book.
943-diff -au ../../git/progit2/progit2/book/01-introduction/sections/first-time-setup.asc /tmp/book/01-introduction/sections/first-time-setup.asc.tmp
944---- ../../git/progit2/progit2/book/01-introduction/sections/first-time-setup.asc 2020-08-10 10:02:15.168231103 +0900
945-+++ /tmp/book/01-introduction/sections/first-time-setup.asc.tmp 2020-10-25 09:24:25.597963934 +0900
933+diff -au /tmp/book/01-introduction/sections/first-time-setup.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/first-time-setup.asc
934+--- /tmp/book/01-introduction/sections/first-time-setup.asc.tmp 2020-10-25 11:05:02.111631973 +0900
935++++ ../../git/progit2/progit2/book/01-introduction/sections/first-time-setup.asc 2020-08-10 10:02:15.168231103 +0900
946936 @@ -1,4 +1,4 @@
947--[[_first_time]]
948-+[[r_first_time]]
937+-[[r_first_time]]
938++[[_first_time]]
949939 === First-Time Git Setup
950940
951941 Now that you have Git on your system, you'll want to do a few things to customize your Git environment.
952-@@ -8,129 +8,58 @@
942+@@ -8,58 +8,129 @@
953943 Git comes with a tool called `git config` that lets you get and set configuration variables that control all aspects of how Git looks and operates.(((git commands, config)))
954944 These variables can be stored in three different places:
955945
956--1. `[path]/etc/gitconfig` file: Contains values applied to every user on the system and all their repositories.
957-+1. `/etc/gitconfig` file: Contains values for every user on the system and all their repositories.
946+-1. `/etc/gitconfig` file: Contains values for every user on the system and all their repositories.
947++1. `[path]/etc/gitconfig` file: Contains values applied to every user on the system and all their repositories.
958948 If you pass the option `--system` to `git config`, it reads and writes from this file specifically.
959-- Because this is a system configuration file, you would need administrative or superuser privilege to make changes to it.
960--2. `~/.gitconfig` or `~/.config/git/config` file: Values specific personally to you, the user.
961-- You can make Git read and write to this file specifically by passing the `--global` option, and this affects _all_ of the repositories you work with on your system.
962-+2. `~/.gitconfig` or `~/.config/git/config` file: Specific to your user.
963-+ You can make Git read and write to this file specifically by passing the `--global` option.
949+-2. `~/.gitconfig` or `~/.config/git/config` file: Specific to your user.
950+- You can make Git read and write to this file specifically by passing the `--global` option.
951++ Because this is a system configuration file, you would need administrative or superuser privilege to make changes to it.
952++2. `~/.gitconfig` or `~/.config/git/config` file: Values specific personally to you, the user.
953++ You can make Git read and write to this file specifically by passing the `--global` option, and this affects _all_ of the repositories you work with on your system.
964954 3. `config` file in the Git directory (that is, `.git/config`) of whatever repository you're currently using: Specific to that single repository.
965-- You can force Git to read from and write to this file with the `--local` option, but that is in fact the default.
966-- Unsurprisingly, you need to be located somewhere in a Git repository for this option to work properly.
955++ You can force Git to read from and write to this file with the `--local` option, but that is in fact the default.
956++ Unsurprisingly, you need to be located somewhere in a Git repository for this option to work properly.
967957
968--Each level overrides values in the previous level, so values in `.git/config` trump those in `[path]/etc/gitconfig`.
969-+Each level overrides values in the previous level, so values in `.git/config` trump those in `/etc/gitconfig`.
958+-Each level overrides values in the previous level, so values in `.git/config` trump those in `/etc/gitconfig`.
959++Each level overrides values in the previous level, so values in `.git/config` trump those in `[path]/etc/gitconfig`.
970960
971961 On Windows systems, Git looks for the `.gitconfig` file in the `$HOME` directory (`C:\Users\$USER` for most people).
972--It also still looks for `[path]/etc/gitconfig`, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.
973--If you are using version 2.x or later of Git for Windows, there is also a system-level config file at
974-+It also still looks for `/etc/gitconfig`, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.
975-+If you are using Git for Windows 2.x or later, there is also a system-level config file at
962+-It also still looks for `/etc/gitconfig`, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.
963+-If you are using Git for Windows 2.x or later, there is also a system-level config file at
964++It also still looks for `[path]/etc/gitconfig`, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer.
965++If you are using version 2.x or later of Git for Windows, there is also a system-level config file at
976966 `C:\Documents and Settings\All Users\Application Data\Git\config` on Windows XP, and in `C:\ProgramData\Git\config` on Windows Vista and newer.
977967 This config file can only be changed by `git config -f <file>` as an admin.
978968
979--You can view all of your settings and where they are coming from using:
980--
981--[source,console]
982------
983--$ git config --list --show-origin
984------
985--
969++You can view all of your settings and where they are coming from using:
970++
971++[source,console]
972++----
973++$ git config --list --show-origin
974++----
975++
986976 ==== Your Identity
987977
988978 The first thing you should do when you install Git is to set your user name and email address.
989979 This is important because every Git commit uses this information, and it's immutably baked into the commits you start creating:
990980
991--[source,console]
992------
993--$ git config --global user.name "John Doe"
994--$ git config --global user.email johndoe@example.com
995------
996--
981++[source,console]
982++----
983++$ git config --global user.name "John Doe"
984++$ git config --global user.email johndoe@example.com
985++----
986++
997987 Again, you need to do this only once if you pass the `--global` option, because then Git will always use that information for anything you do on that system.
998-+<<<<<<< HEAD
988+-<<<<<<< HEAD
999989 If you want to override this with a different name or email address for specific projects, you can run the command without the `--global` option when you're in that project.
1000990
1001991 Many of the GUI tools will help you do this when you first run them.
1002992
1003--[[_editor]]
993++[[_editor]]
1004994 ==== Your Editor
1005995
1006996 Now that your identity is set up, you can configure the default text editor that will be used when Git needs you to type in a message.
1007997 If not configured, Git uses your system's default editor.
1008--
1009- If you want to use a different text editor, such as Emacs, you can do the following:
998+-If you want to use a different text editor, such as Emacs, you can do the following:
1010999
1011--[source,console]
1012------
1013--$ git config --global core.editor emacs
1014------
1000+-While on a Windows system, if you want to use a different text editor, such as Notepad++, you can do the following:
10151001 -
1016--On a Windows system, if you want to use a different text editor, you must specify the full path to its executable file.
1017--This can be different depending on how your editor is packaged.
1018--
1019--In the case of Notepad++, a popular programming editor, you are likely to want to use the 32-bit version, since at the time of writing the 64-bit version doesn't support all plug-ins.
1020--If you are on a 32-bit Windows system, or you have a 64-bit editor on a 64-bit system, you'll type something like this:
1021--
1022--[source,console]
1023------
1024--$ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"
1025------
1026-+While on a Windows system, if you want to use a different text editor, such as Notepad++, you can do the following:
1002+-On a x86 system
1003++If you want to use a different text editor, such as Emacs, you can do the following:
1004+
1005+-On a x64 system
1006++[source,console]
1007++----
1008++$ git config --global core.editor emacs
1009++----
1010++
1011++On a Windows system, if you want to use a different text editor, you must specify the full path to its executable file.
1012++This can be different depending on how your editor is packaged.
10271013 +
1028-+On a x86 system
1014++In the case of Notepad++, a popular programming editor, you are likely to want to use the 32-bit version, since at the time of writing the 64-bit version doesn't support all plug-ins.
1015++If you are on a 32-bit Windows system, or you have a 64-bit editor on a 64-bit system, you'll type something like this:
10291016 +
1030-+On a x64 system
1017++[source,console]
1018++----
1019++$ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"
1020++----
10311021
1032--[NOTE]
1022++[NOTE]
10331023 ====
1034--Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix-based systems like Linux and macOS or a Windows system.
1035--If you are using another editor, or a 32-bit version, please find specific instructions for how to set up your favorite editor with Git in <<C-git-commands#_core_editor>>.
1036-+Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix based systems like Linux and OS X or a Windows system.
1037-+If you are not familiar with either of these editors, you may need to search for specific instructions for how to set up your favorite editor with Git.
1024+-Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix based systems like Linux and OS X or a Windows system.
1025+-If you are not familiar with either of these editors, you may need to search for specific instructions for how to set up your favorite editor with Git.
1026++Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix-based systems like Linux and macOS or a Windows system.
1027++If you are using another editor, or a 32-bit version, please find specific instructions for how to set up your favorite editor with Git in <<C-git-commands#_core_editor>>.
10381028 ====
10391029
1040--[WARNING]
1030++[WARNING]
10411031 ====
1042--You may find, if you don't setup your editor like this, you get into a really confusing state when Git attempts to launch it.
1043--An example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
1044-+You may find, if you don't setup an editor like this, you will likely get into a really confusing state when they are launched.
1045-+Such example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
1032+-You may find, if you don't setup an editor like this, you will likely get into a really confusing state when they are launched.
1033+-Such example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
1034++You may find, if you don't setup your editor like this, you get into a really confusing state when Git attempts to launch it.
1035++An example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
10461036 ====
10471037
1048--==== Your default branch name
1049--
1050--By default Git will create a branch called _master_ when you create a new repository with `git init`.
1051--From Git version 2.28 onwards, you can set a different name for the initial branch.
1052--
1053--To set _main_ as the default branch name do:
1054--
1055--[source,console]
1056------
1057--$ git config --global init.defaultBranch main
1058------
1059--
1038++==== Your default branch name
1039++
1040++By default Git will create a branch called _master_ when you create a new repository with `git init`.
1041++From Git version 2.28 onwards, you can set a different name for the initial branch.
1042++
1043++To set _main_ as the default branch name do:
1044++
1045++[source,console]
1046++----
1047++$ git config --global init.defaultBranch main
1048++----
1049++
10601050 ==== Checking Your Settings
10611051
1062--If you want to check your configuration settings, you can use the `git config --list` command to list all the settings Git can find at that point:
1063-+If you want to check your settings, you can use the `git config --list` command to list all the settings Git can find at that point:
1052+-If you want to check your settings, you can use the `git config --list` command to list all the settings Git can find at that point:
1053++If you want to check your configuration settings, you can use the `git config --list` command to list all the settings Git can find at that point:
10641054
1065--[source,console]
1066------
1067--$ git config --list
1068--user.name=John Doe
1069--user.email=johndoe@example.com
1070--color.status=auto
1071--color.branch=auto
1072--color.interactive=auto
1073--color.diff=auto
1074--...
1075------
1076--
1077--You may see keys more than once, because Git reads the same key from different files (`[path]/etc/gitconfig` and `~/.gitconfig`, for example).
1078-+You may see keys more than once, because Git reads the same key from different files (`/etc/gitconfig` and `~/.gitconfig`, for example).
1055+-You may see keys more than once, because Git reads the same key from different files (`/etc/gitconfig` and `~/.gitconfig`, for example).
1056++[source,console]
1057++----
1058++$ git config --list
1059++user.name=John Doe
1060++user.email=johndoe@example.com
1061++color.status=auto
1062++color.branch=auto
1063++color.interactive=auto
1064++color.diff=auto
1065++...
1066++----
1067++
1068++You may see keys more than once, because Git reads the same key from different files (`[path]/etc/gitconfig` and `~/.gitconfig`, for example).
10791069 In this case, Git uses the last value for each unique key it sees.
10801070
10811071 You can also check what Git thinks a specific key's value is by typing `git config <key>`:(((git commands, config)))
1082--
1083--[source,console]
1084------
1085--$ git config user.name
1086--John Doe
1087------
1088--
1089--[NOTE]
1090--====
1091--Since Git might read the same configuration variable value from more than one file, it's possible that you have an unexpected value for one of these values and you don't know why.
1092--In cases like that, you can query Git as to the _origin_ for that value, and it will tell you which configuration file had the final say in setting that value:
1093--
1094--[source,console]
1095------
1096--$ git config --show-origin rerere.autoUpdate
1097--file:/home/johndoe/.gitconfig false
1098------
1099--====
1100-diff -au ../../git/progit2/progit2/book/01-introduction/sections/help.asc /tmp/book/01-introduction/sections/help.asc.tmp
1101---- ../../git/progit2/progit2/book/01-introduction/sections/help.asc 2020-07-04 16:36:46.718685392 +0900
1102-+++ /tmp/book/01-introduction/sections/help.asc.tmp 2020-10-25 09:24:25.601964123 +0900
1103-@@ -1,48 +1,10 @@
1104--[[_git_help]]
1105-+[[r_git_help]]
1072++
1073++[source,console]
1074++----
1075++$ git config user.name
1076++John Doe
1077++----
1078++
1079++[NOTE]
1080++====
1081++Since Git might read the same configuration variable value from more than one file, it's possible that you have an unexpected value for one of these values and you don't know why.
1082++In cases like that, you can query Git as to the _origin_ for that value, and it will tell you which configuration file had the final say in setting that value:
1083++
1084++[source,console]
1085++----
1086++$ git config --show-origin rerere.autoUpdate
1087++file:/home/johndoe/.gitconfig false
1088++----
1089++====
1090+diff -au /tmp/book/01-introduction/sections/help.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/help.asc
1091+--- /tmp/book/01-introduction/sections/help.asc.tmp 2020-10-25 11:05:02.116632254 +0900
1092++++ ../../git/progit2/progit2/book/01-introduction/sections/help.asc 2020-07-04 16:36:46.718685392 +0900
1093+@@ -1,10 +1,48 @@
1094+-[[r_git_help]]
1095++[[_git_help]]
11061096 === Getting Help
11071097
1108--If you ever need help while using Git, there are three equivalent ways to get the comprehensive manual page (manpage) help for any of the Git commands:
1109-+If you ever need help while using Git, there are three ways to get the manual page (manpage) help for any of the Git commands:
1098+-If you ever need help while using Git, there are three ways to get the manual page (manpage) help for any of the Git commands:
1099++If you ever need help while using Git, there are three equivalent ways to get the comprehensive manual page (manpage) help for any of the Git commands:
11101100
1111--[source,console]
1112------
1113--$ git help <verb>
1114--$ git <verb> --help
1115--$ man git-<verb>
1116------
1117--
1118--For example, you can get the manpage help for the `git config` command by running this:(((git commands, help)))
1119--
1120--[source,console]
1121------
1122--$ git help config
1123------
1124-+For example, you can get the manpage help for the config command by running(((git commands, help)))
1101+-For example, you can get the manpage help for the config command by running(((git commands, help)))
1102++[source,console]
1103++----
1104++$ git help <verb>
1105++$ git <verb> --help
1106++$ man git-<verb>
1107++----
1108++
1109++For example, you can get the manpage help for the `git config` command by running this:(((git commands, help)))
1110++
1111++[source,console]
1112++----
1113++$ git help config
1114++----
11251115
11261116 These commands are nice because you can access them anywhere, even offline.
1127--If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server, which can be found at https://freenode.net[].
1128-+If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server (irc.freenode.net).
1117+-If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server (irc.freenode.net).
1118++If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server, which can be found at https://freenode.net[].
11291119 These channels are regularly filled with hundreds of people who are all very knowledgeable about Git and are often willing to help.(((IRC)))
1130--
1131--In addition, if you don't need the full-blown manpage help, but just need a quick refresher on the available options for a Git command, you can ask for the more concise ``help'' output with the `-h` option, as in:
1132--
1133--[source,console]
1134------
1135--$ git add -h
1136--usage: git add [<options>] [--] <pathspec>...
1137--
1138-- -n, --dry-run dry run
1139-- -v, --verbose be verbose
1140--
1141-- -i, --interactive interactive picking
1142-- -p, --patch select hunks interactively
1143-- -e, --edit edit current diff and apply
1144-- -f, --force allow adding otherwise ignored files
1145-- -u, --update update tracked files
1146-- --renormalize renormalize EOL of tracked files (implies -u)
1147-- -N, --intent-to-add record only the fact that the path will be added later
1148-- -A, --all add changes from all tracked and untracked files
1149-- --ignore-removal ignore paths removed in the working tree (same as --no-all)
1150-- --refresh don't add, only refresh the index
1151-- --ignore-errors just skip files which cannot be added because of errors
1152-- --ignore-missing check if - even missing - files are ignored in dry run
1153-- --chmod (+|-)x override the executable bit of the listed files
1154------
1155--
1156-diff -au ../../git/progit2/progit2/book/01-introduction/sections/history.asc /tmp/book/01-introduction/sections/history.asc.tmp
1157---- ../../git/progit2/progit2/book/01-introduction/sections/history.asc 2020-06-28 16:44:50.921014763 +0900
1158-+++ /tmp/book/01-introduction/sections/history.asc.tmp 2020-10-25 09:24:25.607964406 +0900
1120++
1121++In addition, if you don't need the full-blown manpage help, but just need a quick refresher on the available options for a Git command, you can ask for the more concise ``help'' output with the `-h` option, as in:
1122++
1123++[source,console]
1124++----
1125++$ git add -h
1126++usage: git add [<options>] [--] <pathspec>...
1127++
1128++ -n, --dry-run dry run
1129++ -v, --verbose be verbose
1130++
1131++ -i, --interactive interactive picking
1132++ -p, --patch select hunks interactively
1133++ -e, --edit edit current diff and apply
1134++ -f, --force allow adding otherwise ignored files
1135++ -u, --update update tracked files
1136++ --renormalize renormalize EOL of tracked files (implies -u)
1137++ -N, --intent-to-add record only the fact that the path will be added later
1138++ -A, --all add changes from all tracked and untracked files
1139++ --ignore-removal ignore paths removed in the working tree (same as --no-all)
1140++ --refresh don't add, only refresh the index
1141++ --ignore-errors just skip files which cannot be added because of errors
1142++ --ignore-missing check if - even missing - files are ignored in dry run
1143++ --chmod (+|-)x override the executable bit of the listed files
1144++----
1145++
1146+diff -au /tmp/book/01-introduction/sections/history.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/history.asc
1147+--- /tmp/book/01-introduction/sections/history.asc.tmp 2020-10-25 11:05:02.120632479 +0900
1148++++ ../../git/progit2/progit2/book/01-introduction/sections/history.asc 2020-06-28 16:44:50.921014763 +0900
11591149 @@ -17,4 +17,4 @@
11601150 * Able to handle large projects like the Linux kernel efficiently (speed and data size)
11611151
11621152 Since its birth in 2005, Git has evolved and matured to be easy to use and yet retain these initial qualities.
1163--It's amazingly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<ch03-git-branching#ch03-git-branching>>).
1164-+It's incredibly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<ch03-git-branching#ch03-git-branching>>).
1165-diff -au ../../git/progit2/progit2/book/01-introduction/sections/installing.asc /tmp/book/01-introduction/sections/installing.asc.tmp
1166---- ../../git/progit2/progit2/book/01-introduction/sections/installing.asc 2020-07-04 16:36:46.718685392 +0900
1167-+++ /tmp/book/01-introduction/sections/installing.asc.tmp 2020-10-25 09:24:25.611964594 +0900
1168-@@ -4,144 +4,69 @@
1153+-It's incredibly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<ch03-git-branching#ch03-git-branching>>).
1154++It's amazingly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<ch03-git-branching#ch03-git-branching>>).
1155+diff -au /tmp/book/01-introduction/sections/installing.asc.tmp ../../git/progit2/progit2/book/01-introduction/sections/installing.asc
1156+--- /tmp/book/01-introduction/sections/installing.asc.tmp 2020-10-25 11:05:02.125632760 +0900
1157++++ ../../git/progit2/progit2/book/01-introduction/sections/installing.asc 2020-07-04 16:36:46.718685392 +0900
1158+@@ -4,69 +4,144 @@
11691159 Even if it's already installed, it's probably a good idea to update to the latest version.
11701160 You can either install it as a package or via another installer, or download the source code and compile it yourself.
11711161
1172--[NOTE]
1162++[NOTE]
11731163 ====
1174--This book was written using Git version *2.8.0*.
1175-+This book was written using Git version *2.0.0*.
1164+-This book was written using Git version *2.0.0*.
1165++This book was written using Git version *2.8.0*.
11761166 Though most of the commands we use should work even in ancient versions of Git, some of them might not or might act slightly differently if you're using an older version.
1177--Since Git is quite excellent at preserving backwards compatibility, any version after 2.8 should work just fine.
1178-+Since Git is quite excellent at preserving backwards compatibility, any version after 2.0 should work just fine.
1167+-Since Git is quite excellent at preserving backwards compatibility, any version after 2.0 should work just fine.
1168++Since Git is quite excellent at preserving backwards compatibility, any version after 2.8 should work just fine.
11791169 ====
11801170
11811171 ==== Installing on Linux
11821172
1183--(((Linux, installing)))
1184--If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the package management tool that comes with your distribution.
1185--If you're on Fedora (or any closely-related RPM-based distribution, such as RHEL or CentOS), you can use `dnf`:
1186-+If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the basic package-management tool that comes with your distribution.
1187-+If you're on Fedora for example, you can use yum:
1173+-If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the basic package-management tool that comes with your distribution.
1174+-If you're on Fedora for example, you can use yum:
1175++(((Linux, installing)))
1176++If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the package management tool that comes with your distribution.
1177++If you're on Fedora (or any closely-related RPM-based distribution, such as RHEL or CentOS), you can use `dnf`:
11881178
1189--[source,console]
1190------
1191--$ sudo dnf install git-all
1192------
1193-+If you're on a Debian-based distribution like Ubuntu, try apt-get:
1179+-If you're on a Debian-based distribution like Ubuntu, try apt-get:
1180++[source,console]
1181++----
1182++$ sudo dnf install git-all
1183++----
11941184
1195--If you're on a Debian-based distribution, such as Ubuntu, try `apt`:
1196-+For more options, there are instructions for installing on several different Unix flavors on the Git website, at http://git-scm.com/download/linux[].
1185+-For more options, there are instructions for installing on several different Unix flavors on the Git website, at http://git-scm.com/download/linux[].
1186++If you're on a Debian-based distribution, such as Ubuntu, try `apt`:
11971187
1198--[source,console]
1199------
1200--$ sudo apt install git-all
1201------
1202-+==== Installing on Mac
1188+-==== Installing on Mac
1189++[source,console]
1190++----
1191++$ sudo apt install git-all
1192++----
12031193
1204--For more options, there are instructions for installing on several different Unix distributions on the Git website, at https://git-scm.com/download/linux[].
1205--
1206--==== Installing on macOS
1207--
1208--(((macOS, installing)))
1194++For more options, there are instructions for installing on several different Unix distributions on the Git website, at https://git-scm.com/download/linux[].
1195++
1196++==== Installing on macOS
1197++
1198++(((macOS, installing)))
12091199 There are several ways to install Git on a Mac.
12101200 The easiest is probably to install the Xcode Command Line Tools.(((Xcode)))
1211--On Mavericks (10.9) or above you can do this simply by trying to run `git` from the Terminal the very first time.
1212--
1213--[source,console]
1214------
1215--$ git --version
1216------
1217--
1218-+On Mavericks (10.9) or above you can do this simply by trying to run 'git' from the Terminal the very first time.
1201+-On Mavericks (10.9) or above you can do this simply by trying to run 'git' from the Terminal the very first time.
1202++On Mavericks (10.9) or above you can do this simply by trying to run `git` from the Terminal the very first time.
1203++
1204++[source,console]
1205++----
1206++$ git --version
1207++----
1208++
12191209 If you don't have it installed already, it will prompt you to install it.
12201210
12211211 If you want a more up to date version, you can also install it via a binary installer.
1222--A macOS Git installer is maintained and available for download at the Git website, at https://git-scm.com/download/mac[].
1223-+An OSX Git installer is maintained and available for download at the Git website, at http://git-scm.com/download/mac[].
1212+-An OSX Git installer is maintained and available for download at the Git website, at http://git-scm.com/download/mac[].
1213++A macOS Git installer is maintained and available for download at the Git website, at https://git-scm.com/download/mac[].
12241214
1225--.Git macOS Installer
1226--image::images/git-osx-installer.png[Git macOS installer]
1227-+.Git OS X Installer.
1228-+image::images/git-osx-installer.png[Git OS X installer.]
1215+-.Git OS X Installer.
1216+-image::images/git-osx-installer.png[Git OS X installer.]
1217++.Git macOS Installer
1218++image::images/git-osx-installer.png[Git macOS installer]
12291219
1230--You can also install it as part of the GitHub for macOS install.
1231-+You can also install it as part of the GitHub for Mac install.
1220+-You can also install it as part of the GitHub for Mac install.
1221++You can also install it as part of the GitHub for macOS install.
12321222 Their GUI Git tool has an option to install command line tools as well.
1233--You can download that tool from the GitHub for macOS website, at https://desktop.github.com[].
1234-+You can download that tool from the GitHub for Mac website, at http://mac.github.com[].
1223+-You can download that tool from the GitHub for Mac website, at http://mac.github.com[].
1224++You can download that tool from the GitHub for macOS website, at https://desktop.github.com[].
12351225
12361226 ==== Installing on Windows
12371227
12381228 There are also a few ways to install Git on Windows.(((Windows, installing)))
12391229 The most official build is available for download on the Git website.
1240--Just go to https://git-scm.com/download/win[] and the download will start automatically.
1241--Note that this is a project called Git for Windows, which is separate from Git itself; for more information on it, go to https://gitforwindows.org[].
1242--
1243--To get an automated installation you can use the https://chocolatey.org/packages/git[Git Chocolatey package].
1244--Note that the Chocolatey package is community maintained.
1245-+Just go to http://git-scm.com/download/win[] and the download will start automatically.
1246-+Note that this is a project called Git for Windows, which is separate from Git itself; for more information on it, go to https://git-for-windows.github.io/[].
1230+-Just go to http://git-scm.com/download/win[] and the download will start automatically.
1231+-Note that this is a project called Git for Windows, which is separate from Git itself; for more information on it, go to https://git-for-windows.github.io/[].
1232++Just go to https://git-scm.com/download/win[] and the download will start automatically.
1233++Note that this is a project called Git for Windows, which is separate from Git itself; for more information on it, go to https://gitforwindows.org[].
1234++
1235++To get an automated installation you can use the https://chocolatey.org/packages/git[Git Chocolatey package].
1236++Note that the Chocolatey package is community maintained.
12471237
1248--Another easy way to get Git installed is by installing GitHub Desktop.
1249-+Another easy way to get Git installed is by installing GitHub for Windows.
1238+-Another easy way to get Git installed is by installing GitHub for Windows.
1239++Another easy way to get Git installed is by installing GitHub Desktop.
12501240 The installer includes a command line version of Git as well as the GUI.
1251--It also works well with PowerShell, and sets up solid credential caching and sane CRLF settings.(((PowerShell)))(((CRLF)))(((credential caching)))
1252-+It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.(((Powershell)))(((CRLF)))(((credential caching)))
1241+-It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.(((Powershell)))(((CRLF)))(((credential caching)))
1242++It also works well with PowerShell, and sets up solid credential caching and sane CRLF settings.(((PowerShell)))(((CRLF)))(((credential caching)))
12531243 We'll learn more about those things a little later, but suffice it to say they're things you want.
1254--You can download this from the https://desktop.github.com[GitHub Desktop website].
1255-+You can download this from the GitHub for Windows website, at http://windows.github.com[].
1244+-You can download this from the GitHub for Windows website, at http://windows.github.com[].
1245++You can download this from the https://desktop.github.com[GitHub Desktop website].
12561246
12571247 ==== Installing from Source
12581248
12591249 Some people may instead find it useful to install Git from source, because you'll get the most recent version.
12601250 The binary installers tend to be a bit behind, though as Git has matured in recent years, this has made less of a difference.
12611251
1262--If you do want to install Git from source, you need to have the following libraries that Git depends on: autotools, curl, zlib, openssl, expat, and libiconv.
1263--For example, if you're on a system that has `dnf` (such as Fedora) or `apt-get` (such as a Debian-based system), you can use one of these commands to install the minimal dependencies for compiling and installing the Git binaries:
1264-+If you do want to install Git from source, you need to have the following libraries that Git depends on: curl, zlib, openssl, expat, and libiconv.
1265-+For example, if you're on a system that has yum (such as Fedora) or apt-get (such as a Debian based system), you can use one of these commands to install the minimal dependencies for compiling and installing the Git binaries:
1252+-If you do want to install Git from source, you need to have the following libraries that Git depends on: curl, zlib, openssl, expat, and libiconv.
1253+-For example, if you're on a system that has yum (such as Fedora) or apt-get (such as a Debian based system), you can use one of these commands to install the minimal dependencies for compiling and installing the Git binaries:
1254++If you do want to install Git from source, you need to have the following libraries that Git depends on: autotools, curl, zlib, openssl, expat, and libiconv.
1255++For example, if you're on a system that has `dnf` (such as Fedora) or `apt-get` (such as a Debian-based system), you can use one of these commands to install the minimal dependencies for compiling and installing the Git binaries:
12661256
1267--[source,console]
1268------
1269--$ sudo dnf install dh-autoreconf curl-devel expat-devel gettext-devel \
1270-- openssl-devel perl-devel zlib-devel
1271--$ sudo apt-get install dh-autoreconf libcurl4-gnutls-dev libexpat1-dev \
1272-- gettext libz-dev libssl-dev
1273------
1274--
1275--In order to be able to add the documentation in various formats (doc, html, info), these additional dependencies are required:
1276--
1277--[source,console]
1278------
1279--$ sudo dnf install asciidoc xmlto docbook2X
1280--$ sudo apt-get install asciidoc xmlto docbook2x
1281------
1282-+In order to be able to add the documentation in various formats (doc, html, info), these additional dependencies are required (Note: users of RHEL and RHEL-derivatives like CentOS and Scientific Linux will have to https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[enable the EPEL repository] to download the `docbook2X` package):
1257+-In order to be able to add the documentation in various formats (doc, html, info), these additional dependencies are required (Note: users of RHEL and RHEL-derivatives like CentOS and Scientific Linux will have to https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[enable the EPEL repository] to download the `docbook2X` package):
1258++[source,console]
1259++----
1260++$ sudo dnf install dh-autoreconf curl-devel expat-devel gettext-devel \
1261++ openssl-devel perl-devel zlib-devel
1262++$ sudo apt-get install dh-autoreconf libcurl4-gnutls-dev libexpat1-dev \
1263++ gettext libz-dev libssl-dev
1264++----
1265++
1266++In order to be able to add the documentation in various formats (doc, html, info), these additional dependencies are required:
1267++
1268++[source,console]
1269++----
1270++$ sudo dnf install asciidoc xmlto docbook2X
1271++$ sudo apt-get install asciidoc xmlto docbook2x
1272++----
12831273
1284--[NOTE]
1285--====
1286--Users of RHEL and RHEL-derivatives like CentOS and Scientific Linux will have to https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[enable the EPEL repository] to download the `docbook2X` package.
1287--====
1288--
1289--If you're using a Debian-based distribution (Debian/Ubuntu/Ubuntu-derivatives), you also need the `install-info` package:
1290--
1291--[source,console]
1292------
1293--$ sudo apt-get install install-info
1294------
1295--
1296--If you're using a RPM-based distribution (Fedora/RHEL/RHEL-derivatives), you also need the `getopt` package (which is already installed on a Debian-based distro):
1297--
1298--[source,console]
1299------
1300--$ sudo dnf install getopt
1301------
1302--
1303--Additionally, if you're using Fedora/RHEL/RHEL-derivatives, you need to do this:
1304--
1305--[source,console]
1306------
1307--$ sudo ln -s /usr/bin/db2x_docbook2texi /usr/bin/docbook2x-texi
1308------
1309-+Additionally, if you're using Fedora/RHEL/RHEL-derivatives, you need to do this
1274+-Additionally, if you're using Fedora/RHEL/RHEL-derivatives, you need to do this
1275++[NOTE]
1276++====
1277++Users of RHEL and RHEL-derivatives like CentOS and Scientific Linux will have to https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[enable the EPEL repository] to download the `docbook2X` package.
1278++====
1279++
1280++If you're using a Debian-based distribution (Debian/Ubuntu/Ubuntu-derivatives), you also need the `install-info` package:
1281++
1282++[source,console]
1283++----
1284++$ sudo apt-get install install-info
1285++----
1286++
1287++If you're using a RPM-based distribution (Fedora/RHEL/RHEL-derivatives), you also need the `getopt` package (which is already installed on a Debian-based distro):
1288++
1289++[source,console]
1290++----
1291++$ sudo dnf install getopt
1292++----
1293++
1294++Additionally, if you're using Fedora/RHEL/RHEL-derivatives, you need to do this:
1295++
1296++[source,console]
1297++----
1298++$ sudo ln -s /usr/bin/db2x_docbook2texi /usr/bin/docbook2x-texi
1299++----
13101300
13111301 due to binary name differences.
13121302
13131303 When you have all the necessary dependencies, you can go ahead and grab the latest tagged release tarball from several places.
1314--You can get it via the kernel.org site, at https://www.kernel.org/pub/software/scm/git[], or the mirror on the GitHub website, at https://github.com/git/git/releases[].
1315-+You can get it via the Kernel.org site, at https://www.kernel.org/pub/software/scm/git[], or the mirror on the GitHub web site, at https://github.com/git/git/releases[].
1304+-You can get it via the Kernel.org site, at https://www.kernel.org/pub/software/scm/git[], or the mirror on the GitHub web site, at https://github.com/git/git/releases[].
1305++You can get it via the kernel.org site, at https://www.kernel.org/pub/software/scm/git[], or the mirror on the GitHub website, at https://github.com/git/git/releases[].
13161306 It's generally a little clearer what the latest version is on the GitHub page, but the kernel.org page also has release signatures if you want to verify your download.
13171307
13181308 Then, compile and install:
13191309
1320--[source,console]
1321------
1322--$ tar -zxf git-2.8.0.tar.gz
1323--$ cd git-2.8.0
1324--$ make configure
1325--$ ./configure --prefix=/usr
1326--$ make all doc info
1327--$ sudo make install install-doc install-html install-info
1328------
1329--
1310++[source,console]
1311++----
1312++$ tar -zxf git-2.8.0.tar.gz
1313++$ cd git-2.8.0
1314++$ make configure
1315++$ ./configure --prefix=/usr
1316++$ make all doc info
1317++$ sudo make install install-doc install-html install-info
1318++----
1319++
13301320 After this is done, you can also get Git via Git itself for updates:
1331--
1332--[source,console]
1333------
1334--$ git clone git://git.kernel.org/pub/scm/git/git.git
1335------
1321++
1322++[source,console]
1323++----
1324++$ git clone git://git.kernel.org/pub/scm/git/git.git
1325++----
13361326 Warning: file not found: ../../git/progit2/progit2-ja/book/01-introduction/sections/what-is-git.asc
1337-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/aliases.asc /tmp/book/02-git-basics/sections/aliases.asc.tmp
1338---- ../../git/progit2/progit2/book/02-git-basics/sections/aliases.asc 2020-07-03 19:43:27.508489967 +0900
1339-+++ /tmp/book/02-git-basics/sections/aliases.asc.tmp 2020-10-25 09:24:25.617964877 +0900
1340-@@ -1,70 +1,28 @@
1341--[[_git_aliases]]
1342-+[[r_git_aliases]]
1327+diff -au /tmp/book/02-git-basics/sections/aliases.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/aliases.asc
1328+--- /tmp/book/02-git-basics/sections/aliases.asc.tmp 2020-10-25 11:05:02.148634054 +0900
1329++++ ../../git/progit2/progit2/book/02-git-basics/sections/aliases.asc 2020-07-03 19:43:27.508489967 +0900
1330+@@ -1,28 +1,70 @@
1331+-[[r_git_aliases]]
1332++[[_git_aliases]]
13431333 === Git Aliases
13441334
1345--(((aliases)))
1346--Before we move on to the next chapter, we want to introduce a feature that can make your Git experience simpler, easier, and more familiar: aliases.
1347--For clarity's sake, we won't be using them anywhere else in this book, but if you go on to use Git with any regularity, aliases are something you should know about.
1348-+Before we finish this chapter on basic Git, there's just one little tip that can make your Git experience simpler, easier, and more familiar: aliases.
1349-+We won't refer to them or assume you've used them later in the book, but you should probably know how to use them.
1335+-Before we finish this chapter on basic Git, there's just one little tip that can make your Git experience simpler, easier, and more familiar: aliases.
1336+-We won't refer to them or assume you've used them later in the book, but you should probably know how to use them.
1337++(((aliases)))
1338++Before we move on to the next chapter, we want to introduce a feature that can make your Git experience simpler, easier, and more familiar: aliases.
1339++For clarity's sake, we won't be using them anywhere else in this book, but if you go on to use Git with any regularity, aliases are something you should know about.
13501340
13511341 Git doesn't automatically infer your command if you type it in partially.
13521342 If you don't want to type the entire text of each of the Git commands, you can easily set up an alias for each command using `git config`.(((git commands, config)))
13531343 Here are a couple of examples you may want to set up:
13541344
1355--[source,console]
1356------
1357--$ git config --global alias.co checkout
1358--$ git config --global alias.br branch
1359--$ git config --global alias.ci commit
1360--$ git config --global alias.st status
1361------
1362--
1345++[source,console]
1346++----
1347++$ git config --global alias.co checkout
1348++$ git config --global alias.br branch
1349++$ git config --global alias.ci commit
1350++$ git config --global alias.st status
1351++----
1352++
13631353 This means that, for example, instead of typing `git commit`, you just need to type `git ci`.
13641354 As you go on using Git, you'll probably use other commands frequently as well; don't hesitate to create new aliases.
13651355
13661356 This technique can also be very useful in creating commands that you think should exist.
13671357 For example, to correct the usability problem you encountered with unstaging a file, you can add your own unstage alias to Git:
13681358
1369--[source,console]
1370------
1371--$ git config --global alias.unstage 'reset HEAD --'
1372------
1373--
1359++[source,console]
1360++----
1361++$ git config --global alias.unstage 'reset HEAD --'
1362++----
1363++
13741364 This makes the following two commands equivalent:
13751365
1376--[source,console]
1377------
1378--$ git unstage fileA
1379--$ git reset HEAD -- fileA
1380------
1381--
1366++[source,console]
1367++----
1368++$ git unstage fileA
1369++$ git reset HEAD -- fileA
1370++----
1371++
13821372 This seems a bit clearer.
13831373 It's also common to add a `last` command, like this:
13841374
1385--[source,console]
1386------
1387--$ git config --global alias.last 'log -1 HEAD'
1388------
1389--
1375++[source,console]
1376++----
1377++$ git config --global alias.last 'log -1 HEAD'
1378++----
1379++
13901380 This way, you can see the last commit easily:
13911381
1392--[source,console]
1393------
1394--$ git last
1395--commit 66938dae3329c7aebe598c2246a8e6af90d04646
1396--Author: Josh Goebel <dreamer3@example.com>
1397--Date: Tue Aug 26 19:48:51 2008 +0800
1398--
1399-- Test for current head
1400--
1401-- Signed-off-by: Scott Chacon <schacon@example.com>
1402------
1403--
1382++[source,console]
1383++----
1384++$ git last
1385++commit 66938dae3329c7aebe598c2246a8e6af90d04646
1386++Author: Josh Goebel <dreamer3@example.com>
1387++Date: Tue Aug 26 19:48:51 2008 +0800
1388++
1389++ Test for current head
1390++
1391++ Signed-off-by: Scott Chacon <schacon@example.com>
1392++----
1393++
14041394 As you can tell, Git simply replaces the new command with whatever you alias it for.
14051395 However, maybe you want to run an external command, rather than a Git subcommand.
14061396 In that case, you start the command with a `!` character.
14071397 This is useful if you write your own tools that work with a Git repository.
14081398 We can demonstrate by aliasing `git visual` to run `gitk`:
1409--
1410--[source,console]
1411------
1412--$ git config --global alias.visual '!gitk'
1413------
1414-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/getting-a-repository.asc /tmp/book/02-git-basics/sections/getting-a-repository.asc.tmp
1415---- ../../git/progit2/progit2/book/02-git-basics/sections/getting-a-repository.asc 2020-07-01 10:48:37.610009640 +0900
1416-+++ /tmp/book/02-git-basics/sections/getting-a-repository.asc.tmp 2020-10-25 09:24:25.621965066 +0900
1417-@@ -1,87 +1,41 @@
1418--[[_getting_a_repo]]
1419-+[[r_getting_a_repo]]
1399++
1400++[source,console]
1401++----
1402++$ git config --global alias.visual '!gitk'
1403++----
1404+diff -au /tmp/book/02-git-basics/sections/getting-a-repository.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/getting-a-repository.asc
1405+--- /tmp/book/02-git-basics/sections/getting-a-repository.asc.tmp 2020-10-25 11:05:02.153634335 +0900
1406++++ ../../git/progit2/progit2/book/02-git-basics/sections/getting-a-repository.asc 2020-07-01 10:48:37.610009640 +0900
1407+@@ -1,41 +1,87 @@
1408+-[[r_getting_a_repo]]
1409++[[_getting_a_repo]]
14201410 === Getting a Git Repository
14211411
1422--You typically obtain a Git repository in one of two ways:
1423--
1424--1. You can take a local directory that is currently not under version control, and turn it into a Git repository, or
1425--2. You can _clone_ an existing Git repository from elsewhere.
1426--
1427--In either case, you end up with a Git repository on your local machine, ready for work.
1428-+You can get a Git project using two main approaches.
1429-+The first takes an existing project or directory and imports it into Git.
1430-+The second clones an existing Git repository from another server.
1412+-You can get a Git project using two main approaches.
1413+-The first takes an existing project or directory and imports it into Git.
1414+-The second clones an existing Git repository from another server.
1415++You typically obtain a Git repository in one of two ways:
1416++
1417++1. You can take a local directory that is currently not under version control, and turn it into a Git repository, or
1418++2. You can _clone_ an existing Git repository from elsewhere.
1419++
1420++In either case, you end up with a Git repository on your local machine, ready for work.
14311421
14321422 ==== Initializing a Repository in an Existing Directory
14331423
1434--If you have a project directory that is currently not under version control and you want to start controlling it with Git, you first need to go to that project's directory.
1435--If you've never done this, it looks a little different depending on which system you're running:
1436-+If you're starting to track an existing project in Git, you need to go to the project's directory and type:
1424+-If you're starting to track an existing project in Git, you need to go to the project's directory and type:
1425++If you have a project directory that is currently not under version control and you want to start controlling it with Git, you first need to go to that project's directory.
1426++If you've never done this, it looks a little different depending on which system you're running:
14371427
1438--for Linux:
1439--[source,console]
1440------
1441--$ cd /home/user/my_project
1442------
1443--for macOS:
1444--[source,console]
1445------
1446--$ cd /Users/user/my_project
1447------
1448--for Windows:
1449--[source,console]
1450------
1451--$ cd C:/Users/user/my_project
1452------
1453--
1454--and type:
1455--
1456--[source,console]
1457------
1458--$ git init
1459------
1460--
1461--This creates a new subdirectory named `.git` that contains all of your necessary repository files -- a Git repository skeleton.
1462-+This creates a new subdirectory named `.git` that contains all of your necessary repository files – a Git repository skeleton.
1428+-This creates a new subdirectory named `.git` that contains all of your necessary repository files – a Git repository skeleton.
1429++for Linux:
1430++[source,console]
1431++----
1432++$ cd /home/user/my_project
1433++----
1434++for macOS:
1435++[source,console]
1436++----
1437++$ cd /Users/user/my_project
1438++----
1439++for Windows:
1440++[source,console]
1441++----
1442++$ cd C:/Users/user/my_project
1443++----
1444++
1445++and type:
1446++
1447++[source,console]
1448++----
1449++$ git init
1450++----
1451++
1452++This creates a new subdirectory named `.git` that contains all of your necessary repository files -- a Git repository skeleton.
14631453 At this point, nothing in your project is tracked yet.
1464--See <<ch10-git-internals#ch10-git-internals>> for more information about exactly what files are contained in the `.git` directory you just created.(((git commands, init)))
1465-+(See <<ch10-git-internals#ch10-git-internals>> for more information about exactly what files are contained in the `.git` directory you just created.)(((git commands, init)))
1454+-(See <<ch10-git-internals#ch10-git-internals>> for more information about exactly what files are contained in the `.git` directory you just created.)(((git commands, init)))
1455++See <<ch10-git-internals#ch10-git-internals>> for more information about exactly what files are contained in the `.git` directory you just created.(((git commands, init)))
14661456
14671457 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.
14681458 You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`:
14691459
1470--[source,console]
1471------
1472--$ git add *.c
1473--$ git add LICENSE
1474--$ git commit -m 'Initial project version'
1475------
1476--
1460++[source,console]
1461++----
1462++$ git add *.c
1463++$ git add LICENSE
1464++$ git commit -m 'Initial project version'
1465++----
1466++
14771467 We'll go over what these commands do in just a minute.
14781468 At this point, you have a Git repository with tracked files and an initial commit.
14791469
1480--[[_git_cloning]]
1470++[[_git_cloning]]
14811471 ==== Cloning an Existing Repository
14821472
1483--If you want to get a copy of an existing Git repository -- for example, a project you'd like to contribute to -- the command you need is `git clone`.
1484-+If you want to get a copy of an existing Git repository – for example, a project you'd like to contribute to – the command you need is `git clone`.
1473+-If you want to get a copy of an existing Git repository – for example, a project you'd like to contribute to – the command you need is `git clone`.
1474++If you want to get a copy of an existing Git repository -- for example, a project you'd like to contribute to -- the command you need is `git clone`.
14851475 If you're familiar with other VCS systems such as Subversion, you'll notice that the command is "clone" and not "checkout".
1486--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.
1487-+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.
1476+-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.
1477++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.
14881478 Every version of every file for the history of the project is pulled down by default when you run `git clone`.
1489--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 <<ch04-git-on-the-server#_getting_git_on_a_server>> for more details).
1490--
1491--You clone a repository with `git clone <url>`.(((git commands, clone)))
1492--For example, if you want to clone the Git linkable library called `libgit2`, you can do so like this:
1493--
1494--[source,console]
1495------
1496--$ git clone https://github.com/libgit2/libgit2
1497------
1498--
1499--That creates a directory named `libgit2`, initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
1500--If you go into the new `libgit2` directory that was just created, you'll see the project files in there, ready to be worked on or used.
1501-+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 <<ch04-git-server#r_git_on_the_server>> for more details).
1479+-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 <<ch04-git-server#r_git_on_the_server>> for more details).
1480++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 <<ch04-git-on-the-server#_getting_git_on_a_server>> for more details).
1481++
1482++You clone a repository with `git clone <url>`.(((git commands, clone)))
1483++For example, if you want to clone the Git linkable library called `libgit2`, you can do so like this:
1484++
1485++[source,console]
1486++----
1487++$ git clone https://github.com/libgit2/libgit2
1488++----
1489++
1490++That creates a directory named `libgit2`, initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
1491++If you go into the new `libgit2` directory that was just created, you'll see the project files in there, ready to be worked on or used.
15021492
1503--If you want to clone the repository into a directory named something other than `libgit2`, you can specify the new directory name as an additional argument:
1504-+You clone a repository with `git clone [url]`.(((git commands, clone)))
1505-+For example, if you want to clone the Git linkable library called libgit2, you can do so like this:
1493+-You clone a repository with `git clone [url]`.(((git commands, clone)))
1494+-For example, if you want to clone the Git linkable library called libgit2, you can do so like this:
1495++If you want to clone the repository into a directory named something other than `libgit2`, you can specify the new directory name as an additional argument:
15061496
1507--[source,console]
1508------
1509--$ git clone https://github.com/libgit2/libgit2 mylibgit
1510------
1511-+That creates a directory named ``libgit2'', initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
1512-+If you go into the new `libgit2` directory, you'll see the project files in there, ready to be worked on or used.
1513-+If you want to clone the repository into a directory named something other than ``libgit2'', you can specify that as the next command-line option:
1497+-That creates a directory named ``libgit2'', initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
1498+-If you go into the new `libgit2` directory, you'll see the project files in there, ready to be worked on or used.
1499+-If you want to clone the repository into a directory named something other than ``libgit2'', you can specify that as the next command-line option:
1500++[source,console]
1501++----
1502++$ git clone https://github.com/libgit2/libgit2 mylibgit
1503++----
15141504
15151505 That command does the same thing as the previous one, but the target directory is called `mylibgit`.
15161506
15171507 Git has a number of different transfer protocols you can use.
15181508 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.
1519--<<ch04-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.
1520-+<<ch04-git-server#r_git_on_the_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.
1521-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/recording-changes.asc /tmp/book/02-git-basics/sections/recording-changes.asc.tmp
1522---- ../../git/progit2/progit2/book/02-git-basics/sections/recording-changes.asc 2020-07-04 16:36:46.720685416 +0900
1523-+++ /tmp/book/02-git-basics/sections/recording-changes.asc.tmp 2020-10-25 09:24:25.627965349 +0900
1524-@@ -1,91 +1,48 @@
1509+-<<ch04-git-server#r_git_on_the_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.
1510++<<ch04-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.
1511+diff -au /tmp/book/02-git-basics/sections/recording-changes.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/recording-changes.asc
1512+--- /tmp/book/02-git-basics/sections/recording-changes.asc.tmp 2020-10-25 11:05:02.160634728 +0900
1513++++ ../../git/progit2/progit2/book/02-git-basics/sections/recording-changes.asc 2020-07-04 16:36:46.720685416 +0900
1514+@@ -1,48 +1,91 @@
15251515 === Recording Changes to the Repository
15261516
1527--At this point, you should have a _bona fide_ Git repository on your local machine, and a checkout or _working copy_ of all of its files in front of you.
1528--Typically, you'll want to start making changes and committing snapshots of those changes into your repository each time the project reaches a state you want to record.
1529-+You have a bona fide Git repository and a checkout or working copy of the files for that project.
1530-+You need to make some changes and commit snapshots of those changes into your repository each time the project reaches a state you want to record.
1517+-You have a bona fide Git repository and a checkout or working copy of the files for that project.
1518+-You need to make some changes and commit snapshots of those changes into your repository each time the project reaches a state you want to record.
1519++At this point, you should have a _bona fide_ Git repository on your local machine, and a checkout or _working copy_ of all of its files in front of you.
1520++Typically, you'll want to start making changes and committing snapshots of those changes into your repository each time the project reaches a state you want to record.
15311521
1532--Remember that each file in your working directory can be in one of two states: _tracked_ or _untracked_.
1533-+Remember that each file in your working directory can be in one of two states: tracked or untracked.
1522+-Remember that each file in your working directory can be in one of two states: tracked or untracked.
1523++Remember that each file in your working directory can be in one of two states: _tracked_ or _untracked_.
15341524 Tracked files are files that were in the last snapshot; they can be unmodified, modified, or staged.
1535--In short, tracked files are files that Git knows about.
1536--
1537--Untracked files are everything else -- any files in your working directory that were not in your last snapshot and are not in your staging area.
1538--When you first clone a repository, all of your files will be tracked and unmodified because Git just checked them out and you haven't edited anything.
1539-+Untracked files are everything else – any files in your working directory that were not in your last snapshot and are not in your staging area.
1540-+When you first clone a repository, all of your files will be tracked and unmodified because you just checked them out and haven't edited anything.
1525+-Untracked files are everything else – any files in your working directory that were not in your last snapshot and are not in your staging area.
1526+-When you first clone a repository, all of your files will be tracked and unmodified because you just checked them out and haven't edited anything.
1527++In short, tracked files are files that Git knows about.
1528++
1529++Untracked files are everything else -- any files in your working directory that were not in your last snapshot and are not in your staging area.
1530++When you first clone a repository, all of your files will be tracked and unmodified because Git just checked them out and you haven't edited anything.
15411531
15421532 As you edit files, Git sees them as modified, because you've changed them since your last commit.
1543--As you work, you selectively stage these modified files and then commit all those staged changes, and the cycle repeats.
1544-+You stage these modified files and then commit all your staged changes, and the cycle repeats.
1533+-You stage these modified files and then commit all your staged changes, and the cycle repeats.
1534++As you work, you selectively stage these modified files and then commit all those staged changes, and the cycle repeats.
15451535
1546--.The lifecycle of the status of your files
1547--image::images/lifecycle.png[The lifecycle of the status of your files]
1548-+.The lifecycle of the status of your files.
1549-+image::images/lifecycle.png[The lifecycle of the status of your files.]
1536+-.The lifecycle of the status of your files.
1537+-image::images/lifecycle.png[The lifecycle of the status of your files.]
1538++.The lifecycle of the status of your files
1539++image::images/lifecycle.png[The lifecycle of the status of your files]
15501540
1551--[[_checking_status]]
1541++[[_checking_status]]
15521542 ==== Checking the Status of Your Files
15531543
15541544 The main tool you use to determine which files are in which state is the `git status` command.(((git commands, status)))
15551545 If you run this command directly after a clone, you should see something like this:
15561546
1557--[source,console]
1558------
1559--$ git status
1560--On branch master
1561--Your branch is up-to-date with 'origin/master'.
1562--nothing to commit, working directory clean
1563------
1564--
1565--This means you have a clean working directory; in other words, none of your tracked files are modified.
1566-+This means you have a clean working directory – in other words, there are no tracked and modified files.
1547+-This means you have a clean working directory – in other words, there are no tracked and modified files.
1548++[source,console]
1549++----
1550++$ git status
1551++On branch master
1552++Your branch is up-to-date with 'origin/master'.
1553++nothing to commit, working directory clean
1554++----
1555++
1556++This means you have a clean working directory; in other words, none of your tracked files are modified.
15671557 Git also doesn't see any untracked files, or they would be listed here.
15681558 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.
1569--For now, that branch is always `master`, which is the default; you won't worry about it here.
1570--<<ch03-git-branching#ch03-git-branching>> will go over branches and references in detail.
1571-+For now, that branch is always ``master'', which is the default; you won't worry about it here.
1572-+<<ch03-git-branching#ch03-git-branching>> will go over branches and references in detail.
1559+-For now, that branch is always ``master'', which is the default; you won't worry about it here.
1560+-<<ch03-git-branching#ch03-git-branching>> will go over branches and references in detail.
1561++For now, that branch is always `master`, which is the default; you won't worry about it here.
1562++<<ch03-git-branching#ch03-git-branching>> will go over branches and references in detail.
15731563
1574--Let's say you add a new file to your project, a simple `README` file.
1575-+Let's say you add a new file to your project, a simple README file.
1564+-Let's say you add a new file to your project, a simple README file.
1565++Let's say you add a new file to your project, a simple `README` file.
15761566 If the file didn't exist before, and you run `git status`, you see your untracked file like so:
15771567
1578--[source,console]
1579------
1580--$ echo 'My Project' > README
1581--$ git status
1582--On branch master
1583--Your branch is up-to-date with 'origin/master'.
1584--Untracked files:
1585-- (use "git add <file>..." to include in what will be committed)
1586--
1587-- README
1588--
1589--nothing added to commit but untracked files present (use "git add" to track)
1590------
1591--
1592--You can see that your new `README` file is untracked, because it's under the ``Untracked files'' heading in your status output.
1593-+You can see that your new README file is untracked, because it's under the ``Untracked files'' heading in your status output.
1568+-You can see that your new README file is untracked, because it's under the ``Untracked files'' heading in your status output.
1569++[source,console]
1570++----
1571++$ echo 'My Project' > README
1572++$ git status
1573++On branch master
1574++Your branch is up-to-date with 'origin/master'.
1575++Untracked files:
1576++ (use "git add <file>..." to include in what will be committed)
1577++
1578++ README
1579++
1580++nothing added to commit but untracked files present (use "git add" to track)
1581++----
1582++
1583++You can see that your new `README` file is untracked, because it's under the ``Untracked files'' heading in your status output.
15941584 Untracked basically means that Git sees a file you didn't have in the previous snapshot (commit); Git won't start including it in your commit snapshots until you explicitly tell it to do so.
15951585 It does this so you don't accidentally begin including generated binary files or other files that you did not mean to include.
1596--You do want to start including `README`, so let's start tracking the file.
1597-+You do want to start including README, so let's start tracking the file.
1586+-You do want to start including README, so let's start tracking the file.
1587++You do want to start including `README`, so let's start tracking the file.
15981588
1599--[[_tracking_files]]
1589++[[_tracking_files]]
16001590 ==== Tracking New Files
16011591
16021592 In order to begin tracking a new file, you use the command `git add`.(((git commands, add)))
1603--To begin tracking the `README` file, you can run this:
1604--
1605--[source,console]
1606------
1607--$ git add README
1608------
1609--
1610--If you run your status command again, you can see that your `README` file is now tracked and staged to be committed:
1611--
1612--[source,console]
1613------
1614--$ git status
1615--On branch master
1616--Your branch is up-to-date with 'origin/master'.
1617--Changes to be committed:
1618-- (use "git restore --staged <file>..." to unstage)
1619-+To begin tracking the README file, you can run this:
1620-
1621-- new file: README
1622--
1623------
1624-+If you run your status command again, you can see that your README file is now tracked and staged to be committed:
1593+-To begin tracking the README file, you can run this:
1594++To begin tracking the `README` file, you can run this:
1595++
1596++[source,console]
1597++----
1598++$ git add README
1599++----
1600++
1601++If you run your status command again, you can see that your `README` file is now tracked and staged to be committed:
1602++
1603++[source,console]
1604++----
1605++$ git status
1606++On branch master
1607++Your branch is up-to-date with 'origin/master'.
1608++Changes to be committed:
1609++ (use "git restore --staged <file>..." to unstage)
1610+
1611+-If you run your status command again, you can see that your README file is now tracked and staged to be committed:
1612++ new file: README
1613++
1614++----
16251615
16261616 You can tell that it's staged because it's under the ``Changes to be committed'' heading.
1627--If you commit at this point, the version of the file at the time you ran `git add` is what will be in the subsequent historical snapshot.
1628--You may recall that when you ran `git init` earlier, you then ran `git add <files>` -- that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add)))
1629-+If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot.
1630-+You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add)))
1617+-If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot.
1618+-You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add)))
1619++If you commit at this point, the version of the file at the time you ran `git add` is what will be in the subsequent historical snapshot.
1620++You may recall that when you ran `git init` earlier, you then ran `git add <files>` -- that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add)))
16311621 The `git add` command takes a path name for either a file or a directory; if it's a directory, the command adds all the files in that directory recursively.
16321622
16331623 ==== Staging Modified Files
1634-@@ -93,69 +50,17 @@
1624+@@ -50,17 +93,69 @@
16351625 Let's change a file that was already tracked.
16361626 If you change a previously tracked file called `CONTRIBUTING.md` and then run your `git status` command again, you get something that looks like this:
16371627
1638--[source,console]
1639------
1640--$ git status
1641--On branch master
1642--Your branch is up-to-date with 'origin/master'.
1643--Changes to be committed:
1644-- (use "git reset HEAD <file>..." to unstage)
1645--
1646-- new file: README
1647--
1648--Changes not staged for commit:
1649-- (use "git add <file>..." to update what will be committed)
1650-- (use "git checkout -- <file>..." to discard changes in working directory)
1651--
1652-- modified: CONTRIBUTING.md
1653--
1654------
1655--
1656--The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' -- which means that a file that is tracked has been modified in the working directory but not yet staged.
1657-+The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged.
1628+-The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged.
1629++[source,console]
1630++----
1631++$ git status
1632++On branch master
1633++Your branch is up-to-date with 'origin/master'.
1634++Changes to be committed:
1635++ (use "git reset HEAD <file>..." to unstage)
1636++
1637++ new file: README
1638++
1639++Changes not staged for commit:
1640++ (use "git add <file>..." to update what will be committed)
1641++ (use "git checkout -- <file>..." to discard changes in working directory)
1642++
1643++ modified: CONTRIBUTING.md
1644++
1645++----
1646++
1647++The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' -- which means that a file that is tracked has been modified in the working directory but not yet staged.
16581648 To stage it, you run the `git add` command.
1659--`git add` is a multipurpose command -- you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved.
1660--It may be helpful to think of it more as ``add precisely this content to the next commit'' rather than ``add this file to the project''.(((git commands, add)))
1661-+`git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved.
1662-+It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.(((git commands, add)))
1649+-`git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved.
1650+-It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.(((git commands, add)))
1651++`git add` is a multipurpose command -- you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved.
1652++It may be helpful to think of it more as ``add precisely this content to the next commit'' rather than ``add this file to the project''.(((git commands, add)))
16631653 Let's run `git add` now to stage the `CONTRIBUTING.md` file, and then run `git status` again:
16641654
1665--[source,console]
1666------
1667--$ git add CONTRIBUTING.md
1668--$ git status
1669--On branch master
1670--Your branch is up-to-date with 'origin/master'.
1671--Changes to be committed:
1672-- (use "git reset HEAD <file>..." to unstage)
1673--
1674-- new file: README
1675-- modified: CONTRIBUTING.md
1676--
1677------
1678--
1655++[source,console]
1656++----
1657++$ git add CONTRIBUTING.md
1658++$ git status
1659++On branch master
1660++Your branch is up-to-date with 'origin/master'.
1661++Changes to be committed:
1662++ (use "git reset HEAD <file>..." to unstage)
1663++
1664++ new file: README
1665++ modified: CONTRIBUTING.md
1666++
1667++----
1668++
16791669 Both files are staged and will go into your next commit.
16801670 At this point, suppose you remember one little change that you want to make in `CONTRIBUTING.md` before you commit it.
16811671 You open it again and make that change, and you're ready to commit.
16821672 However, let's run `git status` one more time:
16831673
1684--[source,console]
1685------
1686--$ vim CONTRIBUTING.md
1687--$ git status
1688--On branch master
1689--Your branch is up-to-date with 'origin/master'.
1690--Changes to be committed:
1691-- (use "git reset HEAD <file>..." to unstage)
1692--
1693-- new file: README
1694-- modified: CONTRIBUTING.md
1695--
1696--Changes not staged for commit:
1697-- (use "git add <file>..." to update what will be committed)
1698-- (use "git checkout -- <file>..." to discard changes in working directory)
1699--
1700-- modified: CONTRIBUTING.md
1701--
1702------
1703--
1674++[source,console]
1675++----
1676++$ vim CONTRIBUTING.md
1677++$ git status
1678++On branch master
1679++Your branch is up-to-date with 'origin/master'.
1680++Changes to be committed:
1681++ (use "git reset HEAD <file>..." to unstage)
1682++
1683++ new file: README
1684++ modified: CONTRIBUTING.md
1685++
1686++Changes not staged for commit:
1687++ (use "git add <file>..." to update what will be committed)
1688++ (use "git checkout -- <file>..." to discard changes in working directory)
1689++
1690++ modified: CONTRIBUTING.md
1691++
1692++----
1693++
17041694 What the heck?
17051695 Now `CONTRIBUTING.md` is listed as both staged _and_ unstaged.
17061696 How is that possible?
1707-@@ -163,41 +68,17 @@
1697+@@ -68,17 +163,41 @@
17081698 If you commit now, the version of `CONTRIBUTING.md` as it was when you last ran the `git add` command is how it will go into the commit, not the version of the file as it looks in your working directory when you run `git commit`.
17091699 If you modify a file after you run `git add`, you have to run `git add` again to stage the latest version of the file:
17101700
1711--[source,console]
1712------
1713--$ git add CONTRIBUTING.md
1714--$ git status
1715--On branch master
1716--Your branch is up-to-date with 'origin/master'.
1717--Changes to be committed:
1718-- (use "git reset HEAD <file>..." to unstage)
1719--
1720-- new file: README
1721-- modified: CONTRIBUTING.md
1722------
1723--
1701++[source,console]
1702++----
1703++$ git add CONTRIBUTING.md
1704++$ git status
1705++On branch master
1706++Your branch is up-to-date with 'origin/master'.
1707++Changes to be committed:
1708++ (use "git reset HEAD <file>..." to unstage)
1709++
1710++ new file: README
1711++ modified: CONTRIBUTING.md
1712++----
1713++
17241714 ==== Short Status
17251715
17261716 While the `git status` output is pretty comprehensive, it's also quite wordy.
17271717 Git also has a short status flag so you can see your changes in a more compact way.
17281718 If you run `git status -s` or `git status --short` you get a far more simplified output from the command:
17291719
1730--[source,console]
1731------
1732--$ git status -s
1733-- M README
1734--MM Rakefile
1735--A lib/git.rb
1736--M lib/simplegit.rb
1737--?? LICENSE.txt
1738------
1739--
1720++[source,console]
1721++----
1722++$ git status -s
1723++ M README
1724++MM Rakefile
1725++A lib/git.rb
1726++M lib/simplegit.rb
1727++?? LICENSE.txt
1728++----
1729++
17401730 New files that aren't tracked have a `??` next to them, new files that have been added to the staging area have an `A`, modified files have an `M` and so on.
1741--There are two columns to the output -- the left-hand column indicates the status of the staging area and the right-hand column indicates the status of the working tree.
1742-+There are two columns to the output - the left hand column indicates that the file is staged and the right hand column indicates that it's modified.
1731+-There are two columns to the output - the left hand column indicates that the file is staged and the right hand column indicates that it's modified.
1732++There are two columns to the output -- the left-hand column indicates the status of the staging area and the right-hand column indicates the status of the working tree.
17431733 So for example in that output, the `README` file is modified in the working directory but not yet staged, while the `lib/simplegit.rb` file is modified and staged.
17441734 The `Rakefile` was modified, staged and then modified again, so there are changes to it that are both staged and unstaged.
17451735
1746--[[_ignoring]]
1736++[[_ignoring]]
17471737 ==== Ignoring Files
17481738
17491739 Often, you'll have a class of files that you don't want Git to automatically add or even show you as being untracked.
1750-@@ -205,198 +86,57 @@
1740+@@ -86,57 +205,198 @@
17511741 In such cases, you can create a file listing patterns to match them named `.gitignore`.(((ignoring files)))
17521742 Here is an example `.gitignore` file:
17531743
1754--[source,console]
1755------
1756--$ cat .gitignore
1757--*.[oa]
1758--*~
1759------
1760--
1761--The first line tells Git to ignore any files ending in ``.o'' or ``.a'' -- object and archive files that may be the product of building your code.
1762--The second line tells Git to ignore all files whose names end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files.
1763-+The first line tells Git to ignore any files ending in ``.o'' or ``.a'' – object and archive files that may be the product of building your code.
1764-+The second line tells Git to ignore all files that end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files.
1744+-The first line tells Git to ignore any files ending in ``.o'' or ``.a'' – object and archive files that may be the product of building your code.
1745+-The second line tells Git to ignore all files that end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files.
1746++[source,console]
1747++----
1748++$ cat .gitignore
1749++*.[oa]
1750++*~
1751++----
1752++
1753++The first line tells Git to ignore any files ending in ``.o'' or ``.a'' -- object and archive files that may be the product of building your code.
1754++The second line tells Git to ignore all files whose names end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files.
17651755 You may also include a log, tmp, or pid directory; automatically generated documentation; and so on.
1766--Setting up a `.gitignore` file for your new repository before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository.
1767-+Setting up a `.gitignore` file before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository.
1756+-Setting up a `.gitignore` file before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository.
1757++Setting up a `.gitignore` file for your new repository before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository.
17681758
17691759 The rules for the patterns you can put in the `.gitignore` file are as follows:
17701760
17711761 * Blank lines or lines starting with `#` are ignored.
1772--* Standard glob patterns work, and will be applied recursively throughout the entire working tree.
1773-+* Standard glob patterns work.
1762+-* Standard glob patterns work.
1763++* Standard glob patterns work, and will be applied recursively throughout the entire working tree.
17741764 * You can start patterns with a forward slash (`/`) to avoid recursivity.
17751765 * You can end patterns with a forward slash (`/`) to specify a directory.
17761766 * You can negate a pattern by starting it with an exclamation point (`!`).
17771767
17781768 Glob patterns are like simplified regular expressions that shells use.
1779--An asterisk (`*`) matches zero or more characters; `[abc]` matches any character inside the brackets (in this case a, b, or c); a question mark (`?`) matches a single character; and brackets enclosing characters separated by a hyphen (`[0-9]`) matches any character between them (in this case 0 through 9).
1780-+An asterisk (`*`) matches zero or more characters; `[abc]` matches any character inside the brackets (in this case a, b, or c); a question mark (`?`) matches a single character; and brackets enclosing characters separated by a hyphen(`[0-9]`) matches any character between them (in this case 0 through 9).
1769+-An asterisk (`*`) matches zero or more characters; `[abc]` matches any character inside the brackets (in this case a, b, or c); a question mark (`?`) matches a single character; and brackets enclosing characters separated by a hyphen(`[0-9]`) matches any character between them (in this case 0 through 9).
1770++An asterisk (`*`) matches zero or more characters; `[abc]` matches any character inside the brackets (in this case a, b, or c); a question mark (`?`) matches a single character; and brackets enclosing characters separated by a hyphen (`[0-9]`) matches any character between them (in this case 0 through 9).
17811771 You can also use two asterisks to match nested directories; `a/**/z` would match `a/z`, `a/b/z`, `a/b/c/z`, and so on.
17821772
1783--Here is another example `.gitignore` file:
1784--
1785--[source]
1786------
1787--# ignore all .a files
1788--*.a
1789--
1790--# but do track lib.a, even though you're ignoring .a files above
1791--!lib.a
1792--
1793--# only ignore the TODO file in the current directory, not subdir/TODO
1794--/TODO
1795-+Here is another example .gitignore file:
1773+-Here is another example .gitignore file:
1774++Here is another example `.gitignore` file:
1775++
1776++[source]
1777++----
1778++# ignore all .a files
1779++*.a
1780++
1781++# but do track lib.a, even though you're ignoring .a files above
1782++!lib.a
1783++
1784++# only ignore the TODO file in the current directory, not subdir/TODO
1785++/TODO
17961786
1797--# ignore all files in any directory named build
1798--build/
1799--
1800--# ignore doc/notes.txt, but not doc/server/arch.txt
1801--doc/*.txt
1802--
1803--# ignore all .pdf files in the doc/ directory and any of its subdirectories
1804--doc/**/*.pdf
1805------
1806--
1807--[TIP]
1787++# ignore all files in any directory named build
1788++build/
1789++
1790++# ignore doc/notes.txt, but not doc/server/arch.txt
1791++doc/*.txt
1792++
1793++# ignore all .pdf files in the doc/ directory and any of its subdirectories
1794++doc/**/*.pdf
1795++----
1796++
1797++[TIP]
18081798 ====
18091799 GitHub maintains a fairly comprehensive list of good `.gitignore` file examples for dozens of projects and languages at https://github.com/github/gitignore[] if you want a starting point for your project.
18101800 ====
18111801
1812--[NOTE]
1813--====
1814--In the simple case, a repository might have a single `.gitignore` file in its root directory, which applies recursively to the entire repository.
1815--However, it is also possible to have additional `.gitignore` files in subdirectories.
1816--The rules in these nested `.gitignore` files apply only to the files under the directory where they are located.
1817--The Linux kernel source repository has 206 `.gitignore` files.
1818--
1819--It is beyond the scope of this book to get into the details of multiple `.gitignore` files; see `man gitignore` for the details.
1820--====
1821--
1822--[[_git_diff_staged]]
1802++[NOTE]
1803++====
1804++In the simple case, a repository might have a single `.gitignore` file in its root directory, which applies recursively to the entire repository.
1805++However, it is also possible to have additional `.gitignore` files in subdirectories.
1806++The rules in these nested `.gitignore` files apply only to the files under the directory where they are located.
1807++The Linux kernel source repository has 206 `.gitignore` files.
1808++
1809++It is beyond the scope of this book to get into the details of multiple `.gitignore` files; see `man gitignore` for the details.
1810++====
1811++
1812++[[_git_diff_staged]]
18231813 ==== Viewing Your Staged and Unstaged Changes
18241814
1825--If the `git status` command is too vague for you -- you want to know exactly what you changed, not just which files were changed -- you can use the `git diff` command.(((git commands, diff)))
1826-+If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.(((git commands, diff)))
1815+-If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.(((git commands, diff)))
1816++If the `git status` command is too vague for you -- you want to know exactly what you changed, not just which files were changed -- you can use the `git diff` command.(((git commands, diff)))
18271817 We'll cover `git diff` in more detail later, but you'll probably use it most often to answer these two questions: What have you changed but not yet staged?
18281818 And what have you staged that you are about to commit?
1829--Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed -- the patch, as it were.
1830-+Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were.
1819+-Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were.
1820++Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed -- the patch, as it were.
18311821
18321822 Let's say you edit and stage the `README` file again and then edit the `CONTRIBUTING.md` file without staging it.
18331823 If you run your `git status` command, you once again see something like this:
18341824
1835--[source,console]
1836------
1837--$ git status
1838--On branch master
1839--Your branch is up-to-date with 'origin/master'.
1840--Changes to be committed:
1841-- (use "git reset HEAD <file>..." to unstage)
1842--
1843-- modified: README
1844--
1845--Changes not staged for commit:
1846-- (use "git add <file>..." to update what will be committed)
1847-- (use "git checkout -- <file>..." to discard changes in working directory)
1848--
1849-- modified: CONTRIBUTING.md
1850------
1851--
1825++[source,console]
1826++----
1827++$ git status
1828++On branch master
1829++Your branch is up-to-date with 'origin/master'.
1830++Changes to be committed:
1831++ (use "git reset HEAD <file>..." to unstage)
1832++
1833++ modified: README
1834++
1835++Changes not staged for commit:
1836++ (use "git add <file>..." to update what will be committed)
1837++ (use "git checkout -- <file>..." to discard changes in working directory)
1838++
1839++ modified: CONTRIBUTING.md
1840++----
1841++
18521842 To see what you've changed but not yet staged, type `git diff` with no other arguments:
18531843
1854--[source,console]
1855------
1856--$ git diff
1857--diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1858--index 8ebb991..643e24f 100644
1859----- a/CONTRIBUTING.md
1860--+++ b/CONTRIBUTING.md
1861--@@ -65,7 +65,8 @@ branch directly, things can get messy.
1862-- Please include a nice description of your changes when you submit your PR;
1863-- if we have to read the whole diff to figure out why you're contributing
1864-- in the first place, you're less likely to get feedback and have your change
1865---merged in.
1866--+merged in. Also, split your changes into comprehensive chunks if your patch is
1867--+longer than a dozen lines.
1868--
1869-- If you are starting to work on a particular area, feel free to submit a PR
1870-- that highlights your work in progress (and note in the PR title that it's
1871------
1872--
1844++[source,console]
1845++----
1846++$ git diff
1847++diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1848++index 8ebb991..643e24f 100644
1849++--- a/CONTRIBUTING.md
1850+++++ b/CONTRIBUTING.md
1851++@@ -65,7 +65,8 @@ branch directly, things can get messy.
1852++ Please include a nice description of your changes when you submit your PR;
1853++ if we have to read the whole diff to figure out why you're contributing
1854++ in the first place, you're less likely to get feedback and have your change
1855++-merged in.
1856+++merged in. Also, split your changes into comprehensive chunks if your patch is
1857+++longer than a dozen lines.
1858++
1859++ If you are starting to work on a particular area, feel free to submit a PR
1860++ that highlights your work in progress (and note in the PR title that it's
1861++----
1862++
18731863 That command compares what is in your working directory with what is in your staging area.
18741864 The result tells you the changes you've made that you haven't yet staged.
18751865
18761866 If you want to see what you've staged that will go into your next commit, you can use `git diff --staged`.
18771867 This command compares your staged changes to your last commit:
18781868
1879--[source,console]
1880------
1881--$ git diff --staged
1882--diff --git a/README b/README
1883--new file mode 100644
1884--index 0000000..03902a1
1885----- /dev/null
1886--+++ b/README
1887--@@ -0,0 +1 @@
1888--+My Project
1889------
1890--
1891--It's important to note that `git diff` by itself doesn't show all changes made since your last commit -- only changes that are still unstaged.
1892--If you've staged all of your changes, `git diff` will give you no output.
1893-+It's important to note that `git diff` by itself doesn't show all changes made since your last commit – only changes that are still unstaged.
1894-+This can be confusing, because if you've staged all of your changes, `git diff` will give you no output.
1869+-It's important to note that `git diff` by itself doesn't show all changes made since your last commit – only changes that are still unstaged.
1870+-This can be confusing, because if you've staged all of your changes, `git diff` will give you no output.
1871++[source,console]
1872++----
1873++$ git diff --staged
1874++diff --git a/README b/README
1875++new file mode 100644
1876++index 0000000..03902a1
1877++--- /dev/null
1878+++++ b/README
1879++@@ -0,0 +1 @@
1880+++My Project
1881++----
1882++
1883++It's important to note that `git diff` by itself doesn't show all changes made since your last commit -- only changes that are still unstaged.
1884++If you've staged all of your changes, `git diff` will give you no output.
18951885
18961886 For another example, if you stage the `CONTRIBUTING.md` file and then edit it, you can use `git diff` to see the changes in the file that are staged and the changes that are unstaged.
18971887 If our environment looks like this:
18981888
1899--[source,console]
1900------
1901--$ git add CONTRIBUTING.md
1902--$ echo '# test line' >> CONTRIBUTING.md
1903--$ git status
1904--On branch master
1905--Your branch is up-to-date with 'origin/master'.
1906--Changes to be committed:
1907-- (use "git reset HEAD <file>..." to unstage)
1908--
1909-- modified: CONTRIBUTING.md
1910--
1911--Changes not staged for commit:
1912-- (use "git add <file>..." to update what will be committed)
1913-- (use "git checkout -- <file>..." to discard changes in working directory)
1914--
1915-- modified: CONTRIBUTING.md
1916------
1917--
1889++[source,console]
1890++----
1891++$ git add CONTRIBUTING.md
1892++$ echo '# test line' >> CONTRIBUTING.md
1893++$ git status
1894++On branch master
1895++Your branch is up-to-date with 'origin/master'.
1896++Changes to be committed:
1897++ (use "git reset HEAD <file>..." to unstage)
1898++
1899++ modified: CONTRIBUTING.md
1900++
1901++Changes not staged for commit:
1902++ (use "git add <file>..." to update what will be committed)
1903++ (use "git checkout -- <file>..." to discard changes in working directory)
1904++
1905++ modified: CONTRIBUTING.md
1906++----
1907++
19181908 Now you can use `git diff` to see what is still unstaged:
19191909
1920--[source,console]
1921------
1922--$ git diff
1923--diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1924--index 643e24f..87f08c8 100644
1925----- a/CONTRIBUTING.md
1926--+++ b/CONTRIBUTING.md
1927--@@ -119,3 +119,4 @@ at the
1928-- ## Starter Projects
1929--
1930-- See our [projects list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
1931--+# test line
1932------
1933--
1910++[source,console]
1911++----
1912++$ git diff
1913++diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1914++index 643e24f..87f08c8 100644
1915++--- a/CONTRIBUTING.md
1916+++++ b/CONTRIBUTING.md
1917++@@ -119,3 +119,4 @@ at the
1918++ ## Starter Projects
1919++
1920++ See our [projects list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
1921+++# test line
1922++----
1923++
19341924 and `git diff --cached` to see what you've staged so far (`--staged` and `--cached` are synonyms):
19351925
1936--[source,console]
1937------
1938--$ git diff --cached
1939--diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1940--index 8ebb991..643e24f 100644
1941----- a/CONTRIBUTING.md
1942--+++ b/CONTRIBUTING.md
1943--@@ -65,7 +65,8 @@ branch directly, things can get messy.
1944-- Please include a nice description of your changes when you submit your PR;
1945-- if we have to read the whole diff to figure out why you're contributing
1946-- in the first place, you're less likely to get feedback and have your change
1947---merged in.
1948--+merged in. Also, split your changes into comprehensive chunks if your patch is
1949--+longer than a dozen lines.
1950--
1951-- If you are starting to work on a particular area, feel free to submit a PR
1952-- that highlights your work in progress (and note in the PR title that it's
1953------
1954--
1955--[NOTE]
1926++[source,console]
1927++----
1928++$ git diff --cached
1929++diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
1930++index 8ebb991..643e24f 100644
1931++--- a/CONTRIBUTING.md
1932+++++ b/CONTRIBUTING.md
1933++@@ -65,7 +65,8 @@ branch directly, things can get messy.
1934++ Please include a nice description of your changes when you submit your PR;
1935++ if we have to read the whole diff to figure out why you're contributing
1936++ in the first place, you're less likely to get feedback and have your change
1937++-merged in.
1938+++merged in. Also, split your changes into comprehensive chunks if your patch is
1939+++longer than a dozen lines.
1940++
1941++ If you are starting to work on a particular area, feel free to submit a PR
1942++ that highlights your work in progress (and note in the PR title that it's
1943++----
1944++
1945++[NOTE]
19561946 .Git Diff in an External Tool
19571947 ====
19581948 We will continue to use the `git diff` command in various ways throughout the rest of the book.
1959-@@ -405,68 +145,27 @@
1949+@@ -145,27 +405,68 @@
19601950 Run `git difftool --tool-help` to see what is available on your system.
19611951 ====
19621952
1963--[[_committing_changes]]
1953++[[_committing_changes]]
19641954 ==== Committing Your Changes
19651955
19661956 Now that your staging area is set up the way you want it, you can commit your changes.
1967--Remember that anything that is still unstaged -- any files you have created or modified that you haven't run `git add` on since you edited them -- won't go into this commit.
1968-+Remember that anything that is still unstaged – any files you have created or modified that you haven't run `git add` on since you edited them – won't go into this commit.
1957+-Remember that anything that is still unstaged – any files you have created or modified that you haven't run `git add` on since you edited them – won't go into this commit.
1958++Remember that anything that is still unstaged -- any files you have created or modified that you haven't run `git add` on since you edited them -- won't go into this commit.
19691959 They will stay as modified files on your disk.
19701960 In this case, let's say that the last time you ran `git status`, you saw that everything was staged, so you're ready to commit your changes.(((git commands, status)))
19711961 The simplest way to commit is to type `git commit`:(((git commands, commit)))
19721962
1973--[source,console]
1974------
1975--$ git commit
1976------
1977--
1963++[source,console]
1964++----
1965++$ git commit
1966++----
1967++
19781968 Doing so launches your editor of choice.
1979--
1980--[NOTE]
1981--====
1982--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 <<ch01-getting-started#ch01-getting-started>>.(((editor, changing default)))(((git commands, config)))
1983--====
1984-+(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 <<ch01-introduction#ch01-introduction>>).(((editor, changing default)))(((git commands, config)))
1969+-(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 <<ch01-introduction#ch01-introduction>>).(((editor, changing default)))(((git commands, config)))
1970++
1971++[NOTE]
1972++====
1973++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 <<ch01-getting-started#ch01-getting-started>>.(((editor, changing default)))(((git commands, config)))
1974++====
19851975
19861976 The editor displays the following text (this example is a Vim screen):
19871977
1988--[source]
1989------
1990--
1991--# Please enter the commit message for your changes. Lines starting
1992--# with '#' will be ignored, and an empty message aborts the commit.
1993--# On branch master
1994--# Your branch is up-to-date with 'origin/master'.
1995--#
1996--# Changes to be committed:
1997--# new file: README
1998--# modified: CONTRIBUTING.md
1999--#
2000--~
2001--~
2002--~
2003--".git/COMMIT_EDITMSG" 9L, 283C
2004------
2005--
1978++[source]
1979++----
1980++
1981++# Please enter the commit message for your changes. Lines starting
1982++# with '#' will be ignored, and an empty message aborts the commit.
1983++# On branch master
1984++# Your branch is up-to-date with 'origin/master'.
1985++#
1986++# Changes to be committed:
1987++# new file: README
1988++# modified: CONTRIBUTING.md
1989++#
1990++~
1991++~
1992++~
1993++".git/COMMIT_EDITMSG" 9L, 283C
1994++----
1995++
20061996 You can see that the default commit message contains the latest output of the `git status` command commented out and one empty line on top.
20071997 You can remove these comments and type your commit message, or you can leave them there to help you remember what you're committing.
2008--
2009--[NOTE]
2010--====
2011--For an even more explicit reminder of what you've modified, you can pass the `-v` option to `git commit`.
2012--Doing so also puts the diff of your change in the editor so you can see exactly what changes you're committing.
2013--====
2014--
2015-+(For an even more explicit reminder of what you've modified, you can pass the `-v` option to `git commit`.
2016-+Doing so also puts the diff of your change in the editor so you can see exactly what changes you're committing.)
1998+-(For an even more explicit reminder of what you've modified, you can pass the `-v` option to `git commit`.
1999+-Doing so also puts the diff of your change in the editor so you can see exactly what changes you're committing.)
2000++
2001++[NOTE]
2002++====
2003++For an even more explicit reminder of what you've modified, you can pass the `-v` option to `git commit`.
2004++Doing so also puts the diff of your change in the editor so you can see exactly what changes you're committing.
2005++====
2006++
20172007 When you exit the editor, Git creates your commit with that commit message (with the comments and diff stripped out).
20182008
20192009 Alternatively, you can type your commit message inline with the `commit` command by specifying it after a `-m` flag, like this:
20202010
2021--[source,console]
2022------
2023--$ git commit -m "Story 182: fix benchmarks for speed"
2024--[master 463dc4f] Story 182: fix benchmarks for speed
2025-- 2 files changed, 2 insertions(+)
2026-- create mode 100644 README
2027------
2028--
2011++[source,console]
2012++----
2013++$ git commit -m "Story 182: fix benchmarks for speed"
2014++[master 463dc4f] Story 182: fix benchmarks for speed
2015++ 2 files changed, 2 insertions(+)
2016++ create mode 100644 README
2017++----
2018++
20292019 Now you've created your first commit!
20302020 You can see that the commit has given you some output about itself: which branch you committed to (`master`), what SHA-1 checksum the commit has (`463dc4f`), how many files were changed, and statistics about lines added and removed in the commit.
20312021
2032-@@ -476,73 +175,25 @@
2022+@@ -175,25 +476,73 @@
20332023
20342024 ==== Skipping the Staging Area
20352025
2036--(((staging area, skipping)))
2026++(((staging area, skipping)))
20372027 Although it can be amazingly useful for crafting commits exactly how you want them, the staging area is sometimes a bit more complex than you need in your workflow.
20382028 If you want to skip the staging area, Git provides a simple shortcut.
20392029 Adding the `-a` option to the `git commit` command makes Git automatically stage every file that is already tracked before doing the commit, letting you skip the `git add` part:
20402030
2041--[source,console]
2042------
2043--$ git status
2044--On branch master
2045--Your branch is up-to-date with 'origin/master'.
2046--Changes not staged for commit:
2047-- (use "git add <file>..." to update what will be committed)
2048-- (use "git checkout -- <file>..." to discard changes in working directory)
2049--
2050-- modified: CONTRIBUTING.md
2051--
2052--no changes added to commit (use "git add" and/or "git commit -a")
2053--$ git commit -a -m 'Add new benchmarks'
2054--[master 83e38c7] Add new benchmarks
2055-- 1 file changed, 5 insertions(+), 0 deletions(-)
2056------
2057--
2031++[source,console]
2032++----
2033++$ git status
2034++On branch master
2035++Your branch is up-to-date with 'origin/master'.
2036++Changes not staged for commit:
2037++ (use "git add <file>..." to update what will be committed)
2038++ (use "git checkout -- <file>..." to discard changes in working directory)
2039++
2040++ modified: CONTRIBUTING.md
2041++
2042++no changes added to commit (use "git add" and/or "git commit -a")
2043++$ git commit -a -m 'Add new benchmarks'
2044++[master 83e38c7] Add new benchmarks
2045++ 1 file changed, 5 insertions(+), 0 deletions(-)
2046++----
2047++
20582048 Notice how you don't have to run `git add` on the `CONTRIBUTING.md` file in this case before you commit.
20592049 That's because the `-a` flag includes all changed files.
20602050 This is convenient, but be careful; sometimes this flag will cause you to include unwanted changes.
20612051
2062--[[_removing_files]]
2052++[[_removing_files]]
20632053 ==== Removing Files
20642054
2065--(((files, removing)))
2055++(((files, removing)))
20662056 To remove a file from Git, you have to remove it from your tracked files (more accurately, remove it from your staging area) and then commit.
20672057 The `git rm` command does that, and also removes the file from your working directory so you don't see it as an untracked file the next time around.
20682058
2069--If you simply remove the file from your working directory, it shows up under the ``Changes not staged for commit'' (that is, _unstaged_) area of your `git status` output:
2070--
2071--[source,console]
2072------
2073--$ rm PROJECTS.md
2074--$ git status
2075--On branch master
2076--Your branch is up-to-date with 'origin/master'.
2077--Changes not staged for commit:
2078-- (use "git add/rm <file>..." to update what will be committed)
2079-- (use "git checkout -- <file>..." to discard changes in working directory)
2080--
2081-- deleted: PROJECTS.md
2082--
2083--no changes added to commit (use "git add" and/or "git commit -a")
2084------
2085-+If you simply remove the file from your working directory, it shows up under the ``Changed but not updated'' (that is, _unstaged_) area of your `git status` output:
2059+-If you simply remove the file from your working directory, it shows up under the ``Changed but not updated'' (that is, _unstaged_) area of your `git status` output:
2060++If you simply remove the file from your working directory, it shows up under the ``Changes not staged for commit'' (that is, _unstaged_) area of your `git status` output:
2061++
2062++[source,console]
2063++----
2064++$ rm PROJECTS.md
2065++$ git status
2066++On branch master
2067++Your branch is up-to-date with 'origin/master'.
2068++Changes not staged for commit:
2069++ (use "git add/rm <file>..." to update what will be committed)
2070++ (use "git checkout -- <file>..." to discard changes in working directory)
2071++
2072++ deleted: PROJECTS.md
2073++
2074++no changes added to commit (use "git add" and/or "git commit -a")
2075++----
20862076
20872077 Then, if you run `git rm`, it stages the file's removal:
20882078
2089--[source,console]
2090------
2091--$ git rm PROJECTS.md
2092--rm 'PROJECTS.md'
2093--$ git status
2094--On branch master
2095--Your branch is up-to-date with 'origin/master'.
2096--Changes to be committed:
2097-- (use "git reset HEAD <file>..." to unstage)
2098--
2099-- deleted: PROJECTS.md
2100------
2101--
2079++[source,console]
2080++----
2081++$ git rm PROJECTS.md
2082++rm 'PROJECTS.md'
2083++$ git status
2084++On branch master
2085++Your branch is up-to-date with 'origin/master'.
2086++Changes to be committed:
2087++ (use "git reset HEAD <file>..." to unstage)
2088++
2089++ deleted: PROJECTS.md
2090++----
2091++
21022092 The next time you commit, the file will be gone and no longer tracked.
2103--If you modified the file or had already added it to the staging area, you must force the removal with the `-f` option.
2104-+If you modified the file and added it to the index already, you must force the removal with the `-f` option.
2093+-If you modified the file and added it to the index already, you must force the removal with the `-f` option.
2094++If you modified the file or had already added it to the staging area, you must force the removal with the `-f` option.
21052095 This is a safety feature to prevent accidental removal of data that hasn't yet been recorded in a snapshot and that can't be recovered from Git.
21062096
21072097 Another useful thing you may want to do is to keep the file in your working tree but remove it from your staging area.
2108-@@ -550,71 +201,30 @@
2098+@@ -201,30 +550,71 @@
21092099 This is particularly useful if you forgot to add something to your `.gitignore` file and accidentally staged it, like a large log file or a bunch of `.a` compiled files.
21102100 To do this, use the `--cached` option:
21112101
2112--[source,console]
2113------
2114--$ git rm --cached README
2115------
2116--
2102++[source,console]
2103++----
2104++$ git rm --cached README
2105++----
2106++
21172107 You can pass files, directories, and file-glob patterns to the `git rm` command.
21182108 That means you can do things such as:
21192109
2120--[source,console]
2121------
2122--$ git rm log/\*.log
2123------
2124--
2110++[source,console]
2111++----
2112++$ git rm log/\*.log
2113++----
2114++
21252115 Note the backslash (`\`) in front of the `*`.
21262116 This is necessary because Git does its own filename expansion in addition to your shell's filename expansion.
21272117 This command removes all files that have the `.log` extension in the `log/` directory.
21282118 Or, you can do something like this:
21292119
2130--[source,console]
2131------
2132--$ git rm \*~
2133------
2134-+This command removes all files that end with `~`.
2120+-This command removes all files that end with `~`.
2121++[source,console]
2122++----
2123++$ git rm \*~
2124++----
21352125
2136--This command removes all files whose names end with a `~`.
2137--
2138--[[_git_mv]]
2126++This command removes all files whose names end with a `~`.
2127++
2128++[[_git_mv]]
21392129 ==== Moving Files
21402130
2141--(((files, moving)))
2131++(((files, moving)))
21422132 Unlike many other VCS systems, Git doesn't explicitly track file movement.
21432133 If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file.
2144--However, Git is pretty smart about figuring that out after the fact -- we'll deal with detecting file movement a bit later.
2145-+However, Git is pretty smart about figuring that out after the fact – we'll deal with detecting file movement a bit later.
2134+-However, Git is pretty smart about figuring that out after the fact – we'll deal with detecting file movement a bit later.
2135++However, Git is pretty smart about figuring that out after the fact -- we'll deal with detecting file movement a bit later.
21462136
21472137 Thus it's a bit confusing that Git has a `mv` command.
21482138 If you want to rename a file in Git, you can run something like:
21492139
2150--[source,console]
2151------
2152--$ git mv file_from file_to
2153------
2154--
2140++[source,console]
2141++----
2142++$ git mv file_from file_to
2143++----
2144++
21552145 and it works fine.
21562146 In fact, if you run something like this and look at the status, you'll see that Git considers it a renamed file:
21572147
2158--[source,console]
2159------
2160--$ git mv README.md README
2161--$ git status
2162--On branch master
2163--Your branch is up-to-date with 'origin/master'.
2164--Changes to be committed:
2165-- (use "git reset HEAD <file>..." to unstage)
2166--
2167-- renamed: README.md -> README
2168------
2169--
2148++[source,console]
2149++----
2150++$ git mv README.md README
2151++$ git status
2152++On branch master
2153++Your branch is up-to-date with 'origin/master'.
2154++Changes to be committed:
2155++ (use "git reset HEAD <file>..." to unstage)
2156++
2157++ renamed: README.md -> README
2158++----
2159++
21702160 However, this is equivalent to running something like this:
21712161
2172--[source,console]
2173------
2174--$ mv README.md README
2175--$ git rm README.md
2176--$ git add README
2177------
2178--
2162++[source,console]
2163++----
2164++$ mv README.md README
2165++$ git rm README.md
2166++$ git add README
2167++----
2168++
21792169 Git figures out that it's a rename implicitly, so it doesn't matter if you rename a file that way or with the `mv` command.
2180--The only real difference is that `git mv` is one command instead of three -- it's a convenience function.
2181-+The only real difference is that `mv` is one command instead of three – it's a convenience function.
2170+-The only real difference is that `mv` is one command instead of three – it's a convenience function.
2171++The only real difference is that `git mv` is one command instead of three -- it's a convenience function.
21822172 More importantly, you can use any tool you like to rename a file, and address the add/rm later, before you commit.
2183-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/remotes.asc /tmp/book/02-git-basics/sections/remotes.asc.tmp
2184---- ../../git/progit2/progit2/book/02-git-basics/sections/remotes.asc 2020-07-17 09:06:42.261936072 +0900
2185-+++ /tmp/book/02-git-basics/sections/remotes.asc.tmp 2020-10-25 09:24:25.633965632 +0900
2173+diff -au /tmp/book/02-git-basics/sections/remotes.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/remotes.asc
2174+--- /tmp/book/02-git-basics/sections/remotes.asc.tmp 2020-10-25 11:05:02.167635122 +0900
2175++++ ../../git/progit2/progit2/book/02-git-basics/sections/remotes.asc 2020-07-17 09:06:42.261936072 +0900
21862176 @@ -1,4 +1,4 @@
2187--[[_remote_repos]]
2188-+[[r_remote_repos]]
2177+-[[r_remote_repos]]
2178++[[_remote_repos]]
21892179 === Working with Remotes
21902180
21912181 To be able to collaborate on any Git project, you need to know how to manage your remote repositories.
2192-@@ -8,233 +8,81 @@
2182+@@ -8,81 +8,233 @@
21932183 Managing remote repositories includes knowing how to add remote repositories, remove remotes that are no longer valid, manage various remote branches and define them as being tracked or not, and more.
21942184 In this section, we'll cover some of these remote-management skills.
21952185
2196--[NOTE]
2197--.Remote repositories can be on your local machine.
2198--====
2199--It is entirely possible that you can be working with a ``remote'' repository that is, in fact, on the same host you are.
2200--The word ``remote'' does not necessarily imply that the repository is somewhere else on the network or Internet, only that it is elsewhere.
2201--Working with such a remote repository would still involve all the standard pushing, pulling and fetching operations as with any other remote.
2202--====
2203--
2186++[NOTE]
2187++.Remote repositories can be on your local machine.
2188++====
2189++It is entirely possible that you can be working with a ``remote'' repository that is, in fact, on the same host you are.
2190++The word ``remote'' does not necessarily imply that the repository is somewhere else on the network or Internet, only that it is elsewhere.
2191++Working with such a remote repository would still involve all the standard pushing, pulling and fetching operations as with any other remote.
2192++====
2193++
22042194 ==== Showing Your Remotes
22052195
22062196 To see which remote servers you have configured, you can run the `git remote` command.(((git commands, remote)))
22072197 It lists the shortnames of each remote handle you've specified.
2208--If you've cloned your repository, you should at least see `origin` -- that is the default name Git gives to the server you cloned from:
2209--
2210--[source,console]
2211------
2212--$ git clone https://github.com/schacon/ticgit
2213--Cloning into 'ticgit'...
2214--remote: Reusing existing pack: 1857, done.
2215--remote: Total 1857 (delta 0), reused 0 (delta 0)
2216--Receiving objects: 100% (1857/1857), 374.35 KiB | 268.00 KiB/s, done.
2217--Resolving deltas: 100% (772/772), done.
2218--Checking connectivity... done.
2219--$ cd ticgit
2220--$ git remote
2221--origin
2222------
2223-+If you've cloned your repository, you should at least see origin – that is the default name Git gives to the server you cloned from:
2198+-If you've cloned your repository, you should at least see origin – that is the default name Git gives to the server you cloned from:
2199++If you've cloned your repository, you should at least see `origin` -- that is the default name Git gives to the server you cloned from:
2200++
2201++[source,console]
2202++----
2203++$ git clone https://github.com/schacon/ticgit
2204++Cloning into 'ticgit'...
2205++remote: Reusing existing pack: 1857, done.
2206++remote: Total 1857 (delta 0), reused 0 (delta 0)
2207++Receiving objects: 100% (1857/1857), 374.35 KiB | 268.00 KiB/s, done.
2208++Resolving deltas: 100% (772/772), done.
2209++Checking connectivity... done.
2210++$ cd ticgit
2211++$ git remote
2212++origin
2213++----
22242214
22252215 You can also specify `-v`, which shows you the URLs that Git has stored for the shortname to be used when reading and writing to that remote:
22262216
2227--[source,console]
2228------
2229--$ git remote -v
2230--origin https://github.com/schacon/ticgit (fetch)
2231--origin https://github.com/schacon/ticgit (push)
2232------
2233--
2217++[source,console]
2218++----
2219++$ git remote -v
2220++origin https://github.com/schacon/ticgit (fetch)
2221++origin https://github.com/schacon/ticgit (push)
2222++----
2223++
22342224 If you have more than one remote, the command lists them all.
22352225 For example, a repository with multiple remotes for working with several collaborators might look something like this.
22362226
2237--[source,console]
2238------
2239--$ cd grit
2240--$ git remote -v
2241--bakkdoor https://github.com/bakkdoor/grit (fetch)
2242--bakkdoor https://github.com/bakkdoor/grit (push)
2243--cho45 https://github.com/cho45/grit (fetch)
2244--cho45 https://github.com/cho45/grit (push)
2245--defunkt https://github.com/defunkt/grit (fetch)
2246--defunkt https://github.com/defunkt/grit (push)
2247--koke git://github.com/koke/grit.git (fetch)
2248--koke git://github.com/koke/grit.git (push)
2249--origin git@github.com:mojombo/grit.git (fetch)
2250--origin git@github.com:mojombo/grit.git (push)
2251------
2252--
2227++[source,console]
2228++----
2229++$ cd grit
2230++$ git remote -v
2231++bakkdoor https://github.com/bakkdoor/grit (fetch)
2232++bakkdoor https://github.com/bakkdoor/grit (push)
2233++cho45 https://github.com/cho45/grit (fetch)
2234++cho45 https://github.com/cho45/grit (push)
2235++defunkt https://github.com/defunkt/grit (fetch)
2236++defunkt https://github.com/defunkt/grit (push)
2237++koke git://github.com/koke/grit.git (fetch)
2238++koke git://github.com/koke/grit.git (push)
2239++origin git@github.com:mojombo/grit.git (fetch)
2240++origin git@github.com:mojombo/grit.git (push)
2241++----
2242++
22532243 This means we can pull contributions from any of these users pretty easily.
22542244 We may additionally have permission to push to one or more of these, though we can't tell that here.
22552245
2256--Notice that these remotes use a variety of protocols; we'll cover more about this in <<ch04-git-on-the-server#_getting_git_on_a_server>>.
2257-+Notice that these remotes use a variety of protocols; we'll cover more about this in <<ch04-git-server#r_git_on_the_server>>.
2246+-Notice that these remotes use a variety of protocols; we'll cover more about this in <<ch04-git-server#r_git_on_the_server>>.
2247++Notice that these remotes use a variety of protocols; we'll cover more about this in <<ch04-git-on-the-server#_getting_git_on_a_server>>.
22582248
22592249 ==== Adding Remote Repositories
22602250
2261--We've mentioned and given some demonstrations of how the `git clone` command implicitly adds the `origin` remote for you.
2262--Here's how to add a new remote explicitly.(((git commands, remote)))
2263-+We've mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.(((git commands, remote)))
2251+-We've mentioned and given some demonstrations of adding remote repositories in previous sections, but here is how to do it explicitly.(((git commands, remote)))
2252++We've mentioned and given some demonstrations of how the `git clone` command implicitly adds the `origin` remote for you.
2253++Here's how to add a new remote explicitly.(((git commands, remote)))
22642254 To add a new remote Git repository as a shortname you can reference easily, run `git remote add <shortname> <url>`:
22652255
2266--[source,console]
2267------
2268--$ git remote
2269--origin
2270--$ git remote add pb https://github.com/paulboone/ticgit
2271--$ git remote -v
2272--origin https://github.com/schacon/ticgit (fetch)
2273--origin https://github.com/schacon/ticgit (push)
2274--pb https://github.com/paulboone/ticgit (fetch)
2275--pb https://github.com/paulboone/ticgit (push)
2276------
2277--
2256++[source,console]
2257++----
2258++$ git remote
2259++origin
2260++$ git remote add pb https://github.com/paulboone/ticgit
2261++$ git remote -v
2262++origin https://github.com/schacon/ticgit (fetch)
2263++origin https://github.com/schacon/ticgit (push)
2264++pb https://github.com/paulboone/ticgit (fetch)
2265++pb https://github.com/paulboone/ticgit (push)
2266++----
2267++
22782268 Now you can use the string `pb` on the command line in lieu of the whole URL.
22792269 For example, if you want to fetch all the information that Paul has but that you don't yet have in your repository, you can run `git fetch pb`:
22802270
2281--[source,console]
2282------
2283--$ git fetch pb
2284--remote: Counting objects: 43, done.
2285--remote: Compressing objects: 100% (36/36), done.
2286--remote: Total 43 (delta 10), reused 31 (delta 5)
2287--Unpacking objects: 100% (43/43), done.
2288--From https://github.com/paulboone/ticgit
2289-- * [new branch] master -> pb/master
2290-- * [new branch] ticgit -> pb/ticgit
2291------
2292--
2293--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.
2294--We'll go over what branches are and how to use them in much more detail in <<ch03-git-branching#ch03-git-branching>>.
2295-+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.
2296-+(We'll go over what branches are and how to use them in much more detail in <<ch03-git-branching#ch03-git-branching>>.)
2271+-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.
2272+-(We'll go over what branches are and how to use them in much more detail in <<ch03-git-branching#ch03-git-branching>>.)
2273++[source,console]
2274++----
2275++$ git fetch pb
2276++remote: Counting objects: 43, done.
2277++remote: Compressing objects: 100% (36/36), done.
2278++remote: Total 43 (delta 10), reused 31 (delta 5)
2279++Unpacking objects: 100% (43/43), done.
2280++From https://github.com/paulboone/ticgit
2281++ * [new branch] master -> pb/master
2282++ * [new branch] ticgit -> pb/ticgit
2283++----
2284++
2285++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.
2286++We'll go over what branches are and how to use them in much more detail in <<ch03-git-branching#ch03-git-branching>>.
22972287
2298--[[_fetching_and_pulling]]
2288++[[_fetching_and_pulling]]
22992289 ==== Fetching and Pulling from Your Remotes
23002290
23012291 As you just saw, to get data from your remote projects, you can run:(((git commands, fetch)))
23022292
2303--[source,console]
2304------
2305--$ git fetch <remote>
2306------
2307--
2293++[source,console]
2294++----
2295++$ git fetch <remote>
2296++----
2297++
23082298 The command goes out to that remote project and pulls down all the data from that remote project that you don't have yet.
23092299 After you do this, you should have references to all the branches from that remote, which you can merge in or inspect at any time.
23102300
23112301 If you clone a repository, the command automatically adds that remote repository under the name ``origin''.
23122302 So, `git fetch origin` fetches any new work that has been pushed to that server since you cloned (or last fetched from) it.
2313--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.
2314-+It's important to note that the `git fetch` command pulls the data to your local repository – it doesn't automatically merge it with any of your work or modify what you're currently working on.
2303+-It's important to note that the `git fetch` command pulls the data to your local repository – it doesn't automatically merge it with any of your work or modify what you're currently working on.
2304++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.
23152305 You have to merge it manually into your work when you're ready.
23162306
2317--If your current branch is set up to track a remote branch (see the next section and <<ch03-git-branching#ch03-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)))
2318--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.
2319-+If you have a branch set up to track a remote branch (see the next section and <<ch03-git-branching#ch03-git-branching>> for more information), you can use the `git pull` command to automatically fetch and then merge a remote branch into your current branch.(((git commands, pull)))
2320-+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.
2307+-If you have a branch set up to track a remote branch (see the next section and <<ch03-git-branching#ch03-git-branching>> for more information), you can use the `git pull` command to automatically fetch and then merge a remote branch into your current branch.(((git commands, pull)))
2308+-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.
2309++If your current branch is set up to track a remote branch (see the next section and <<ch03-git-branching#ch03-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)))
2310++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.
23212311 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.
23222312
2323--[NOTE]
2324--====
2325--From git version 2.27 onward, `git pull` will give a warning if the `pull.rebase` variable is not set.
2326--Git will keep warning you until you set the variable.
2327--
2328--If you want the default behavior of git (fast-forward if possible, else create a merge commit):
2329--`git config --global pull.rebase "false"`
2330--
2331--If you want to rebase when pulling:
2332--`git config --global pull.rebase "true"`
2333--====
2334--
2335--[[_pushing_remotes]]
2313++[NOTE]
2314++====
2315++From git version 2.27 onward, `git pull` will give a warning if the `pull.rebase` variable is not set.
2316++Git will keep warning you until you set the variable.
2317++
2318++If you want the default behavior of git (fast-forward if possible, else create a merge commit):
2319++`git config --global pull.rebase "false"`
2320++
2321++If you want to rebase when pulling:
2322++`git config --global pull.rebase "true"`
2323++====
2324++
2325++[[_pushing_remotes]]
23362326 ==== Pushing to Your Remotes
23372327
23382328 When you have your project at a point that you want to share, you have to push it upstream.
2339--The command for this is simple: `git push <remote> <branch>`.(((git commands, push)))
2340--If you want to push your `master` branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server:
2341--
2342--[source,console]
2343------
2344--$ git push origin master
2345------
2346-+The command for this is simple: `git push [remote-name] [branch-name]`.(((git commands, push)))
2347-+If you want to push your master branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server:
2329+-The command for this is simple: `git push [remote-name] [branch-name]`.(((git commands, push)))
2330+-If you want to push your master branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server:
2331++The command for this is simple: `git push <remote> <branch>`.(((git commands, push)))
2332++If you want to push your `master` branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server:
2333++
2334++[source,console]
2335++----
2336++$ git push origin master
2337++----
23482338
23492339 This command works only if you cloned from a server to which you have write access and if nobody has pushed in the meantime.
23502340 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.
2351--You'll have to fetch their work first and incorporate it into yours before you'll be allowed to push.
2352-+You'll have to pull down their work first and incorporate it into yours before you'll be allowed to push.
2341+-You'll have to pull down their work first and incorporate it into yours before you'll be allowed to push.
2342++You'll have to fetch their work first and incorporate it into yours before you'll be allowed to push.
23532343 See <<ch03-git-branching#ch03-git-branching>> for more detailed information on how to push to remote servers.
23542344
2355--[[_inspecting_remote]]
2345++[[_inspecting_remote]]
23562346 ==== Inspecting a Remote
23572347
2358--If you want to see more information about a particular remote, you can use the `git remote show <remote>` command.(((git commands, remote)))
2359-+If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.(((git commands, remote)))
2348+-If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.(((git commands, remote)))
2349++If you want to see more information about a particular remote, you can use the `git remote show <remote>` command.(((git commands, remote)))
23602350 If you run this command with a particular shortname, such as `origin`, you get something like this:
23612351
2362--[source,console]
2363------
2364--$ git remote show origin
2365--* remote origin
2366-- Fetch URL: https://github.com/schacon/ticgit
2367-- Push URL: https://github.com/schacon/ticgit
2368-- HEAD branch: master
2369-- Remote branches:
2370-- master tracked
2371-- dev-branch tracked
2372-- Local branch configured for 'git pull':
2373-- master merges with remote master
2374-- Local ref configured for 'git push':
2375-- master pushes to master (up to date)
2376------
2377--
2352++[source,console]
2353++----
2354++$ git remote show origin
2355++* remote origin
2356++ Fetch URL: https://github.com/schacon/ticgit
2357++ Push URL: https://github.com/schacon/ticgit
2358++ HEAD branch: master
2359++ Remote branches:
2360++ master tracked
2361++ dev-branch tracked
2362++ Local branch configured for 'git pull':
2363++ master merges with remote master
2364++ Local ref configured for 'git push':
2365++ master pushes to master (up to date)
2366++----
2367++
23782368 It lists the URL for the remote repository as well as the tracking branch information.
2379--The command helpfully tells you that if you're on the `master` branch and you run `git pull`, it will automatically merge in the `master` branch on the remote after it fetches all the remote references.
2380-+The command helpfully tells you that if you're on the master branch and you run `git pull`, it will automatically merge in the master branch on the remote after it fetches all the remote references.
2369+-The command helpfully tells you that if you're on the master branch and you run `git pull`, it will automatically merge in the master branch on the remote after it fetches all the remote references.
2370++The command helpfully tells you that if you're on the `master` branch and you run `git pull`, it will automatically merge in the `master` branch on the remote after it fetches all the remote references.
23812371 It also lists all the remote references it has pulled down.
23822372
23832373 That is a simple example you're likely to encounter.
23842374 When you're using Git more heavily, however, you may see much more information from `git remote show`:
23852375
2386--[source,console]
2387------
2388--$ git remote show origin
2389--* remote origin
2390-- URL: https://github.com/my-org/complex-project
2391-- Fetch URL: https://github.com/my-org/complex-project
2392-- Push URL: https://github.com/my-org/complex-project
2393-- HEAD branch: master
2394-- Remote branches:
2395-- master tracked
2396-- dev-branch tracked
2397-- markdown-strip tracked
2398-- issue-43 new (next fetch will store in remotes/origin)
2399-- issue-45 new (next fetch will store in remotes/origin)
2400-- refs/remotes/origin/issue-11 stale (use 'git remote prune' to remove)
2401-- Local branches configured for 'git pull':
2402-- dev-branch merges with remote dev-branch
2403-- master merges with remote master
2404-- Local refs configured for 'git push':
2405-- dev-branch pushes to dev-branch (up to date)
2406-- markdown-strip pushes to markdown-strip (up to date)
2407-- master pushes to master (up to date)
2408------
2409--
2376++[source,console]
2377++----
2378++$ git remote show origin
2379++* remote origin
2380++ URL: https://github.com/my-org/complex-project
2381++ Fetch URL: https://github.com/my-org/complex-project
2382++ Push URL: https://github.com/my-org/complex-project
2383++ HEAD branch: master
2384++ Remote branches:
2385++ master tracked
2386++ dev-branch tracked
2387++ markdown-strip tracked
2388++ issue-43 new (next fetch will store in remotes/origin)
2389++ issue-45 new (next fetch will store in remotes/origin)
2390++ refs/remotes/origin/issue-11 stale (use 'git remote prune' to remove)
2391++ Local branches configured for 'git pull':
2392++ dev-branch merges with remote dev-branch
2393++ master merges with remote master
2394++ Local refs configured for 'git push':
2395++ dev-branch pushes to dev-branch (up to date)
2396++ markdown-strip pushes to markdown-strip (up to date)
2397++ master pushes to master (up to date)
2398++----
2399++
24102400 This command shows which branch is automatically pushed to when you run `git push` while on certain branches.
2411--It also shows you which remote branches on the server you don't yet have, which remote branches you have that have been removed from the server, and multiple local branches that are able to merge automatically with their remote-tracking branch when you run `git pull`.
2412-+It also shows you which remote branches on the server you don't yet have, which remote branches you have that have been removed from the server, and multiple branches that are automatically merged when you run `git pull`.
2401+-It also shows you which remote branches on the server you don't yet have, which remote branches you have that have been removed from the server, and multiple branches that are automatically merged when you run `git pull`.
2402++It also shows you which remote branches on the server you don't yet have, which remote branches you have that have been removed from the server, and multiple local branches that are able to merge automatically with their remote-tracking branch when you run `git pull`.
24132403
2414--==== Renaming and Removing Remotes
2415-+==== Removing and Renaming Remotes
2404+-==== Removing and Renaming Remotes
2405++==== Renaming and Removing Remotes
24162406
2417--You can run `git remote rename` to change a remote's shortname.(((git commands, remote)))
2418-+If you want to rename a reference you can run `git remote rename` to change a remote's shortname.(((git commands, remote)))
2407+-If you want to rename a reference you can run `git remote rename` to change a remote's shortname.(((git commands, remote)))
2408++You can run `git remote rename` to change a remote's shortname.(((git commands, remote)))
24192409 For instance, if you want to rename `pb` to `paul`, you can do so with `git remote rename`:
24202410
2421--[source,console]
2422------
2423--$ git remote rename pb paul
2424--$ git remote
2425--origin
2426--paul
2427------
2428--
2429--It's worth mentioning that this changes all your remote-tracking branch names, too.
2430-+It's worth mentioning that this changes your remote branch names, too.
2411+-It's worth mentioning that this changes your remote branch names, too.
2412++[source,console]
2413++----
2414++$ git remote rename pb paul
2415++$ git remote
2416++origin
2417++paul
2418++----
2419++
2420++It's worth mentioning that this changes all your remote-tracking branch names, too.
24312421 What used to be referenced at `pb/master` is now at `paul/master`.
24322422
2433--If you want to remove a remote for some reason -- you've moved the server or are no longer using a particular mirror, or perhaps a contributor isn't contributing anymore -- you can either use `git remote remove` or `git remote rm`:
2434--
2435--[source,console]
2436------
2437--$ git remote remove paul
2438--$ git remote
2439--origin
2440------
2441--
2442--Once you delete the reference to a remote this way, all remote-tracking branches and configuration settings associated with that remote are also deleted.
2443-+If you want to remove a remote for some reason – you've moved the server or are no longer using a particular mirror, or perhaps a contributor isn't contributing anymore – you can use `git remote rm`:
2444-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/tagging.asc /tmp/book/02-git-basics/sections/tagging.asc.tmp
2445---- ../../git/progit2/progit2/book/02-git-basics/sections/tagging.asc 2020-08-29 09:58:24.048195629 +0900
2446-+++ /tmp/book/02-git-basics/sections/tagging.asc.tmp 2020-10-25 09:24:25.639965914 +0900
2447-@@ -1,299 +1,77 @@
2448--[[_git_tagging]]
2449-+[[r_git_tagging]]
2423+-If you want to remove a remote for some reason – you've moved the server or are no longer using a particular mirror, or perhaps a contributor isn't contributing anymore – you can use `git remote rm`:
2424++If you want to remove a remote for some reason -- you've moved the server or are no longer using a particular mirror, or perhaps a contributor isn't contributing anymore -- you can either use `git remote remove` or `git remote rm`:
2425++
2426++[source,console]
2427++----
2428++$ git remote remove paul
2429++$ git remote
2430++origin
2431++----
2432++
2433++Once you delete the reference to a remote this way, all remote-tracking branches and configuration settings associated with that remote are also deleted.
2434+diff -au /tmp/book/02-git-basics/sections/tagging.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/tagging.asc
2435+--- /tmp/book/02-git-basics/sections/tagging.asc.tmp 2020-10-25 11:05:02.173635460 +0900
2436++++ ../../git/progit2/progit2/book/02-git-basics/sections/tagging.asc 2020-08-29 09:58:24.048195629 +0900
2437+@@ -1,77 +1,299 @@
2438+-[[r_git_tagging]]
2439++[[_git_tagging]]
24502440 === Tagging
24512441
2452--(((tags)))
2453--Like most VCSs, Git has the ability to tag specific points in a repository's history as being important.
2454--Typically, people use this functionality to mark release points (`v1.0`, `v2.0` and so on).
2455--In this section, you'll learn how to list existing tags, how to create and delete tags, and what the different types of tags are.
2456-+Like most VCSs, Git has the ability to tag specific points in history as being important.
2457-+Typically people use this functionality to mark release points (v1.0, and so on).
2458-+In this section, you'll learn how to list the available tags, how to create new tags, and what the different types of tags are.
2442+-Like most VCSs, Git has the ability to tag specific points in history as being important.
2443+-Typically people use this functionality to mark release points (v1.0, and so on).
2444+-In this section, you'll learn how to list the available tags, how to create new tags, and what the different types of tags are.
2445++(((tags)))
2446++Like most VCSs, Git has the ability to tag specific points in a repository's history as being important.
2447++Typically, people use this functionality to mark release points (`v1.0`, `v2.0` and so on).
2448++In this section, you'll learn how to list existing tags, how to create and delete tags, and what the different types of tags are.
24592449
24602450 ==== Listing Your Tags
24612451
2462--Listing the existing tags in Git is straightforward.
2463--Just type `git tag` (with optional `-l` or `--list`):(((git commands, tag)))
2464-+Listing the available tags in Git is straightforward.
2465-+Just type `git tag`:(((git commands, tag)))
2452+-Listing the available tags in Git is straightforward.
2453+-Just type `git tag`:(((git commands, tag)))
2454++Listing the existing tags in Git is straightforward.
2455++Just type `git tag` (with optional `-l` or `--list`):(((git commands, tag)))
24662456
2467--[source,console]
2468------
2469--$ git tag
2470--v1.0
2471--v2.0
2472------
2473-+This command lists the tags in alphabetical order; the order in which they appear has no real importance.
2457+-This command lists the tags in alphabetical order; the order in which they appear has no real importance.
2458++[source,console]
2459++----
2460++$ git tag
2461++v1.0
2462++v2.0
2463++----
24742464
2475--This command lists the tags in alphabetical order; the order in which they are displayed has no real importance.
2476--
2477--You can also search for tags that match a particular pattern.
2478-+You can also search for tags with a particular pattern.
2465+-You can also search for tags with a particular pattern.
2466++This command lists the tags in alphabetical order; the order in which they are displayed has no real importance.
2467++
2468++You can also search for tags that match a particular pattern.
24792469 The Git source repo, for instance, contains more than 500 tags.
2480--If you're interested only in looking at the 1.8.5 series, you can run this:
2481--
2482--[source,console]
2483------
2484--$ git tag -l "v1.8.5*"
2485--v1.8.5
2486--v1.8.5-rc0
2487--v1.8.5-rc1
2488--v1.8.5-rc2
2489--v1.8.5-rc3
2490--v1.8.5.1
2491--v1.8.5.2
2492--v1.8.5.3
2493--v1.8.5.4
2494--v1.8.5.5
2495------
2496--
2497--[NOTE]
2498--.Listing tag wildcards requires `-l` or `--list` option
2499--====
2500--If you want just the entire list of tags, running the command `git tag` implicitly assumes you want a listing and provides one; the use of `-l` or `--list` in this case is optional.
2501--
2502--If, however, you're supplying a wildcard pattern to match tag names, the use of `-l` or `--list` is mandatory.
2503--====
2504-+If you're only interested in looking at the 1.8.5 series, you can run this:
2470+-If you're only interested in looking at the 1.8.5 series, you can run this:
2471++If you're interested only in looking at the 1.8.5 series, you can run this:
2472++
2473++[source,console]
2474++----
2475++$ git tag -l "v1.8.5*"
2476++v1.8.5
2477++v1.8.5-rc0
2478++v1.8.5-rc1
2479++v1.8.5-rc2
2480++v1.8.5-rc3
2481++v1.8.5.1
2482++v1.8.5.2
2483++v1.8.5.3
2484++v1.8.5.4
2485++v1.8.5.5
2486++----
2487++
2488++[NOTE]
2489++.Listing tag wildcards requires `-l` or `--list` option
2490++====
2491++If you want just the entire list of tags, running the command `git tag` implicitly assumes you want a listing and provides one; the use of `-l` or `--list` in this case is optional.
2492++
2493++If, however, you're supplying a wildcard pattern to match tag names, the use of `-l` or `--list` is mandatory.
2494++====
25052495
25062496 ==== Creating Tags
25072497
2508--Git supports two types of tags: _lightweight_ and _annotated_.
2509-+Git uses two main types of tags: lightweight and annotated.
2498+-Git uses two main types of tags: lightweight and annotated.
2499++Git supports two types of tags: _lightweight_ and _annotated_.
25102500
2511--A lightweight tag is very much like a branch that doesn't change -- it's just a pointer to a specific commit.
2512-+A lightweight tag is very much like a branch that doesn't change – it's just a pointer to a specific commit.
2501+-A lightweight tag is very much like a branch that doesn't change – it's just a pointer to a specific commit.
2502++A lightweight tag is very much like a branch that doesn't change -- it's just a pointer to a specific commit.
25132503
25142504 Annotated tags, however, are stored as full objects in the Git database.
25152505 They're checksummed; contain the tagger name, email, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG).
25162506 It's generally recommended that you create annotated tags so you can have all this information; but if you want a temporary tag or for some reason don't want to keep the other information, lightweight tags are available too.
25172507
2518--[[_annotated_tags]]
2508++[[_annotated_tags]]
25192509 ==== Annotated Tags
25202510
2521--(((tags, annotated)))
2511++(((tags, annotated)))
25222512 Creating an annotated tag in Git is simple.
25232513 The easiest way is to specify `-a` when you run the `tag` command:(((git commands, tag)))
25242514
2525--[source,console]
2526------
2527--$ git tag -a v1.4 -m "my version 1.4"
2528--$ git tag
2529--v0.1
2530--v1.3
2531--v1.4
2532------
2533--
2515++[source,console]
2516++----
2517++$ git tag -a v1.4 -m "my version 1.4"
2518++$ git tag
2519++v0.1
2520++v1.3
2521++v1.4
2522++----
2523++
25342524 The `-m` specifies a tagging message, which is stored with the tag.
25352525 If you don't specify a message for an annotated tag, Git launches your editor so you can type it in.
25362526
25372527 You can see the tag data along with the commit that was tagged by using the `git show` command:
25382528
2539--[source,console]
2540------
2541--$ git show v1.4
2542--tag v1.4
2543--Tagger: Ben Straub <ben@straub.cc>
2544--Date: Sat May 3 20:19:12 2014 -0700
2545--
2546--my version 1.4
2547--
2548--commit ca82a6dff817ec66f44342007202690a93763949
2549--Author: Scott Chacon <schacon@gee-mail.com>
2550--Date: Mon Mar 17 21:52:11 2008 -0700
2551--
2552-- Change version number
2553------
2554--
2555- That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information.
2556-
2529++[source,console]
2530++----
2531++$ git show v1.4
2532++tag v1.4
2533++Tagger: Ben Straub <ben@straub.cc>
2534++Date: Sat May 3 20:19:12 2014 -0700
2535++
2536++my version 1.4
2537++
2538++commit ca82a6dff817ec66f44342007202690a93763949
2539++Author: Scott Chacon <schacon@gee-mail.com>
2540++Date: Mon Mar 17 21:52:11 2008 -0700
2541++
2542++ Change version number
2543++----
2544++
2545+ That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information.
2546+
25572547 ==== Lightweight Tags
25582548
2559--(((tags, lightweight)))
2549++(((tags, lightweight)))
25602550 Another way to tag commits is with a lightweight tag.
2561--This is basically the commit checksum stored in a file -- no other information is kept.
2562--To create a lightweight tag, don't supply any of the `-a`, `-s`, or `-m` options, just provide a tag name:
2563--
2564--[source,console]
2565------
2566--$ git tag v1.4-lw
2567--$ git tag
2568--v0.1
2569--v1.3
2570--v1.4
2571--v1.4-lw
2572--v1.5
2573------
2574-+This is basically the commit checksum stored in a file – no other information is kept.
2575-+To create a lightweight tag, don't supply the `-a`, `-s`, or `-m` option:
2551+-This is basically the commit checksum stored in a file – no other information is kept.
2552+-To create a lightweight tag, don't supply the `-a`, `-s`, or `-m` option:
2553++This is basically the commit checksum stored in a file -- no other information is kept.
2554++To create a lightweight tag, don't supply any of the `-a`, `-s`, or `-m` options, just provide a tag name:
2555++
2556++[source,console]
2557++----
2558++$ git tag v1.4-lw
2559++$ git tag
2560++v0.1
2561++v1.3
2562++v1.4
2563++v1.4-lw
2564++v1.5
2565++----
25762566
25772567 This time, if you run `git show` on the tag, you don't see the extra tag information.(((git commands, show)))
25782568 The command just shows the commit:
25792569
2580--[source,console]
2581------
2582--$ git show v1.4-lw
2583--commit ca82a6dff817ec66f44342007202690a93763949
2584--Author: Scott Chacon <schacon@gee-mail.com>
2585--Date: Mon Mar 17 21:52:11 2008 -0700
2586--
2587-- Change version number
2588------
2589--
2570++[source,console]
2571++----
2572++$ git show v1.4-lw
2573++commit ca82a6dff817ec66f44342007202690a93763949
2574++Author: Scott Chacon <schacon@gee-mail.com>
2575++Date: Mon Mar 17 21:52:11 2008 -0700
2576++
2577++ Change version number
2578++----
2579++
25902580 ==== Tagging Later
25912581
25922582 You can also tag commits after you've moved past them.
25932583 Suppose your commit history looks like this:
25942584
2595--[source,console]
2596------
2597--$ git log --pretty=oneline
2598--15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment'
2599--a6b4c97498bd301d84096da251c98a07c7723e65 Create write support
2600--0d52aaab4479697da7686c15f77a3d64d9165190 One more thing
2601--6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment'
2602--0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc Add commit function
2603--4682c3261057305bdd616e23b64b0857d832627b Add todo file
2604--166ae0c4d3f420721acbb115cc33848dfcc2121a Create write support
2605--9fceb02d0ae598e95dc970b74767f19372d61af8 Update rakefile
2606--964f16d36dfccde844893cac5b347e7b3d44abbc Commit the todo
2607--8a5cbc430f1a9c3d00faaeffd07798508422908a Update readme
2608------
2609--
2610--Now, suppose you forgot to tag the project at v1.2, which was at the ``Update rakefile'' commit.
2611-+Now, suppose you forgot to tag the project at v1.2, which was at the ``updated rakefile'' commit.
2585+-Now, suppose you forgot to tag the project at v1.2, which was at the ``updated rakefile'' commit.
2586++[source,console]
2587++----
2588++$ git log --pretty=oneline
2589++15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment'
2590++a6b4c97498bd301d84096da251c98a07c7723e65 Create write support
2591++0d52aaab4479697da7686c15f77a3d64d9165190 One more thing
2592++6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment'
2593++0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc Add commit function
2594++4682c3261057305bdd616e23b64b0857d832627b Add todo file
2595++166ae0c4d3f420721acbb115cc33848dfcc2121a Create write support
2596++9fceb02d0ae598e95dc970b74767f19372d61af8 Update rakefile
2597++964f16d36dfccde844893cac5b347e7b3d44abbc Commit the todo
2598++8a5cbc430f1a9c3d00faaeffd07798508422908a Update readme
2599++----
2600++
2601++Now, suppose you forgot to tag the project at v1.2, which was at the ``Update rakefile'' commit.
26122602 You can add it after the fact.
26132603 To tag that commit, you specify the commit checksum (or part of it) at the end of the command:
26142604
2615--[source,console]
2616------
2617--$ git tag -a v1.2 9fceb02
2618------
2619--
2605++[source,console]
2606++----
2607++$ git tag -a v1.2 9fceb02
2608++----
2609++
26202610 You can see that you've tagged the commit:(((git commands, tag)))
26212611
2622--[source,console]
2623------
2624--$ git tag
2625--v0.1
2626--v1.2
2627--v1.3
2628--v1.4
2629--v1.4-lw
2630--v1.5
2631--
2632--$ git show v1.2
2633--tag v1.2
2634--Tagger: Scott Chacon <schacon@gee-mail.com>
2635--Date: Mon Feb 9 15:32:16 2009 -0800
2636--
2637--version 1.2
2638--commit 9fceb02d0ae598e95dc970b74767f19372d61af8
2639--Author: Magnus Chacon <mchacon@gee-mail.com>
2640--Date: Sun Apr 27 20:43:35 2008 -0700
2641--
2642-- Update rakefile
2643--...
2644------
2645--
2646--[[_sharing_tags]]
2612++[source,console]
2613++----
2614++$ git tag
2615++v0.1
2616++v1.2
2617++v1.3
2618++v1.4
2619++v1.4-lw
2620++v1.5
2621++
2622++$ git show v1.2
2623++tag v1.2
2624++Tagger: Scott Chacon <schacon@gee-mail.com>
2625++Date: Mon Feb 9 15:32:16 2009 -0800
2626++
2627++version 1.2
2628++commit 9fceb02d0ae598e95dc970b74767f19372d61af8
2629++Author: Magnus Chacon <mchacon@gee-mail.com>
2630++Date: Sun Apr 27 20:43:35 2008 -0700
2631++
2632++ Update rakefile
2633++...
2634++----
2635++
2636++[[_sharing_tags]]
26472637 ==== Sharing Tags
26482638
26492639 By default, the `git push` command doesn't transfer tags to remote servers.(((git commands, push)))
26502640 You will have to explicitly push tags to a shared server after you have created them.
2651--This process is just like sharing remote branches -- you can run `git push origin <tagname>`.
2652--
2653--[source,console]
2654------
2655--$ git push origin v1.5
2656--Counting objects: 14, done.
2657--Delta compression using up to 8 threads.
2658--Compressing objects: 100% (12/12), done.
2659--Writing objects: 100% (14/14), 2.05 KiB | 0 bytes/s, done.
2660--Total 14 (delta 3), reused 0 (delta 0)
2661--To git@github.com:schacon/simplegit.git
2662-- * [new tag] v1.5 -> v1.5
2663------
2664-+This process is just like sharing remote branches – you can run `git push origin [tagname]`.
2641+-This process is just like sharing remote branches – you can run `git push origin [tagname]`.
2642++This process is just like sharing remote branches -- you can run `git push origin <tagname>`.
2643++
2644++[source,console]
2645++----
2646++$ git push origin v1.5
2647++Counting objects: 14, done.
2648++Delta compression using up to 8 threads.
2649++Compressing objects: 100% (12/12), done.
2650++Writing objects: 100% (14/14), 2.05 KiB | 0 bytes/s, done.
2651++Total 14 (delta 3), reused 0 (delta 0)
2652++To git@github.com:schacon/simplegit.git
2653++ * [new tag] v1.5 -> v1.5
2654++----
26652655
26662656 If you have a lot of tags that you want to push up at once, you can also use the `--tags` option to the `git push` command.
26672657 This will transfer all of your tags to the remote server that are not already there.
26682658
2669--[source,console]
2670------
2671--$ git push origin --tags
2672--Counting objects: 1, done.
2673--Writing objects: 100% (1/1), 160 bytes | 0 bytes/s, done.
2674--Total 1 (delta 0), reused 0 (delta 0)
2675--To git@github.com:schacon/simplegit.git
2676-- * [new tag] v1.4 -> v1.4
2677-- * [new tag] v1.4-lw -> v1.4-lw
2678------
2679--
2659++[source,console]
2660++----
2661++$ git push origin --tags
2662++Counting objects: 1, done.
2663++Writing objects: 100% (1/1), 160 bytes | 0 bytes/s, done.
2664++Total 1 (delta 0), reused 0 (delta 0)
2665++To git@github.com:schacon/simplegit.git
2666++ * [new tag] v1.4 -> v1.4
2667++ * [new tag] v1.4-lw -> v1.4-lw
2668++----
2669++
26802670 Now, when someone else clones or pulls from your repository, they will get all your tags as well.
26812671
2682--[NOTE]
2683--.`git push` pushes both types of tags
2684--====
2685--`git push <remote> --tags` will push both lightweight and annotated tags.
2686--There is currently no option to push only lightweight tags, but if you use `git push <remote> --follow-tags` only annotated tags will be pushed to the remote.
2687--====
2688--
2689--==== Deleting Tags
2690--
2691--To delete a tag on your local repository, you can use `git tag -d <tagname>`.
2692--For example, we could remove our lightweight tag above as follows:
2693--
2694--[source,console]
2695------
2696--$ git tag -d v1.4-lw
2697--Deleted tag 'v1.4-lw' (was e7d5add)
2698------
2699--
2700--Note that this does not remove the tag from any remote servers.
2701--There are two common variations for deleting a tag from a remote server.
2702--
2703--The first variation is `git push <remote> :refs/tags/<tagname>`:
2704--
2705--[source,console]
2706------
2707--$ git push origin :refs/tags/v1.4-lw
2708--To /git@github.com:schacon/simplegit.git
2709-- - [deleted] v1.4-lw
2710------
2711--
2712--The way to interpret the above is to read it as the null value before the colon is being pushed to the remote tag name, effectively deleting it.
2713--
2714--The second (and more intuitive) way to delete a remote tag is with:
2715--
2716--[source,console]
2717------
2718--$ git push origin --delete <tagname>
2719------
2720--
2672++[NOTE]
2673++.`git push` pushes both types of tags
2674++====
2675++`git push <remote> --tags` will push both lightweight and annotated tags.
2676++There is currently no option to push only lightweight tags, but if you use `git push <remote> --follow-tags` only annotated tags will be pushed to the remote.
2677++====
2678++
2679++==== Deleting Tags
2680++
2681++To delete a tag on your local repository, you can use `git tag -d <tagname>`.
2682++For example, we could remove our lightweight tag above as follows:
2683++
2684++[source,console]
2685++----
2686++$ git tag -d v1.4-lw
2687++Deleted tag 'v1.4-lw' (was e7d5add)
2688++----
2689++
2690++Note that this does not remove the tag from any remote servers.
2691++There are two common variations for deleting a tag from a remote server.
2692++
2693++The first variation is `git push <remote> :refs/tags/<tagname>`:
2694++
2695++[source,console]
2696++----
2697++$ git push origin :refs/tags/v1.4-lw
2698++To /git@github.com:schacon/simplegit.git
2699++ - [deleted] v1.4-lw
2700++----
2701++
2702++The way to interpret the above is to read it as the null value before the colon is being pushed to the remote tag name, effectively deleting it.
2703++
2704++The second (and more intuitive) way to delete a remote tag is with:
2705++
2706++[source,console]
2707++----
2708++$ git push origin --delete <tagname>
2709++----
2710++
27212711 ==== Checking out Tags
27222712
2723--If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in ``detached HEAD'' state, which has some ill side effects:
2724--
2725--[source,console]
2726------
2727--$ git checkout v2.0.0
2728--Note: switching to 'v2.0.0'.
2729--
2730--You are in 'detached HEAD' state. You can look around, make experimental
2731--changes and commit them, and you can discard any commits you make in this
2732--state without impacting any branches by performing another checkout.
2733--
2734--If you want to create a new branch to retain commits you create, you may
2735--do so (now or later) by using -c with the switch command. Example:
2736--
2737-- git switch -c <new-branch-name>
2738--
2739--Or undo this operation with:
2740--
2741-- git switch -
2742--
2743--Turn off this advice by setting config variable advice.detachedHead to false
2744--
2745--HEAD is now at 99ada87... Merge pull request #89 from schacon/appendix-final
2746--
2747--$ git checkout v2.0-beta-0.1
2748--Previous HEAD position was 99ada87... Merge pull request #89 from schacon/appendix-final
2749--HEAD is now at df3f601... Add atlas.json and cover image
2750------
2751--
2752--In ``detached HEAD'' state, if you make changes and then create a commit, the tag will stay the same, but your new commit won't belong to any branch and will be unreachable, except by the exact commit hash.
2753--Thus, if you need to make changes -- say you're fixing a bug on an older version, for instance -- you will generally want to create a branch:
2754--
2755--[source,console]
2756------
2757--$ git checkout -b version2 v2.0.0
2758--Switched to a new branch 'version2'
2759------
2760-+You can't really check out a tag in Git, since they can't be moved around.
2761-+If you want to put a version of your repository in your working directory that looks like a specific tag, you can create a new branch at a specific tag with `git checkout -b [branchname] [tagname]`:
2762-
2763--If you do this and make a commit, your `version2` branch will be slightly different than your `v2.0.0` tag since it will move forward with your new changes, so do be careful.
2764-+Of course if you do this and do a commit, your `version2` branch will be slightly different than your `v2.0.0` tag since it will move forward with your new changes, so do be careful.
2765-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/undoing.asc /tmp/book/02-git-basics/sections/undoing.asc.tmp
2766---- ../../git/progit2/progit2/book/02-git-basics/sections/undoing.asc 2020-10-18 09:42:35.779991668 +0900
2767-+++ /tmp/book/02-git-basics/sections/undoing.asc.tmp 2020-10-25 09:24:25.644966150 +0900
2713+-You can't really check out a tag in Git, since they can't be moved around.
2714+-If you want to put a version of your repository in your working directory that looks like a specific tag, you can create a new branch at a specific tag with `git checkout -b [branchname] [tagname]`:
2715++If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in ``detached HEAD'' state, which has some ill side effects:
2716++
2717++[source,console]
2718++----
2719++$ git checkout v2.0.0
2720++Note: switching to 'v2.0.0'.
2721++
2722++You are in 'detached HEAD' state. You can look around, make experimental
2723++changes and commit them, and you can discard any commits you make in this
2724++state without impacting any branches by performing another checkout.
2725++
2726++If you want to create a new branch to retain commits you create, you may
2727++do so (now or later) by using -c with the switch command. Example:
2728++
2729++ git switch -c <new-branch-name>
2730++
2731++Or undo this operation with:
2732++
2733++ git switch -
2734++
2735++Turn off this advice by setting config variable advice.detachedHead to false
2736++
2737++HEAD is now at 99ada87... Merge pull request #89 from schacon/appendix-final
2738++
2739++$ git checkout v2.0-beta-0.1
2740++Previous HEAD position was 99ada87... Merge pull request #89 from schacon/appendix-final
2741++HEAD is now at df3f601... Add atlas.json and cover image
2742++----
2743++
2744++In ``detached HEAD'' state, if you make changes and then create a commit, the tag will stay the same, but your new commit won't belong to any branch and will be unreachable, except by the exact commit hash.
2745++Thus, if you need to make changes -- say you're fixing a bug on an older version, for instance -- you will generally want to create a branch:
2746++
2747++[source,console]
2748++----
2749++$ git checkout -b version2 v2.0.0
2750++Switched to a new branch 'version2'
2751++----
2752+
2753+-Of course if you do this and do a commit, your `version2` branch will be slightly different than your `v2.0.0` tag since it will move forward with your new changes, so do be careful.
2754++If you do this and make a commit, your `version2` branch will be slightly different than your `v2.0.0` tag since it will move forward with your new changes, so do be careful.
2755+diff -au /tmp/book/02-git-basics/sections/undoing.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/undoing.asc
2756+--- /tmp/book/02-git-basics/sections/undoing.asc.tmp 2020-10-25 11:05:02.179635797 +0900
2757++++ ../../git/progit2/progit2/book/02-git-basics/sections/undoing.asc 2020-10-18 09:42:35.779991668 +0900
27682758 @@ -1,4 +1,4 @@
2769--[[_undoing]]
2770-+[[r_undoing]]
2759+-[[r_undoing]]
2760++[[_undoing]]
27712761 === Undoing Things
27722762
27732763 At any stage, you may want to undo something.
2774-@@ -7,12 +7,7 @@
2764+@@ -7,7 +7,12 @@
27752765 This is one of the few areas in Git where you may lose some work if you do it wrong.
27762766
27772767 One of the common undos takes place when you commit too early and possibly forget to add some files, or you mess up your commit message.
2778--If you want to redo that commit, make the additional changes you forgot, stage them, and commit again using the `--amend` option:
2779--
2780--[source,console]
2781------
2782--$ git commit --amend
2783------
2784-+If you want to try that commit again, you can run commit with the `--amend` option:
2768+-If you want to try that commit again, you can run commit with the `--amend` option:
2769++If you want to redo that commit, make the additional changes you forgot, stage them, and commit again using the `--amend` option:
2770++
2771++[source,console]
2772++----
2773++$ git commit --amend
2774++----
27852775
27862776 This command takes your staging area and uses it for the commit.
27872777 If you've made no changes since your last commit (for instance, you run this command immediately after your previous commit), then your snapshot will look exactly the same, and all you'll change is your commit message.
2788-@@ -22,214 +17,50 @@
2778+@@ -17,50 +22,214 @@
27892779
27902780 As an example, if you commit and then realize you forgot to stage the changes in a file you wanted to add to this commit, you can do something like this:
27912781
2792--[source,console]
2793------
2794--$ git commit -m 'Initial commit'
2795--$ git add forgotten_file
2796--$ git commit --amend
2797------
2798--
2799--You end up with a single commit -- the second commit replaces the results of the first.
2800--
2801--[NOTE]
2802--====
2803--It's important to understand that when you're amending your last commit, you're not so much fixing it as _replacing_ it entirely with a new, improved commit that pushes the old commit out of the way and puts the new commit in its place.
2804--Effectively, it's as if the previous commit never happened, and it won't show up in your repository history.
2805--
2806--The obvious value to amending commits is to make minor improvements to your last commit, without cluttering your repository history with commit messages of the form, ``Oops, forgot to add a file'' or ``Darn, fixing a typo in last commit''.
2807--====
2808--
2809--[NOTE]
2810--====
2811--Only amend commits that are still local and have not been pushed somewhere.
2812--Amending previously pushed commits and force pushing the branch will cause problems for your collaborators.
2813--For more on what happens when you do this and how to recover if you're on the receiving end read <<_rebase_peril>>.
2814--====
2815-+You end up with a single commit – the second commit replaces the results of the first.
2816-
2817--[[_unstaging]]
2782+-You end up with a single commit – the second commit replaces the results of the first.
2783++[source,console]
2784++----
2785++$ git commit -m 'Initial commit'
2786++$ git add forgotten_file
2787++$ git commit --amend
2788++----
2789++
2790++You end up with a single commit -- the second commit replaces the results of the first.
2791++
2792++[NOTE]
2793++====
2794++It's important to understand that when you're amending your last commit, you're not so much fixing it as _replacing_ it entirely with a new, improved commit that pushes the old commit out of the way and puts the new commit in its place.
2795++Effectively, it's as if the previous commit never happened, and it won't show up in your repository history.
2796++
2797++The obvious value to amending commits is to make minor improvements to your last commit, without cluttering your repository history with commit messages of the form, ``Oops, forgot to add a file'' or ``Darn, fixing a typo in last commit''.
2798++====
2799++
2800++[NOTE]
2801++====
2802++Only amend commits that are still local and have not been pushed somewhere.
2803++Amending previously pushed commits and force pushing the branch will cause problems for your collaborators.
2804++For more on what happens when you do this and how to recover if you're on the receiving end read <<_rebase_peril>>.
2805++====
2806+
2807++[[_unstaging]]
28182808 ==== Unstaging a Staged File
28192809
2820--The next two sections demonstrate how to work with your staging area and working directory changes.
2821-+The next two sections demonstrate how to wrangle your staging area and working directory changes.
2810+-The next two sections demonstrate how to wrangle your staging area and working directory changes.
2811++The next two sections demonstrate how to work with your staging area and working directory changes.
28222812 The nice part is that the command you use to determine the state of those two areas also reminds you how to undo changes to them.
28232813 For example, let's say you've changed two files and want to commit them as two separate changes, but you accidentally type `git add *` and stage them both.
28242814 How can you unstage one of the two?
28252815 The `git status` command reminds you:
28262816
2827--[source,console]
2828------
2829--$ git add *
2830--$ git status
2831--On branch master
2832--Changes to be committed:
2833-- (use "git reset HEAD <file>..." to unstage)
2834--
2835-- renamed: README.md -> README
2836-- modified: CONTRIBUTING.md
2837------
2838--
2817++[source,console]
2818++----
2819++$ git add *
2820++$ git status
2821++On branch master
2822++Changes to be committed:
2823++ (use "git reset HEAD <file>..." to unstage)
2824++
2825++ renamed: README.md -> README
2826++ modified: CONTRIBUTING.md
2827++----
2828++
28392829 Right below the ``Changes to be committed'' text, it says use `git reset HEAD <file>...` to unstage.
28402830 So, let's use that advice to unstage the `CONTRIBUTING.md` file:
28412831
2842--[source,console]
2843------
2844--$ git reset HEAD CONTRIBUTING.md
2845--Unstaged changes after reset:
2846--M CONTRIBUTING.md
2847--$ git status
2848--On branch master
2849--Changes to be committed:
2850-- (use "git reset HEAD <file>..." to unstage)
2851--
2852-- renamed: README.md -> README
2853--
2854--Changes not staged for commit:
2855-- (use "git add <file>..." to update what will be committed)
2856-- (use "git checkout -- <file>..." to discard changes in working directory)
2857--
2858-- modified: CONTRIBUTING.md
2859------
2860--
2832++[source,console]
2833++----
2834++$ git reset HEAD CONTRIBUTING.md
2835++Unstaged changes after reset:
2836++M CONTRIBUTING.md
2837++$ git status
2838++On branch master
2839++Changes to be committed:
2840++ (use "git reset HEAD <file>..." to unstage)
2841++
2842++ renamed: README.md -> README
2843++
2844++Changes not staged for commit:
2845++ (use "git add <file>..." to update what will be committed)
2846++ (use "git checkout -- <file>..." to discard changes in working directory)
2847++
2848++ modified: CONTRIBUTING.md
2849++----
2850++
28612851 The command is a bit strange, but it works.
28622852 The `CONTRIBUTING.md` file is modified but once again unstaged.
28632853
2864--[NOTE]
2854++[NOTE]
28652855 =====
2866--It's true that `git reset` can be a dangerous command, especially if you provide the `--hard` flag.
2867--However, in the scenario described above, the file in your working directory is not touched, so it's relatively safe.
2868-+While `git reset` _can_ be a dangerous command if you call it with `--hard`, in this instance the file in your working directory is not touched.
2869-+Calling `git reset` without an option is not dangerous - it only touches your staging area.
2856+-While `git reset` _can_ be a dangerous command if you call it with `--hard`, in this instance the file in your working directory is not touched.
2857+-Calling `git reset` without an option is not dangerous - it only touches your staging area.
2858++It's true that `git reset` can be a dangerous command, especially if you provide the `--hard` flag.
2859++However, in the scenario described above, the file in your working directory is not touched, so it's relatively safe.
28702860 =====
28712861
28722862 For now this magic invocation is all you need to know about the `git reset` command.
2873--We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<ch07-git-tools#_git_reset>>.
2874-+We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<ch07-git-tools#r_git_reset>>.
2863+-We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<ch07-git-tools#r_git_reset>>.
2864++We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<ch07-git-tools#_git_reset>>.
28752865
28762866 ==== Unmodifying a Modified File
28772867
28782868 What if you realize that you don't want to keep your changes to the `CONTRIBUTING.md` file?
2879--How can you easily unmodify it -- revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
2880-+How can you easily unmodify it – revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
2869+-How can you easily unmodify it – revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
2870++How can you easily unmodify it -- revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
28812871 Luckily, `git status` tells you how to do that, too.
28822872 In the last example output, the unstaged area looks like this:
28832873
2884--[source,console]
2885------
2886--Changes not staged for commit:
2887-- (use "git add <file>..." to update what will be committed)
2888-- (use "git checkout -- <file>..." to discard changes in working directory)
2889--
2890-- modified: CONTRIBUTING.md
2891------
2892--
2874++[source,console]
2875++----
2876++Changes not staged for commit:
2877++ (use "git add <file>..." to update what will be committed)
2878++ (use "git checkout -- <file>..." to discard changes in working directory)
2879++
2880++ modified: CONTRIBUTING.md
2881++----
2882++
28932883 It tells you pretty explicitly how to discard the changes you've made.
28942884 Let's do what it says:
28952885
2896--[source,console]
2897------
2898--$ git checkout -- CONTRIBUTING.md
2899--$ git status
2900--On branch master
2901--Changes to be committed:
2902-- (use "git reset HEAD <file>..." to unstage)
2903--
2904-- renamed: README.md -> README
2905--
2906------
2907--
2886++[source,console]
2887++----
2888++$ git checkout -- CONTRIBUTING.md
2889++$ git status
2890++On branch master
2891++Changes to be committed:
2892++ (use "git reset HEAD <file>..." to unstage)
2893++
2894++ renamed: README.md -> README
2895++
2896++----
2897++
29082898 You can see that the changes have been reverted.
29092899
2910--[IMPORTANT]
2900++[IMPORTANT]
29112901 =====
29122902 It's important to understand that `git checkout -- <file>` is a dangerous command.
2913--Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
2914--Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
2915-+Any changes you made to that file are gone – you just copied another file over it.
2916-+Don't ever use this command unless you absolutely know that you don't want the file.
2903+-Any changes you made to that file are gone – you just copied another file over it.
2904+-Don't ever use this command unless you absolutely know that you don't want the file.
2905++Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
2906++Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
29172907 =====
29182908
29192909 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 <<ch03-git-branching#ch03-git-branching>>; these are generally better ways to go.
29202910
29212911 Remember, anything that is _committed_ in Git can almost always be recovered.
2922--Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<ch10-git-internals#_data_recovery>> for data recovery).
2923-+Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<ch10-git-internals#r_data_recovery>> for data recovery).
2912+-Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<ch10-git-internals#r_data_recovery>> for data recovery).
2913++Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<ch10-git-internals#_data_recovery>> for data recovery).
29242914 However, anything you lose that was never committed is likely never to be seen again.
2925--
2926--[[undoing_git_restore]]
2927--==== Undoing things with git restore
2928--
2929--Git version 2.25.0 introduced a new command: `git restore`.
2930--It's basically an alternative to `git reset` which we just covered.
2931--From Git version 2.25.0 onwards, Git will use `git restore` instead of `git reset` for many undo operations.
2932--
2933--Let's retrace our steps, and undo things with `git restore` instead of `git reset`.
2934--
2935--===== Unstaging a Staged File with git restore
2936--
2937--The next two sections demonstrate how to work with your staging area and working directory changes with `git restore`.
2938--The nice part is that the command you use to determine the state of those two areas also reminds you how to undo changes to them.
2939--For example, let's say you've changed two files and want to commit them as two separate changes, but you accidentally type `git add *` and stage them both.
2940--How can you unstage one of the two?
2941--The `git status` command reminds you:
2942--
2943--[source,console]
2944------
2945--$ git add *
2946--$ git status
2947--On branch master
2948--Changes to be committed:
2949-- (use "git restore --staged <file>..." to unstage)
2950-- modified: CONTRIBUTING.md
2951-- renamed: README.md -> README
2952--
2953------
2954--
2955--Right below the ``Changes to be committed'' text, it says use `git restore --staged <file>...` to unstage.
2956--So, let's use that advice to unstage the `CONTRIBUTING.md` file:
2957--
2958--[source,console]
2959------
2960--$ git restore --staged CONTRIBUTING.md
2961--$ git status
2962--On branch master
2963--Changes to be committed:
2964-- (use "git restore --staged <file>..." to unstage)
2965-- renamed: README.md -> README
2966--
2967--Changes not staged for commit:
2968-- (use "git add <file>..." to update what will be committed)
2969-- (use "git restore <file>..." to discard changes in working directory)
2970-- modified: CONTRIBUTING.md
2971--
2972------
2973--
2974--The `CONTRIBUTING.md` file is modified but once again unstaged.
2975--
2976--===== Unmodifying a Modified File with git restore
2977--
2978--What if you realize that you don't want to keep your changes to the `CONTRIBUTING.md` file?
2979--How can you easily unmodify it -- revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
2980--Luckily, `git status` tells you how to do that, too.
2981--In the last example output, the unstaged area looks like this:
2982--
2983--[source,console]
2984------
2985--Changes not staged for commit:
2986-- (use "git add <file>..." to update what will be committed)
2987-- (use "git restore <file>..." to discard changes in working directory)
2988-- modified: CONTRIBUTING.md
2989--
2990------
2991--
2992--It tells you pretty explicitly how to discard the changes you've made.
2993--Let's do what it says:
2994--
2995--[source,console]
2996------
2997--$ git restore CONTRIBUTING.md
2998--$ git status
2999--On branch master
3000--Changes to be committed:
3001-- (use "git restore --staged <file>..." to unstage)
3002-- renamed: README.md -> README
3003--
3004------
3005--
3006--[IMPORTANT]
3007--=====
3008--It's important to understand that `git restore <file>` is a dangerous command.
3009--Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
3010--Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
3011--=====
3012-diff -au ../../git/progit2/progit2/book/02-git-basics/sections/viewing-history.asc /tmp/book/02-git-basics/sections/viewing-history.asc.tmp
3013---- ../../git/progit2/progit2/book/02-git-basics/sections/viewing-history.asc 2020-09-26 08:56:07.950296410 +0900
3014-+++ /tmp/book/02-git-basics/sections/viewing-history.asc.tmp 2020-10-25 09:24:25.649966386 +0900
3015-@@ -1,213 +1,76 @@
3016--[[_viewing_history]]
3017-+[[r_viewing_history]]
2915++
2916++[[undoing_git_restore]]
2917++==== Undoing things with git restore
2918++
2919++Git version 2.25.0 introduced a new command: `git restore`.
2920++It's basically an alternative to `git reset` which we just covered.
2921++From Git version 2.25.0 onwards, Git will use `git restore` instead of `git reset` for many undo operations.
2922++
2923++Let's retrace our steps, and undo things with `git restore` instead of `git reset`.
2924++
2925++===== Unstaging a Staged File with git restore
2926++
2927++The next two sections demonstrate how to work with your staging area and working directory changes with `git restore`.
2928++The nice part is that the command you use to determine the state of those two areas also reminds you how to undo changes to them.
2929++For example, let's say you've changed two files and want to commit them as two separate changes, but you accidentally type `git add *` and stage them both.
2930++How can you unstage one of the two?
2931++The `git status` command reminds you:
2932++
2933++[source,console]
2934++----
2935++$ git add *
2936++$ git status
2937++On branch master
2938++Changes to be committed:
2939++ (use "git restore --staged <file>..." to unstage)
2940++ modified: CONTRIBUTING.md
2941++ renamed: README.md -> README
2942++
2943++----
2944++
2945++Right below the ``Changes to be committed'' text, it says use `git restore --staged <file>...` to unstage.
2946++So, let's use that advice to unstage the `CONTRIBUTING.md` file:
2947++
2948++[source,console]
2949++----
2950++$ git restore --staged CONTRIBUTING.md
2951++$ git status
2952++On branch master
2953++Changes to be committed:
2954++ (use "git restore --staged <file>..." to unstage)
2955++ renamed: README.md -> README
2956++
2957++Changes not staged for commit:
2958++ (use "git add <file>..." to update what will be committed)
2959++ (use "git restore <file>..." to discard changes in working directory)
2960++ modified: CONTRIBUTING.md
2961++
2962++----
2963++
2964++The `CONTRIBUTING.md` file is modified but once again unstaged.
2965++
2966++===== Unmodifying a Modified File with git restore
2967++
2968++What if you realize that you don't want to keep your changes to the `CONTRIBUTING.md` file?
2969++How can you easily unmodify it -- revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)?
2970++Luckily, `git status` tells you how to do that, too.
2971++In the last example output, the unstaged area looks like this:
2972++
2973++[source,console]
2974++----
2975++Changes not staged for commit:
2976++ (use "git add <file>..." to update what will be committed)
2977++ (use "git restore <file>..." to discard changes in working directory)
2978++ modified: CONTRIBUTING.md
2979++
2980++----
2981++
2982++It tells you pretty explicitly how to discard the changes you've made.
2983++Let's do what it says:
2984++
2985++[source,console]
2986++----
2987++$ git restore CONTRIBUTING.md
2988++$ git status
2989++On branch master
2990++Changes to be committed:
2991++ (use "git restore --staged <file>..." to unstage)
2992++ renamed: README.md -> README
2993++
2994++----
2995++
2996++[IMPORTANT]
2997++=====
2998++It's important to understand that `git restore <file>` is a dangerous command.
2999++Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
3000++Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
3001++=====
3002+diff -au /tmp/book/02-git-basics/sections/viewing-history.asc.tmp ../../git/progit2/progit2/book/02-git-basics/sections/viewing-history.asc
3003+--- /tmp/book/02-git-basics/sections/viewing-history.asc.tmp 2020-10-25 11:05:02.185636135 +0900
3004++++ ../../git/progit2/progit2/book/02-git-basics/sections/viewing-history.asc 2020-09-26 08:56:07.950296410 +0900
3005+@@ -1,76 +1,213 @@
3006+-[[r_viewing_history]]
3007++[[_viewing_history]]
30183008 === Viewing the Commit History
30193009
30203010 After you have created several commits, or if you have cloned a repository with an existing commit history, you'll probably want to look back to see what has happened.
30213011 The most basic and powerful tool to do this is the `git log` command.
30223012
30233013 These examples use a very simple project called ``simplegit''.
3024--To get the project, run:
3025--
3026--[source,console]
3027------
3028--$ git clone https://github.com/schacon/simplegit-progit
3029------
3030-+To get the project, run
3014+-To get the project, run
3015++To get the project, run:
3016++
3017++[source,console]
3018++----
3019++$ git clone https://github.com/schacon/simplegit-progit
3020++----
30313021
30323022 When you run `git log` in this project, you should get output that looks something like this:(((git commands, log)))
30333023
3034--[source,console]
3035------
3036--$ git log
3037--commit ca82a6dff817ec66f44342007202690a93763949
3038--Author: Scott Chacon <schacon@gee-mail.com>
3039--Date: Mon Mar 17 21:52:11 2008 -0700
3040--
3041-- Change version number
3042--
3043--commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3044--Author: Scott Chacon <schacon@gee-mail.com>
3045--Date: Sat Mar 15 16:40:33 2008 -0700
3046--
3047-- Remove unnecessary test
3048--
3049--commit a11bef06a3f659402fe7563abf99ad00de2209e6
3050--Author: Scott Chacon <schacon@gee-mail.com>
3051--Date: Sat Mar 15 10:31:28 2008 -0700
3052--
3053-- Initial commit
3054------
3055--
3056--By default, with no arguments, `git log` lists the commits made in that repository in reverse chronological order; that is, the most recent commits show up first.
3057-+By default, with no arguments, `git log` lists the commits made in that repository in reverse chronological order – that is, the most recent commits show up first.
3024+-By default, with no arguments, `git log` lists the commits made in that repository in reverse chronological order – that is, the most recent commits show up first.
3025++[source,console]
3026++----
3027++$ git log
3028++commit ca82a6dff817ec66f44342007202690a93763949
3029++Author: Scott Chacon <schacon@gee-mail.com>
3030++Date: Mon Mar 17 21:52:11 2008 -0700
3031++
3032++ Change version number
3033++
3034++commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3035++Author: Scott Chacon <schacon@gee-mail.com>
3036++Date: Sat Mar 15 16:40:33 2008 -0700
3037++
3038++ Remove unnecessary test
3039++
3040++commit a11bef06a3f659402fe7563abf99ad00de2209e6
3041++Author: Scott Chacon <schacon@gee-mail.com>
3042++Date: Sat Mar 15 10:31:28 2008 -0700
3043++
3044++ Initial commit
3045++----
3046++
3047++By default, with no arguments, `git log` lists the commits made in that repository in reverse chronological order; that is, the most recent commits show up first.
30583048 As you can see, this command lists each commit with its SHA-1 checksum, the author's name and email, the date written, and the commit message.
30593049
30603050 A huge number and variety of options to the `git log` command are available to show you exactly what you're looking for.
30613051 Here, we'll show you some of the most popular.
30623052
3063--One of the more helpful options is `-p` or `--patch`, which shows the difference (the _patch_ output) introduced in each commit.
3064--You can also limit the number of log entries displayed, such as using `-2` to show only the last two entries.
3065--
3066--[source,console]
3067------
3068--$ git log -p -2
3069--commit ca82a6dff817ec66f44342007202690a93763949
3070--Author: Scott Chacon <schacon@gee-mail.com>
3071--Date: Mon Mar 17 21:52:11 2008 -0700
3072--
3073-- Change version number
3074--
3075--diff --git a/Rakefile b/Rakefile
3076--index a874b73..8f94139 100644
3077----- a/Rakefile
3078--+++ b/Rakefile
3079--@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
3080-- spec = Gem::Specification.new do |s|
3081-- s.platform = Gem::Platform::RUBY
3082-- s.name = "simplegit"
3083--- s.version = "0.1.0"
3084--+ s.version = "0.1.1"
3085-- s.author = "Scott Chacon"
3086-- s.email = "schacon@gee-mail.com"
3087-- s.summary = "A simple gem for using Git in Ruby code."
3088--
3089--commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3090--Author: Scott Chacon <schacon@gee-mail.com>
3091--Date: Sat Mar 15 16:40:33 2008 -0700
3092--
3093-- Remove unnecessary test
3094--
3095--diff --git a/lib/simplegit.rb b/lib/simplegit.rb
3096--index a0a60ae..47c6340 100644
3097----- a/lib/simplegit.rb
3098--+++ b/lib/simplegit.rb
3099--@@ -18,8 +18,3 @@ class SimpleGit
3100-- end
3101--
3102-- end
3103---
3104---if $0 == __FILE__
3105--- git = SimpleGit.new
3106--- puts git.show
3107---end
3108------
3109-+One of the more helpful options is `-p`, which shows the difference introduced in each commit.
3110-+You can also use `-2`, which limits the output to only the last two entries:
3053+-One of the more helpful options is `-p`, which shows the difference introduced in each commit.
3054+-You can also use `-2`, which limits the output to only the last two entries:
3055++One of the more helpful options is `-p` or `--patch`, which shows the difference (the _patch_ output) introduced in each commit.
3056++You can also limit the number of log entries displayed, such as using `-2` to show only the last two entries.
3057++
3058++[source,console]
3059++----
3060++$ git log -p -2
3061++commit ca82a6dff817ec66f44342007202690a93763949
3062++Author: Scott Chacon <schacon@gee-mail.com>
3063++Date: Mon Mar 17 21:52:11 2008 -0700
3064++
3065++ Change version number
3066++
3067++diff --git a/Rakefile b/Rakefile
3068++index a874b73..8f94139 100644
3069++--- a/Rakefile
3070+++++ b/Rakefile
3071++@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
3072++ spec = Gem::Specification.new do |s|
3073++ s.platform = Gem::Platform::RUBY
3074++ s.name = "simplegit"
3075++- s.version = "0.1.0"
3076+++ s.version = "0.1.1"
3077++ s.author = "Scott Chacon"
3078++ s.email = "schacon@gee-mail.com"
3079++ s.summary = "A simple gem for using Git in Ruby code."
3080++
3081++commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3082++Author: Scott Chacon <schacon@gee-mail.com>
3083++Date: Sat Mar 15 16:40:33 2008 -0700
3084++
3085++ Remove unnecessary test
3086++
3087++diff --git a/lib/simplegit.rb b/lib/simplegit.rb
3088++index a0a60ae..47c6340 100644
3089++--- a/lib/simplegit.rb
3090+++++ b/lib/simplegit.rb
3091++@@ -18,8 +18,3 @@ class SimpleGit
3092++ end
3093++
3094++ end
3095++-
3096++-if $0 == __FILE__
3097++- git = SimpleGit.new
3098++- puts git.show
3099++-end
3100++----
31113101
31123102 This option displays the same information but with a diff directly following each entry.
31133103 This is very helpful for code review or to quickly browse what happened during a series of commits that a collaborator has added.
31143104 You can also use a series of summarizing options with `git log`.
31153105 For example, if you want to see some abbreviated stats for each commit, you can use the `--stat` option:
31163106
3117--[source,console]
3118------
3119--$ git log --stat
3120--commit ca82a6dff817ec66f44342007202690a93763949
3121--Author: Scott Chacon <schacon@gee-mail.com>
3122--Date: Mon Mar 17 21:52:11 2008 -0700
3123--
3124-- Change version number
3125--
3126-- Rakefile | 2 +-
3127-- 1 file changed, 1 insertion(+), 1 deletion(-)
3128--
3129--commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3130--Author: Scott Chacon <schacon@gee-mail.com>
3131--Date: Sat Mar 15 16:40:33 2008 -0700
3132--
3133-- Remove unnecessary test
3134--
3135-- lib/simplegit.rb | 5 -----
3136-- 1 file changed, 5 deletions(-)
3137--
3138--commit a11bef06a3f659402fe7563abf99ad00de2209e6
3139--Author: Scott Chacon <schacon@gee-mail.com>
3140--Date: Sat Mar 15 10:31:28 2008 -0700
3141--
3142-- Initial commit
3143--
3144-- README | 6 ++++++
3145-- Rakefile | 23 +++++++++++++++++++++++
3146-- lib/simplegit.rb | 25 +++++++++++++++++++++++++
3147-- 3 files changed, 54 insertions(+)
3148------
3149--
3107++[source,console]
3108++----
3109++$ git log --stat
3110++commit ca82a6dff817ec66f44342007202690a93763949
3111++Author: Scott Chacon <schacon@gee-mail.com>
3112++Date: Mon Mar 17 21:52:11 2008 -0700
3113++
3114++ Change version number
3115++
3116++ Rakefile | 2 +-
3117++ 1 file changed, 1 insertion(+), 1 deletion(-)
3118++
3119++commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
3120++Author: Scott Chacon <schacon@gee-mail.com>
3121++Date: Sat Mar 15 16:40:33 2008 -0700
3122++
3123++ Remove unnecessary test
3124++
3125++ lib/simplegit.rb | 5 -----
3126++ 1 file changed, 5 deletions(-)
3127++
3128++commit a11bef06a3f659402fe7563abf99ad00de2209e6
3129++Author: Scott Chacon <schacon@gee-mail.com>
3130++Date: Sat Mar 15 10:31:28 2008 -0700
3131++
3132++ Initial commit
3133++
3134++ README | 6 ++++++
3135++ Rakefile | 23 +++++++++++++++++++++++
3136++ lib/simplegit.rb | 25 +++++++++++++++++++++++++
3137++ 3 files changed, 54 insertions(+)
3138++----
3139++
31503140 As you can see, the `--stat` option prints below each commit entry a list of modified files, how many files were changed, and how many lines in those files were added and removed.
31513141 It also puts a summary of the information at the end.
31523142
31533143 Another really useful option is `--pretty`.
31543144 This option changes the log output to formats other than the default.
3155--A few prebuilt option values are available for you to use.
3156--The `oneline` value for this option prints each commit on a single line, which is useful if you're looking at a lot of commits.
3157--In addition, the `short`, `full`, and `fuller` values show the output in roughly the same format but with less or more information, respectively:
3158--
3159--[source,console]
3160------
3161--$ git log --pretty=oneline
3162--ca82a6dff817ec66f44342007202690a93763949 Change version number
3163--085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Remove unnecessary test
3164--a11bef06a3f659402fe7563abf99ad00de2209e6 Initial commit
3165------
3166--
3167--The most interesting option value is `format`, which allows you to specify your own log output format.
3168--This is especially useful when you're generating output for machine parsing -- because you specify the format explicitly, you know it won't change with updates to Git:(((log formatting)))
3169--
3170--[source,console]
3171------
3172--$ git log --pretty=format:"%h - %an, %ar : %s"
3173--ca82a6d - Scott Chacon, 6 years ago : Change version number
3174--085bb3b - Scott Chacon, 6 years ago : Remove unnecessary test
3175--a11bef0 - Scott Chacon, 6 years ago : Initial commit
3176------
3177-+A few prebuilt options are available for you to use.
3178-+The `oneline` option prints each commit on a single line, which is useful if you're looking at a lot of commits.
3179-+In addition, the `short`, `full`, and `fuller` options show the output in roughly the same format but with less or more information, respectively:
3145+-A few prebuilt options are available for you to use.
3146+-The `oneline` option prints each commit on a single line, which is useful if you're looking at a lot of commits.
3147+-In addition, the `short`, `full`, and `fuller` options show the output in roughly the same format but with less or more information, respectively:
3148++A few prebuilt option values are available for you to use.
3149++The `oneline` value for this option prints each commit on a single line, which is useful if you're looking at a lot of commits.
3150++In addition, the `short`, `full`, and `fuller` values show the output in roughly the same format but with less or more information, respectively:
3151++
3152++[source,console]
3153++----
3154++$ git log --pretty=oneline
3155++ca82a6dff817ec66f44342007202690a93763949 Change version number
3156++085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Remove unnecessary test
3157++a11bef06a3f659402fe7563abf99ad00de2209e6 Initial commit
3158++----
3159++
3160++The most interesting option value is `format`, which allows you to specify your own log output format.
3161++This is especially useful when you're generating output for machine parsing -- because you specify the format explicitly, you know it won't change with updates to Git:(((log formatting)))
3162++
3163++[source,console]
3164++----
3165++$ git log --pretty=format:"%h - %an, %ar : %s"
3166++ca82a6d - Scott Chacon, 6 years ago : Change version number
3167++085bb3b - Scott Chacon, 6 years ago : Remove unnecessary test
3168++a11bef0 - Scott Chacon, 6 years ago : Initial commit
3169++----
31803170
3181--<<pretty_format>> lists some of the more useful specifiers that `format` takes.
3182-+The most interesting option is `format`, which allows you to specify your own log output format.
3183-+This is especially useful when you're generating output for machine parsing – because you specify the format explicitly, you know it won't change with updates to Git:(((log formatting)))
3171+-The most interesting option is `format`, which allows you to specify your own log output format.
3172+-This is especially useful when you're generating output for machine parsing – because you specify the format explicitly, you know it won't change with updates to Git:(((log formatting)))
3173++<<pretty_format>> lists some of the more useful specifiers that `format` takes.
31843174
3185--[[pretty_format]]
3186--.Useful specifiers for `git log --pretty=format`
3187-+<<rpretty_format>> lists some of the more useful options that format takes.
3188-+
3189-+.Useful options for `git log --pretty=format`
3175+-<<rpretty_format>> lists some of the more useful options that format takes.
3176+-
3177+-.Useful options for `git log --pretty=format`
3178++[[pretty_format]]
3179++.Useful specifiers for `git log --pretty=format`
31903180 [cols="1,4",options="header"]
31913181 |================================
3192--| Specifier | Description of Output
3193--| `%H` | Commit hash
3194--| `%h` | Abbreviated commit hash
3195--| `%T` | Tree hash
3196--| `%t` | Abbreviated tree hash
3197--| `%P` | Parent hashes
3198--| `%p` | Abbreviated parent hashes
3199--| `%an` | Author name
3200--| `%ae` | Author email
3201--| `%ad` | Author date (format respects the --date=option)
3202--| `%ar` | Author date, relative
3203--| `%cn` | Committer name
3204--| `%ce` | Committer email
3205--| `%cd` | Committer date
3206--| `%cr` | Committer date, relative
3207--| `%s` | Subject
3208-+| Option | Description of Output
3209-+| `%H` | Commit hash
3210-+| `%h` | Abbreviated commit hash
3211-+| `%T` | Tree hash
3212-+| `%t` | Abbreviated tree hash
3213-+| `%P` | Parent hashes
3214-+| `%p` | Abbreviated parent hashes
3215-+| `%an` | Author name
3216-+| `%ae` | Author email
3217-+| `%ad` | Author date (format respects the --date=option)
3218-+| `%ar` | Author date, relative
3219-+| `%cn` | Committer name
3220-+| `%ce` | Committer email
3221-+| `%cd` | Committer date
3222-+| `%cr` | Committer date, relative
3223-+| `%s` | Subject
3182+-| Option | Description of Output
3183+-| `%H` | Commit hash
3184+-| `%h` | Abbreviated commit hash
3185+-| `%T` | Tree hash
3186+-| `%t` | Abbreviated tree hash
3187+-| `%P` | Parent hashes
3188+-| `%p` | Abbreviated parent hashes
3189+-| `%an` | Author name
3190+-| `%ae` | Author email
3191+-| `%ad` | Author date (format respects the --date=option)
3192+-| `%ar` | Author date, relative
3193+-| `%cn` | Committer name
3194+-| `%ce` | Committer email
3195+-| `%cd` | Committer date
3196+-| `%cr` | Committer date, relative
3197+-| `%s` | Subject
3198++| Specifier | Description of Output
3199++| `%H` | Commit hash
3200++| `%h` | Abbreviated commit hash
3201++| `%T` | Tree hash
3202++| `%t` | Abbreviated tree hash
3203++| `%P` | Parent hashes
3204++| `%p` | Abbreviated parent hashes
3205++| `%an` | Author name
3206++| `%ae` | Author email
3207++| `%ad` | Author date (format respects the --date=option)
3208++| `%ar` | Author date, relative
3209++| `%cn` | Committer name
3210++| `%ce` | Committer email
3211++| `%cd` | Committer date
3212++| `%cr` | Committer date, relative
3213++| `%s` | Subject
32243214 |================================
32253215
32263216 You may be wondering what the difference is between _author_ and _committer_.
32273217 The author is the person who originally wrote the work, whereas the committer is the person who last applied the work.
3228--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.
3229-+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.
3218+-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.
3219++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.
32303220 We'll cover this distinction a bit more in <<ch05-distributed-git#ch05-distributed-git>>.
32313221
3232--The `oneline` and `format` option values are particularly useful with another `log` option called `--graph`.
3233-+The `oneline` and `format` options are particularly useful with another `log` option called `--graph`.
3222+-The `oneline` and `format` options are particularly useful with another `log` option called `--graph`.
3223++The `oneline` and `format` option values are particularly useful with another `log` option called `--graph`.
32343224 This option adds a nice little ASCII graph showing your branch and merge history:
32353225
3236--[source,console]
3237------
3238--$ git log --pretty=format:"%h %s" --graph
3239--* 2d3acf9 Ignore errors from SIGCHLD on trap
3240--* 5e3ee11 Merge branch 'master' of git://github.com/dustin/grit
3241--|\
3242--| * 420eac9 Add method for getting the current branch
3243--* | 30e367c Timeout code and tests
3244--* | 5a09431 Add timeout protection to grit
3245--* | e1193f8 Support for heads with slashes in them
3246--|/
3247--* d6016bc Require time for xmlschema
3248--* 11d191e Merge branch 'defunkt' into local
3249------
3250--
3226++[source,console]
3227++----
3228++$ git log --pretty=format:"%h %s" --graph
3229++* 2d3acf9 Ignore errors from SIGCHLD on trap
3230++* 5e3ee11 Merge branch 'master' of git://github.com/dustin/grit
3231++|\
3232++| * 420eac9 Add method for getting the current branch
3233++* | 30e367c Timeout code and tests
3234++* | 5a09431 Add timeout protection to grit
3235++* | e1193f8 Support for heads with slashes in them
3236++|/
3237++* d6016bc Require time for xmlschema
3238++* 11d191e Merge branch 'defunkt' into local
3239++----
3240++
32513241 This type of output will become more interesting as we go through branching and merging in the next chapter.
32523242
3253--Those are only some simple output-formatting options to `git log` -- there are many more.
3254--<<log_options>> lists the options we've covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command.
3255-+Those are only some simple output-formatting options to `git log` – there are many more.
3256-+<<rlog_options>> lists the options we've covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command.
3243+-Those are only some simple output-formatting options to `git log` – there are many more.
3244+-<<rlog_options>> lists the options we've covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command.
3245++Those are only some simple output-formatting options to `git log` -- there are many more.
3246++<<log_options>> lists the options we've covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command.
32573247
3258--[[log_options]]
3248++[[log_options]]
32593249 .Common options to `git log`
32603250 [cols="1,4",options="header"]
32613251 |================================
3262-@@ -220,63 +83,39 @@
3252+@@ -83,39 +220,63 @@
32633253 | `--abbrev-commit` | Show only the first few characters of the SHA-1 checksum instead of all 40.
32643254 | `--relative-date` | Display the date in a relative format (for example, ``2 weeks ago'') instead of using the full date format.
32653255 | `--graph` | Display an ASCII graph of the branch and merge history beside the log output.
3266--| `--pretty` | Show commits in an alternate format. Option values include oneline, short, full, fuller, and format (where you specify your own format).
3267--| `--oneline` | Shorthand for `--pretty=oneline --abbrev-commit` used together.
3268-+| `--pretty` | Show commits in an alternate format. Options include oneline, short, full, fuller, and format (where you specify your own format).
3256+-| `--pretty` | Show commits in an alternate format. Options include oneline, short, full, fuller, and format (where you specify your own format).
3257++| `--pretty` | Show commits in an alternate format. Option values include oneline, short, full, fuller, and format (where you specify your own format).
3258++| `--oneline` | Shorthand for `--pretty=oneline --abbrev-commit` used together.
32693259 |================================
32703260
32713261 ==== Limiting Log Output
32723262
3273--In addition to output-formatting options, `git log` takes a number of useful limiting options; that is, options that let you show only a subset of commits.
3274--You've seen one such option already -- the `-2` option, which displays only the last two commits.
3275-+In addition to output-formatting options, `git log` takes a number of useful limiting options – that is, options that let you show only a subset of commits.
3276-+You've seen one such option already – the `-2` option, which show only the last two commits.
3263+-In addition to output-formatting options, `git log` takes a number of useful limiting options – that is, options that let you show only a subset of commits.
3264+-You've seen one such option already – the `-2` option, which show only the last two commits.
3265++In addition to output-formatting options, `git log` takes a number of useful limiting options; that is, options that let you show only a subset of commits.
3266++You've seen one such option already -- the `-2` option, which displays only the last two commits.
32773267 In fact, you can do `-<n>`, where `n` is any integer to show the last `n` commits.
32783268 In reality, you're unlikely to use that often, because Git by default pipes all output through a pager so you see only one page of log output at a time.
32793269
32803270 However, the time-limiting options such as `--since` and `--until` are very useful.
32813271 For example, this command gets the list of commits made in the last two weeks:
32823272
3283--[source,console]
3284------
3285--$ git log --since=2.weeks
3286------
3287--
3288--This command works with lots of formats -- you can specify a specific date like `"2008-01-15"`, or a relative date such as `"2 years 1 day 3 minutes ago"`.
3289-+This command works with lots of formats – you can specify a specific date like `"2008-01-15"`, or a relative date such as `"2 years 1 day 3 minutes ago"`.
3273+-This command works with lots of formats – you can specify a specific date like `"2008-01-15"`, or a relative date such as `"2 years 1 day 3 minutes ago"`.
3274++[source,console]
3275++----
3276++$ git log --since=2.weeks
3277++----
3278++
3279++This command works with lots of formats -- you can specify a specific date like `"2008-01-15"`, or a relative date such as `"2 years 1 day 3 minutes ago"`.
32903280
32913281 You can also filter the list to commits that match some search criteria.
32923282 The `--author` option allows you to filter on a specific author, and the `--grep` option lets you search for keywords in the commit messages.
3293-+(Note that if you want to specify both author and grep options, you have to add `--all-match` or the command will match commits with either.)
3294-
3295--[NOTE]
3296--====
3297--You can specify more than one instance of both the `--author` and `--grep` search criteria, which
3298--will limit the commit output to commits that match _any_ of the `--author` patterns and _any_
3299--of the `--grep` patterns; however, adding the `--all-match` option further limits the output to
3300--just those commits that match _all_ `--grep` patterns.
3301--====
3302--
3303--Another really helpful filter is the `-S` option (colloquially referred to as Git's ``pickaxe'' option), which takes a string and shows only those commits that changed the number of occurrences of that string.
3304-+Another really helpful filter is the `-S` option which takes a string and only shows the commits that introduced a change to the code that added or removed that string.
3283+-(Note that if you want to specify both author and grep options, you have to add `--all-match` or the command will match commits with either.)
3284+
3285+-Another really helpful filter is the `-S` option which takes a string and only shows the commits that introduced a change to the code that added or removed that string.
3286++[NOTE]
3287++====
3288++You can specify more than one instance of both the `--author` and `--grep` search criteria, which
3289++will limit the commit output to commits that match _any_ of the `--author` patterns and _any_
3290++of the `--grep` patterns; however, adding the `--all-match` option further limits the output to
3291++just those commits that match _all_ `--grep` patterns.
3292++====
3293++
3294++Another really helpful filter is the `-S` option (colloquially referred to as Git's ``pickaxe'' option), which takes a string and shows only those commits that changed the number of occurrences of that string.
33053295 For instance, if you wanted to find the last commit that added or removed a reference to a specific function, you could call:
33063296
3307--[source,console]
3308------
3309--$ git log -S function_name
3310------
3311--
3297++[source,console]
3298++----
3299++$ git log -S function_name
3300++----
3301++
33123302 The last really useful option to pass to `git log` as a filter is a path.
33133303 If you specify a directory or file name, you can limit the log output to commits that introduced a change to those files.
3314--This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options:
3315--
3316--[source,console]
3317------
3318--$ git log -- path/to/file
3319------
3320-+This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options.
3304+-This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options.
3305++This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options:
3306++
3307++[source,console]
3308++----
3309++$ git log -- path/to/file
3310++----
33213311
3322--In <<limit_options>> we'll list these and a few other common options for your reference.
3323-+In <<rlimit_options>> we'll list these and a few other common options for your reference.
3312+-In <<rlimit_options>> we'll list these and a few other common options for your reference.
3313++In <<limit_options>> we'll list these and a few other common options for your reference.
33243314
3325--[[limit_options]]
3315++[[limit_options]]
33263316 .Options to limit the output of `git log`
33273317 [cols="2,4",options="header"]
33283318 |================================
33293319 | Option | Description
3330--| `-<n>` | Show only the last n commits
3331-+| `-(n)` | Show only the last n commits
3320+-| `-(n)` | Show only the last n commits
3321++| `-<n>` | Show only the last n commits
33323322 | `--since`, `--after` | Limit the commits to those made after the specified date.
33333323 | `--until`, `--before` | Limit the commits to those made before the specified date.
33343324 | `--author` | Only show commits in which the author entry matches the specified string.
3335-@@ -285,25 +124,6 @@
3325+@@ -124,6 +285,25 @@
33363326 | `-S` | Only show commits adding or removing code matching the string
33373327 |================================
33383328
3339--For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano in the month of October 2008 and are not merge commits, you can run something like this:(((log filtering)))
3340--
3341--[source,console]
3342------
3343--$ git log --pretty="%h - %s" --author='Junio C Hamano' --since="2008-10-01" \
3344-- --before="2008-11-01" --no-merges -- t/
3345--5610e3b - Fix testcase failure when extended attributes are in use
3346--acd3b9e - Enhance hold_lock_file_for_{update,append}() API
3347--f563754 - demonstrate breakage of detached checkout with symbolic link HEAD
3348--d1a43f2 - reset --hard/read-tree --reset -u: remove unmerged new paths
3349--51a94af - Fix "checkout --track -b newbranch" on detached HEAD
3350--b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unborn branch
3351------
3352-+For example, if you want to see which commits modifying test files in the Git source code history are merged and were committed by Junio Hamano in the month of October 2008, you can run something like this:(((log filtering)))
3329+-For example, if you want to see which commits modifying test files in the Git source code history are merged and were committed by Junio Hamano in the month of October 2008, you can run something like this:(((log filtering)))
3330++For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano in the month of October 2008 and are not merge commits, you can run something like this:(((log filtering)))
3331++
3332++[source,console]
3333++----
3334++$ git log --pretty="%h - %s" --author='Junio C Hamano' --since="2008-10-01" \
3335++ --before="2008-11-01" --no-merges -- t/
3336++5610e3b - Fix testcase failure when extended attributes are in use
3337++acd3b9e - Enhance hold_lock_file_for_{update,append}() API
3338++f563754 - demonstrate breakage of detached checkout with symbolic link HEAD
3339++d1a43f2 - reset --hard/read-tree --reset -u: remove unmerged new paths
3340++51a94af - Fix "checkout --track -b newbranch" on detached HEAD
3341++b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unborn branch
3342++----
33533343
33543344 Of the nearly 40,000 commits in the Git source code history, this command shows the 6 that match those criteria.
3355--
3356--[TIP]
3357--.Preventing the display of merge commits
3358--====
3359--Depending on the workflow used in your repository, it's possible that a sizable percentage of the commits in your log history are just merge commits, which typically aren't very informative.
3360--To prevent the display of merge commits cluttering up your log history, simply add the log option `--no-merges`.
3361--====
3362-diff -au ../../git/progit2/progit2/book/03-git-branching/sections/basic-branching-and-merging.asc /tmp/book/03-git-branching/sections/basic-branching-and-merging.asc.tmp
3363---- ../../git/progit2/progit2/book/03-git-branching/sections/basic-branching-and-merging.asc 2020-07-04 16:36:46.720685416 +0900
3364-+++ /tmp/book/03-git-branching/sections/basic-branching-and-merging.asc.tmp 2020-10-25 09:24:25.655966668 +0900
3345++
3346++[TIP]
3347++.Preventing the display of merge commits
3348++====
3349++Depending on the workflow used in your repository, it's possible that a sizable percentage of the commits in your log history are just merge commits, which typically aren't very informative.
3350++To prevent the display of merge commits cluttering up your log history, simply add the log option `--no-merges`.
3351++====
3352+diff -au /tmp/book/03-git-branching/sections/basic-branching-and-merging.asc.tmp ../../git/progit2/progit2/book/03-git-branching/sections/basic-branching-and-merging.asc
3353+--- /tmp/book/03-git-branching/sections/basic-branching-and-merging.asc.tmp 2020-10-25 11:05:02.191636472 +0900
3354++++ ../../git/progit2/progit2/book/03-git-branching/sections/basic-branching-and-merging.asc 2020-07-04 16:36:46.720685416 +0900
33653355 @@ -3,8 +3,8 @@
33663356 Let's go through a simple example of branching and merging with a workflow that you might use in the real world.
33673357 You'll follow these steps:
33683358
3369--. Do some work on a website.
3370--. Create a branch for a new user story you're working on.
3371-+. Do work on a web site.
3372-+. Create a branch for a new story you're working on.
3359+-. Do work on a web site.
3360+-. Create a branch for a new story you're working on.
3361++. Do some work on a website.
3362++. Create a branch for a new user story you're working on.
33733363 . Do some work in that branch.
33743364
33753365 At this stage, you'll receive a call that another issue is critical and you need a hotfix.
3376-@@ -13,306 +13,134 @@
3366+@@ -13,134 +13,306 @@
33773367 . Switch to your production branch.
33783368 . Create a branch to add the hotfix.
33793369 . After it's tested, merge the hotfix branch, and push to production.
3380--. Switch back to your original user story and continue working.
3381-+. Switch back to your original story and continue working.
3370+-. Switch back to your original story and continue working.
3371++. Switch back to your original user story and continue working.
33823372
3383--[[_basic_branching]]
3373++[[_basic_branching]]
33843374 ==== Basic Branching
33853375
3386--(((branches, basic workflow)))
3387--First, let's say you're working on your project and have a couple of commits already on the `master` branch.
3388-+First, let's say you're working on your project and have a couple of commits already.
3376+-First, let's say you're working on your project and have a couple of commits already.
3377++(((branches, basic workflow)))
3378++First, let's say you're working on your project and have a couple of commits already on the `master` branch.
33893379
33903380 .A simple commit history
3391--image::images/basic-branching-1.png[A simple commit history]
3392-+image::images/basic-branching-1.png[A simple commit history.]
3381+-image::images/basic-branching-1.png[A simple commit history.]
3382++image::images/basic-branching-1.png[A simple commit history]
33933383
33943384 You've decided that you're going to work on issue #53 in whatever issue-tracking system your company uses.
3395--To create a new branch and switch to it at the same time, you can run the `git checkout` command with the `-b` switch:
3396--
3397--[source,console]
3398------
3399--$ git checkout -b iss53
3400--Switched to a new branch "iss53"
3401------
3402-+To create a branch and switch to it at the same time, you can run the `git checkout` command with the `-b` switch:
3385+-To create a branch and switch to it at the same time, you can run the `git checkout` command with the `-b` switch:
3386++To create a new branch and switch to it at the same time, you can run the `git checkout` command with the `-b` switch:
3387++
3388++[source,console]
3389++----
3390++$ git checkout -b iss53
3391++Switched to a new branch "iss53"
3392++----
34033393
34043394 This is shorthand for:
34053395
3406--[source,console]
3407------
3408--$ git branch iss53
3409--$ git checkout iss53
3410------
3411--
3396++[source,console]
3397++----
3398++$ git branch iss53
3399++$ git checkout iss53
3400++----
3401++
34123402 .Creating a new branch pointer
3413--image::images/basic-branching-2.png[Creating a new branch pointer]
3414-+image::images/basic-branching-2.png[Creating a new branch pointer.]
3403+-image::images/basic-branching-2.png[Creating a new branch pointer.]
3404++image::images/basic-branching-2.png[Creating a new branch pointer]
34153405
3416--You work on your website and do some commits.
3417-+You work on your web site and do some commits.
3406+-You work on your web site and do some commits.
3407++You work on your website and do some commits.
34183408 Doing so moves the `iss53` branch forward, because you have it checked out (that is, your `HEAD` is pointing to it):
34193409
3420--[source,console]
3421------
3422--$ vim index.html
3423--$ git commit -a -m 'Create new footer [issue 53]'
3424------
3425--
3426--.The `iss53` branch has moved forward with your work
3427--image::images/basic-branching-3.png[The `iss53` branch has moved forward with your work]
3428-+.The iss53 branch has moved forward with your work
3429-+image::images/basic-branching-3.png[The iss53 branch has moved forward with your work.]
3410+-.The iss53 branch has moved forward with your work
3411+-image::images/basic-branching-3.png[The iss53 branch has moved forward with your work.]
3412++[source,console]
3413++----
3414++$ vim index.html
3415++$ git commit -a -m 'Create new footer [issue 53]'
3416++----
3417++
3418++.The `iss53` branch has moved forward with your work
3419++image::images/basic-branching-3.png[The `iss53` branch has moved forward with your work]
34303420
3431--Now you get the call that there is an issue with the website, and you need to fix it immediately.
3432-+Now you get the call that there is an issue with the web site, and you need to fix it immediately.
3421+-Now you get the call that there is an issue with the web site, and you need to fix it immediately.
3422++Now you get the call that there is an issue with the website, and you need to fix it immediately.
34333423 With Git, you don't have to deploy your fix along with the `iss53` changes you've made, and you don't have to put a lot of effort into reverting those changes before you can work on applying your fix to what is in production.
34343424 All you have to do is switch back to your `master` branch.
34353425
34363426 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.
34373427 It's best to have a clean working state when you switch branches.
3438--There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<ch07-git-tools#_git_stashing>>.
3439-+There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<ch07-git-tools#r_git_stashing>>.
3428+-There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<ch07-git-tools#r_git_stashing>>.
3429++There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<ch07-git-tools#_git_stashing>>.
34403430 For now, let's assume you've committed all your changes, so you can switch back to your `master` branch:
34413431
3442--[source,console]
3443------
3444--$ git checkout master
3445--Switched to branch 'master'
3446------
3447--
3432++[source,console]
3433++----
3434++$ git checkout master
3435++Switched to branch 'master'
3436++----
3437++
34483438 At this point, your project working directory is exactly the way it was before you started working on issue #53, and you can concentrate on your hotfix.
34493439 This is an important point to remember: when you switch branches, Git resets your working directory to look like it did the last time you committed on that branch.
34503440 It adds, removes, and modifies files automatically to make sure your working copy is what the branch looked like on your last commit to it.
34513441
34523442 Next, you have a hotfix to make.
3453--Let's create a `hotfix` branch on which to work until it's completed:
3454--
3455--[source,console]
3456------
3457--$ git checkout -b hotfix
3458--Switched to a new branch 'hotfix'
3459--$ vim index.html
3460--$ git commit -a -m 'Fix broken email address'
3461--[hotfix 1fb7853] Fix broken email address
3462-- 1 file changed, 2 insertions(+)
3463------
3464-+Let's create a hotfix branch on which to work until it's completed:
3443+-Let's create a hotfix branch on which to work until it's completed:
3444++Let's create a `hotfix` branch on which to work until it's completed:
3445++
3446++[source,console]
3447++----
3448++$ git checkout -b hotfix
3449++Switched to a new branch 'hotfix'
3450++$ vim index.html
3451++$ git commit -a -m 'Fix broken email address'
3452++[hotfix 1fb7853] Fix broken email address
3453++ 1 file changed, 2 insertions(+)
3454++----
34653455
34663456 .Hotfix branch based on `master`
3467--image::images/basic-branching-4.png[Hotfix branch based on `master`]
3468-+image::images/basic-branching-4.png[Hotfix branch based on `master`.]
3457+-image::images/basic-branching-4.png[Hotfix branch based on `master`.]
3458++image::images/basic-branching-4.png[Hotfix branch based on `master`]
34693459
3470--You can run your tests, make sure the hotfix is what you want, and finally merge the `hotfix` branch back into your `master` branch to deploy to production.
3471-+You can run your tests, make sure the hotfix is what you want, and merge it back into your `master` branch to deploy to production.
3460+-You can run your tests, make sure the hotfix is what you want, and merge it back into your `master` branch to deploy to production.
3461++You can run your tests, make sure the hotfix is what you want, and finally merge the `hotfix` branch back into your `master` branch to deploy to production.
34723462 You do this with the `git merge` command:(((git commands, merge)))
34733463
3474--[source,console]
3475------
3476--$ git checkout master
3477--$ git merge hotfix
3478--Updating f42c576..3a0874c
3479--Fast-forward
3480-- index.html | 2 ++
3481-- 1 file changed, 2 insertions(+)
3482------
3483--
3464++[source,console]
3465++----
3466++$ git checkout master
3467++$ git merge hotfix
3468++Updating f42c576..3a0874c
3469++Fast-forward
3470++ index.html | 2 ++
3471++ 1 file changed, 2 insertions(+)
3472++----
3473++
34843474 You'll notice the phrase ``fast-forward'' in that merge.
3485--Because the commit `C4` pointed to by the branch `hotfix` you merged in was directly ahead of the commit `C2` you're on, Git simply moves the pointer forward.
3486--To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together -- this is called a ``fast-forward.''
3487-+Because the commit pointed to by the branch you merged in was directly upstream of the commit you're on, Git simply moves the pointer forward.
3488-+To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together – this is called a ``fast-forward.''
3475+-Because the commit pointed to by the branch you merged in was directly upstream of the commit you're on, Git simply moves the pointer forward.
3476+-To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together – this is called a ``fast-forward.''
3477++Because the commit `C4` pointed to by the branch `hotfix` you merged in was directly ahead of the commit `C2` you're on, Git simply moves the pointer forward.
3478++To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together -- this is called a ``fast-forward.''
34893479
34903480 Your change is now in the snapshot of the commit pointed to by the `master` branch, and you can deploy the fix.
34913481
34923482 .`master` is fast-forwarded to `hotfix`
3493--image::images/basic-branching-5.png[`master` is fast-forwarded to `hotfix`]
3494-+image::images/basic-branching-5.png[`master` is fast-forwarded to `hotfix`.]
3483+-image::images/basic-branching-5.png[`master` is fast-forwarded to `hotfix`.]
3484++image::images/basic-branching-5.png[`master` is fast-forwarded to `hotfix`]
34953485
34963486 After your super-important fix is deployed, you're ready to switch back to the work you were doing before you were interrupted.
3497--However, first you'll delete the `hotfix` branch, because you no longer need it -- the `master` branch points at the same place.
3498-+However, first you'll delete the `hotfix` branch, because you no longer need it – the `master` branch points at the same place.
3487+-However, first you'll delete the `hotfix` branch, because you no longer need it – the `master` branch points at the same place.
3488++However, first you'll delete the `hotfix` branch, because you no longer need it -- the `master` branch points at the same place.
34993489 You can delete it with the `-d` option to `git branch`:
35003490
3501--[source,console]
3502------
3503--$ git branch -d hotfix
3504--Deleted branch hotfix (3a0874c).
3505------
3506--
3491++[source,console]
3492++----
3493++$ git branch -d hotfix
3494++Deleted branch hotfix (3a0874c).
3495++----
3496++
35073497 Now you can switch back to your work-in-progress branch on issue #53 and continue working on it.
35083498
3509--[source,console]
3510------
3511--$ git checkout iss53
3512--Switched to branch "iss53"
3513--$ vim index.html
3514--$ git commit -a -m 'Finish the new footer [issue 53]'
3515--[iss53 ad82d7a] Finish the new footer [issue 53]
3516--1 file changed, 1 insertion(+)
3517------
3518--
3499++[source,console]
3500++----
3501++$ git checkout iss53
3502++Switched to branch "iss53"
3503++$ vim index.html
3504++$ git commit -a -m 'Finish the new footer [issue 53]'
3505++[iss53 ad82d7a] Finish the new footer [issue 53]
3506++1 file changed, 1 insertion(+)
3507++----
3508++
35193509 .Work continues on `iss53`
3520--image::images/basic-branching-6.png[Work continues on `iss53`]
3521-+image::images/basic-branching-6.png[Work continues on `iss53`.]
3510+-image::images/basic-branching-6.png[Work continues on `iss53`.]
3511++image::images/basic-branching-6.png[Work continues on `iss53`]
35223512
35233513 It's worth noting here that the work you did in your `hotfix` branch is not contained in the files in your `iss53` branch.
35243514 If you need to pull it in, you can merge your `master` branch into your `iss53` branch by running `git merge master`, or you can wait to integrate those changes until you decide to pull the `iss53` branch back into `master` later.
35253515
3526--[[_basic_merging]]
3516++[[_basic_merging]]
35273517 ==== Basic Merging
35283518
3529--(((branches, merging)))(((merging)))
3519++(((branches, merging)))(((merging)))
35303520 Suppose you've decided that your issue #53 work is complete and ready to be merged into your `master` branch.
35313521 In order to do that, you'll merge your `iss53` branch into `master`, much like you merged your `hotfix` branch earlier.
35323522 All you have to do is check out the branch you wish to merge into and then run the `git merge` command:
35333523
3534--[source,console]
3535------
3536--$ git checkout master
3537--Switched to branch 'master'
3538--$ git merge iss53
3539--Merge made by the 'recursive' strategy.
3540--index.html | 1 +
3541--1 file changed, 1 insertion(+)
3542------
3543--
3524++[source,console]
3525++----
3526++$ git checkout master
3527++Switched to branch 'master'
3528++$ git merge iss53
3529++Merge made by the 'recursive' strategy.
3530++index.html | 1 +
3531++1 file changed, 1 insertion(+)
3532++----
3533++
35443534 This looks a bit different than the `hotfix` merge you did earlier.
35453535 In this case, your development history has diverged from some older point.
35463536 Because the commit on the branch you're on isn't a direct ancestor of the branch you're merging in, Git has to do some work.
35473537 In this case, Git does a simple three-way merge, using the two snapshots pointed to by the branch tips and the common ancestor of the two.
35483538
35493539 .Three snapshots used in a typical merge
3550--image::images/basic-merging-1.png[Three snapshots used in a typical merge]
3551-+image::images/basic-merging-1.png[Three snapshots used in a typical merge.]
3540+-image::images/basic-merging-1.png[Three snapshots used in a typical merge.]
3541++image::images/basic-merging-1.png[Three snapshots used in a typical merge]
35523542
35533543 Instead of just moving the branch pointer forward, Git creates a new snapshot that results from this three-way merge and automatically creates a new commit that points to it.
35543544 This is referred to as a merge commit, and is special in that it has more than one parent.
35553545
35563546 .A merge commit
3557--image::images/basic-merging-2.png[A merge commit]
3558-+image::images/basic-merging-2.png[A merge commit.]
3559-
3560--Now that your work is merged in, you have no further need for the `iss53` branch.
3561--You can close the issue in your issue-tracking system, and delete the branch:
3562-+It's worth pointing out that Git determines the best common ancestor to use for its merge base; this is different than older tools like CVS or Subversion (before version 1.5), where the developer doing the merge had to figure out the best merge base for themselves.
3563-+This makes merging a heck of a lot easier in Git than in these other systems.
3547+-image::images/basic-merging-2.png[A merge commit.]
3548+-
3549+-It's worth pointing out that Git determines the best common ancestor to use for its merge base; this is different than older tools like CVS or Subversion (before version 1.5), where the developer doing the merge had to figure out the best merge base for themselves.
3550+-This makes merging a heck of a lot easier in Git than in these other systems.
3551++image::images/basic-merging-2.png[A merge commit]
35643552
3565--[source,console]
3566------
3567--$ git branch -d iss53
3568------
3569-+Now that your work is merged in, you have no further need for the `iss53` branch.
3570-+You can close the ticket in your ticket-tracking system, and delete the branch:
3553+ Now that your work is merged in, you have no further need for the `iss53` branch.
3554+-You can close the ticket in your ticket-tracking system, and delete the branch:
3555++You can close the issue in your issue-tracking system, and delete the branch:
3556++
3557++[source,console]
3558++----
3559++$ git branch -d iss53
3560++----
35713561
3572--[[_basic_merge_conflicts]]
3562++[[_basic_merge_conflicts]]
35733563 ==== Basic Merge Conflicts
35743564
3575--(((merging, conflicts)))
3565++(((merging, conflicts)))
35763566 Occasionally, this process doesn't go smoothly.
3577--If you changed the same part of the same file differently in the two branches you're merging, Git won't be able to merge them cleanly.
3578--If your fix for issue #53 modified the same part of a file as the `hotfix` branch, you'll get a merge conflict that looks something like this:
3579--
3580--[source,console]
3581------
3582--$ git merge iss53
3583--Auto-merging index.html
3584--CONFLICT (content): Merge conflict in index.html
3585--Automatic merge failed; fix conflicts and then commit the result.
3586------
3587-+If you changed the same part of the same file differently in the two branches you're merging together, Git won't be able to merge them cleanly.
3588-+If your fix for issue #53 modified the same part of a file as the `hotfix`, you'll get a merge conflict that looks something like this:
3567+-If you changed the same part of the same file differently in the two branches you're merging together, Git won't be able to merge them cleanly.
3568+-If your fix for issue #53 modified the same part of a file as the `hotfix`, you'll get a merge conflict that looks something like this:
3569++If you changed the same part of the same file differently in the two branches you're merging, Git won't be able to merge them cleanly.
3570++If your fix for issue #53 modified the same part of a file as the `hotfix` branch, you'll get a merge conflict that looks something like this:
3571++
3572++[source,console]
3573++----
3574++$ git merge iss53
3575++Auto-merging index.html
3576++CONFLICT (content): Merge conflict in index.html
3577++Automatic merge failed; fix conflicts and then commit the result.
3578++----
35893579
35903580 Git hasn't automatically created a new merge commit.
35913581 It has paused the process while you resolve the conflict.
35923582 If you want to see which files are unmerged at any point after a merge conflict, you can run `git status`:
35933583
3594--[source,console]
3595------
3596--$ git status
3597--On branch master
3598--You have unmerged paths.
3599-- (fix conflicts and run "git commit")
3600--
3601--Unmerged paths:
3602-- (use "git add <file>..." to mark resolution)
3603--
3604-- both modified: index.html
3605--
3606--no changes added to commit (use "git add" and/or "git commit -a")
3607------
3608--
3584++[source,console]
3585++----
3586++$ git status
3587++On branch master
3588++You have unmerged paths.
3589++ (fix conflicts and run "git commit")
3590++
3591++Unmerged paths:
3592++ (use "git add <file>..." to mark resolution)
3593++
3594++ both modified: index.html
3595++
3596++no changes added to commit (use "git add" and/or "git commit -a")
3597++----
3598++
36093599 Anything that has merge conflicts and hasn't been resolved is listed as unmerged.
36103600 Git adds standard conflict-resolution markers to the files that have conflicts, so you can open them manually and resolve those conflicts.
36113601 Your file contains a section that looks something like this:
36123602
3613--[source,html]
3614------
3615--<<<<<<< HEAD:index.html
3616--<div id="footer">contact : email.support@github.com</div>
3617--=======
3618--<div id="footer">
3619-- please contact us at support@github.com
3620--</div>
3621-->>>>>>> iss53:index.html
3622------
3623--
3603++[source,html]
3604++----
3605++<<<<<<< HEAD:index.html
3606++<div id="footer">contact : email.support@github.com</div>
3607++=======
3608++<div id="footer">
3609++ please contact us at support@github.com
3610++</div>
3611++>>>>>>> iss53:index.html
3612++----
3613++
36243614 This means the version in `HEAD` (your `master` branch, because that was what you had checked out when you ran your merge command) is the top part of that block (everything above the `=======`), while the version in your `iss53` branch looks like everything in the bottom part.
36253615 In order to resolve the conflict, you have to either choose one side or the other or merge the contents yourself.
36263616 For instance, you might resolve this conflict by replacing the entire block with this:
36273617
3628--[source,html]
3629------
3630--<div id="footer">
3631--please contact us at email.support@github.com
3632--</div>
3633------
3634--
3635--This resolution has a little of each section, and the `<<<<<<<`, `=======`, and `>>>>>>>` lines have been completely removed.
3636-+This resolution has a little of each section, and the `>>>>>` lines have been completely removed.
3618+-This resolution has a little of each section, and the `>>>>>` lines have been completely removed.
3619++[source,html]
3620++----
3621++<div id="footer">
3622++please contact us at email.support@github.com
3623++</div>
3624++----
3625++
3626++This resolution has a little of each section, and the `<<<<<<<`, `=======`, and `>>>>>>>` lines have been completely removed.
36373627 After you've resolved each of these sections in each conflicted file, run `git add` on each file to mark it as resolved.
36383628 Staging the file marks it as resolved in Git.
36393629
36403630 If you want to use a graphical tool to resolve these issues, you can run `git mergetool`, which fires up an appropriate visual merge tool and walks you through the conflicts:(((git commands, mergetool)))
36413631
3642--[source,console]
3643------
3644--$ git mergetool
3645--
3646--This message is displayed because 'merge.tool' is not configured.
3647--See 'git mergetool --tool-help' or 'git help config' for more details.
3648--'git mergetool' will now attempt to use one of the following tools:
3649--opendiff kdiff3 tkdiff xxdiff meld tortoisemerge gvimdiff diffuse diffmerge ecmerge p4merge araxis bc3 codecompare vimdiff emerge
3650--Merging:
3651--index.html
3652--
3653--Normal merge conflict for 'index.html':
3654-- {local}: modified file
3655-- {remote}: modified file
3656--Hit return to start merge resolution tool (opendiff):
3657------
3658--
3632++[source,console]
3633++----
3634++$ git mergetool
3635++
3636++This message is displayed because 'merge.tool' is not configured.
3637++See 'git mergetool --tool-help' or 'git help config' for more details.
3638++'git mergetool' will now attempt to use one of the following tools:
3639++opendiff kdiff3 tkdiff xxdiff meld tortoisemerge gvimdiff diffuse diffmerge ecmerge p4merge araxis bc3 codecompare vimdiff emerge
3640++Merging:
3641++index.html
3642++
3643++Normal merge conflict for 'index.html':
3644++ {local}: modified file
3645++ {remote}: modified file
3646++Hit return to start merge resolution tool (opendiff):
3647++----
3648++
36593649 If you want to use a merge tool other than the default (Git chose `opendiff` in this case because the command was run on a Mac), you can see all the supported tools listed at the top after ``one of the following tools.''
36603650 Just type the name of the tool you'd rather use.
36613651
3662--[NOTE]
3652++[NOTE]
36633653 ====
3664--If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<ch07-git-tools#_advanced_merging>>.
3665-+If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<ch07-git-tools#r_advanced_merging>>.
3654+-If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<ch07-git-tools#r_advanced_merging>>.
3655++If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<ch07-git-tools#_advanced_merging>>.
36663656 ====
36673657
36683658 After you exit the merge tool, Git asks you if the merge was successful.
36693659 If you tell the script that it was, it stages the file to mark it as resolved for you.
36703660 You can run `git status` again to verify that all conflicts have been resolved:
36713661
3672--[source,console]
3673------
3674--$ git status
3675--On branch master
3676--All conflicts fixed but you are still merging.
3677-- (use "git commit" to conclude merge)
3678--
3679--Changes to be committed:
3680--
3681-- modified: index.html
3682------
3683--
3662++[source,console]
3663++----
3664++$ git status
3665++On branch master
3666++All conflicts fixed but you are still merging.
3667++ (use "git commit" to conclude merge)
3668++
3669++Changes to be committed:
3670++
3671++ modified: index.html
3672++----
3673++
36843674 If you're happy with that, and you verify that everything that had conflicts has been staged, you can type `git commit` to finalize the merge commit.
36853675 The commit message by default looks something like this:
36863676
3687--[source,console]
3688------
3689--Merge branch 'iss53'
3690--
3691--Conflicts:
3692-- index.html
3693--#
3694--# It looks like you may be committing a merge.
3695--# If this is not correct, please remove the file
3696--# .git/MERGE_HEAD
3697--# and try again.
3698--
3699--
3700--# Please enter the commit message for your changes. Lines starting
3701--# with '#' will be ignored, and an empty message aborts the commit.
3702--# On branch master
3703--# All conflicts fixed but you are still merging.
3704--#
3705--# Changes to be committed:
3706--# modified: index.html
3707--#
3708------
3709--
3710--If you think it would be helpful to others looking at this merge in the future, you can modify this commit message with details about how you resolved the merge and explain why you did the changes you made if these are not obvious.
3711-+You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future – why you did what you did, if it's not obvious.
3712-diff -au ../../git/progit2/progit2/book/03-git-branching/sections/branch-management.asc /tmp/book/03-git-branching/sections/branch-management.asc.tmp
3713---- ../../git/progit2/progit2/book/03-git-branching/sections/branch-management.asc 2020-09-12 09:27:13.221663700 +0900
3714-+++ /tmp/book/03-git-branching/sections/branch-management.asc.tmp 2020-10-25 09:24:25.660966904 +0900
3677+-You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future – why you did what you did, if it's not obvious.
3678++[source,console]
3679++----
3680++Merge branch 'iss53'
3681++
3682++Conflicts:
3683++ index.html
3684++#
3685++# It looks like you may be committing a merge.
3686++# If this is not correct, please remove the file
3687++# .git/MERGE_HEAD
3688++# and try again.
3689++
3690++
3691++# Please enter the commit message for your changes. Lines starting
3692++# with '#' will be ignored, and an empty message aborts the commit.
3693++# On branch master
3694++# All conflicts fixed but you are still merging.
3695++#
3696++# Changes to be committed:
3697++# modified: index.html
3698++#
3699++----
3700++
3701++If you think it would be helpful to others looking at this merge in the future, you can modify this commit message with details about how you resolved the merge and explain why you did the changes you made if these are not obvious.
3702+diff -au /tmp/book/03-git-branching/sections/branch-management.asc.tmp ../../git/progit2/progit2/book/03-git-branching/sections/branch-management.asc
3703+--- /tmp/book/03-git-branching/sections/branch-management.asc.tmp 2020-10-25 11:05:02.196636753 +0900
3704++++ ../../git/progit2/progit2/book/03-git-branching/sections/branch-management.asc 2020-09-12 09:27:13.221663700 +0900
37153705 @@ -1,4 +1,4 @@
3716--[[_branch_management]]
3717-+[[r_branch_management]]
3706+-[[r_branch_management]]
3707++[[_branch_management]]
37183708 === Branch Management
37193709
37203710 (((branches, managing)))
@@ -3722,16877 +3712,16781 @@ diff -au ../../git/progit2/progit2/book/03-git-branching/sections/branch-managem
37223712 [source,console]
37233713 ----
37243714 $ git branch -v
3725-- iss53 93b412c Fix javascript issue
3726-+ iss53 93b412c fix javascript issue
3715+- iss53 93b412c fix javascript issue
3716++ iss53 93b412c Fix javascript issue
37273717 * master 7a98805 Merge branch 'iss53'
3728-- testing 782fd34 Add scott to the author list in the readme
3729-+ testing 782fd34 add scott to the author list in the readmes
3718+- testing 782fd34 add scott to the author list in the readmes
3719++ testing 782fd34 Add scott to the author list in the readme
37303720 ----
37313721
37323722 The useful `--merged` and `--no-merged` options can filter this list to branches that you have or have not yet merged into the branch you're currently on.
3733-@@ -59,126 +59,3 @@
3723+@@ -59,3 +59,126 @@
37343724 ----
37353725
37363726 If you really do want to delete the branch and lose that work, you can force it with `-D`, as the helpful message points out.
3737--
3738--[TIP]
3739--====
3740--The options described above, `--merged` and `--no-merged` will, if not given a commit or branch name as an argument, show you what is, respectively, merged or not merged into your _current_ branch.
3741--
3742--You can always provide an additional argument to ask about the merge state with respect to some other branch without checking that other branch out first, as in, what is not merged into the `master` branch?
3743--[source,console]
3744------
3745--$ git checkout testing
3746--$ git branch --no-merged master
3747-- topicA
3748-- featureB
3749------
3750--====
3751--
3752--==== Changing a branch name
3753--
3754--[CAUTION]
3755--====
3756--Do not rename branches that are still in use by other collaborators.
3757--Do not rename a branch like master/main/mainline without having read the section "Changing the master branch name".
3758--====
3759--
3760--Suppose you have a branch that is called _bad-branch-name_ and you want to change it to _corrected-branch-name_, while keeping all history.
3761--You also want to change the branch name on the remote (GitHub, GitLab, other server).
3762--How do you do this?
3763--
3764--Rename the branch locally with the `git branch --move` command:
3765--
3766--[source, console]
3767------
3768--$ git branch --move bad-branch-name corrected-branch-name
3769------
3770--
3771--This replaces your bad-branch-name with corrected-branch-name, but this change is only local for now.
3772--To let others see the corrected branch on the remote, push it:
3773--
3774--[source,console]
3775------
3776--$ git push --set-upstream origin corrected-branch-name
3777------
3778--
3779--Now we'll take a brief look at where we are now:
3780--
3781--[source, console]
3782------
3783--$ git branch --all
3784--* corrected-branch-name
3785-- main
3786-- remotes/origin/bad-branch-name
3787-- remotes/origin/corrected-branch-name
3788-- remotes/origin/main
3789------
3790--
3791--Notice that you're on the branch corrected-branch-name.
3792--The corrected branch is available on the remote.
3793--However the bad branch is also still present on the remote.
3794--You can delete the bad branch from the remote:
3795--
3796--[source,console]
3797------
3798--$ git push origin --delete bad-branch-name
3799------
3800--
3801--Now the bad branch name is fully replaced with the corrected branch name.
3802--
3803--===== Changing the master branch name
3804--
3805--[WARNING]
3806--====
3807--Changing the name of a branch like master/main/mainline/default will break the integrations, services, helper utilities and build/release scripts that your repository uses.
3808--Before you do this, make sure you consult with your collaborators.
3809--Also make sure you do a thorough search through your repo and update any references to the old branch name in your code or scripts.
3810--====
3811--
3812--Rename your local _master_ branch into _main_ with the following command
3813--
3814--[source,console]
3815------
3816--$ git branch --move master main
3817------
3818--
3819--There's no _master_ branch locally anymore, because it's renamed to the _main_ branch.
3820--
3821--To let others see the new _main_ branch, you need to push it to the remote.
3822--This makes the renamed branch available on the remote.
3823--
3824--[source,console]
3825------
3826--$ git push --set-upstream origin main
3827------
3828--
3829--Now we end up with the following state:
3830--
3831--[source,console]
3832------
3833--git branch --all
3834--* main
3835-- remotes/origin/HEAD -> origin/master
3836-- remotes/origin/main
3837-- remotes/origin/master
3838------
3839--
3840--Your local _master_ branch is gone, as it's replaced with the _main_ branch.
3841--The _main_ branch is also available on the remote.
3842--But the remote still has a _master_ branch.
3843--Other collaborators will continue to use the _master_ branch as the base of their work, until you make some further changes.
3844--
3845--Now you have a few more tasks in front of you to complete the transition:
3846--
3847--* Any projects that depend on this one will need to update their code and/or configuration.
3848--* Update any test-runner configuration files.
3849--* Adjust build and release scripts.
3850--* Redirect settings on your repo host for things like the repo's default branch, merge rules, and other things that match branch names.
3851--* Update references to the old branch in documentation.
3852--* Close or merge any pull requests that target the old branch.
3853--
3854--After you've done all these tasks, and are certain the main branch performs just as the _master_ branch, you can delete the _master_ branch:
3855--
3856--[source, console]
3857------
3858--$ git push origin --delete master
3859------
3860-diff -au ../../git/progit2/progit2/book/03-git-branching/sections/nutshell.asc /tmp/book/03-git-branching/sections/nutshell.asc.tmp
3861---- ../../git/progit2/progit2/book/03-git-branching/sections/nutshell.asc 2020-09-26 08:56:07.950296410 +0900
3862-+++ /tmp/book/03-git-branching/sections/nutshell.asc.tmp 2020-10-25 09:24:25.667967234 +0900
3863-@@ -1,41 +1,34 @@
3864--[[_git_branches_overview]]
3865-+[[r_git_branches_overview]]
3727++
3728++[TIP]
3729++====
3730++The options described above, `--merged` and `--no-merged` will, if not given a commit or branch name as an argument, show you what is, respectively, merged or not merged into your _current_ branch.
3731++
3732++You can always provide an additional argument to ask about the merge state with respect to some other branch without checking that other branch out first, as in, what is not merged into the `master` branch?
3733++[source,console]
3734++----
3735++$ git checkout testing
3736++$ git branch --no-merged master
3737++ topicA
3738++ featureB
3739++----
3740++====
3741++
3742++==== Changing a branch name
3743++
3744++[CAUTION]
3745++====
3746++Do not rename branches that are still in use by other collaborators.
3747++Do not rename a branch like master/main/mainline without having read the section "Changing the master branch name".
3748++====
3749++
3750++Suppose you have a branch that is called _bad-branch-name_ and you want to change it to _corrected-branch-name_, while keeping all history.
3751++You also want to change the branch name on the remote (GitHub, GitLab, other server).
3752++How do you do this?
3753++
3754++Rename the branch locally with the `git branch --move` command:
3755++
3756++[source, console]
3757++----
3758++$ git branch --move bad-branch-name corrected-branch-name
3759++----
3760++
3761++This replaces your bad-branch-name with corrected-branch-name, but this change is only local for now.
3762++To let others see the corrected branch on the remote, push it:
3763++
3764++[source,console]
3765++----
3766++$ git push --set-upstream origin corrected-branch-name
3767++----
3768++
3769++Now we'll take a brief look at where we are now:
3770++
3771++[source, console]
3772++----
3773++$ git branch --all
3774++* corrected-branch-name
3775++ main
3776++ remotes/origin/bad-branch-name
3777++ remotes/origin/corrected-branch-name
3778++ remotes/origin/main
3779++----
3780++
3781++Notice that you're on the branch corrected-branch-name.
3782++The corrected branch is available on the remote.
3783++However the bad branch is also still present on the remote.
3784++You can delete the bad branch from the remote:
3785++
3786++[source,console]
3787++----
3788++$ git push origin --delete bad-branch-name
3789++----
3790++
3791++Now the bad branch name is fully replaced with the corrected branch name.
3792++
3793++===== Changing the master branch name
3794++
3795++[WARNING]
3796++====
3797++Changing the name of a branch like master/main/mainline/default will break the integrations, services, helper utilities and build/release scripts that your repository uses.
3798++Before you do this, make sure you consult with your collaborators.
3799++Also make sure you do a thorough search through your repo and update any references to the old branch name in your code or scripts.
3800++====
3801++
3802++Rename your local _master_ branch into _main_ with the following command
3803++
3804++[source,console]
3805++----
3806++$ git branch --move master main
3807++----
3808++
3809++There's no _master_ branch locally anymore, because it's renamed to the _main_ branch.
3810++
3811++To let others see the new _main_ branch, you need to push it to the remote.
3812++This makes the renamed branch available on the remote.
3813++
3814++[source,console]
3815++----
3816++$ git push --set-upstream origin main
3817++----
3818++
3819++Now we end up with the following state:
3820++
3821++[source,console]
3822++----
3823++git branch --all
3824++* main
3825++ remotes/origin/HEAD -> origin/master
3826++ remotes/origin/main
3827++ remotes/origin/master
3828++----
3829++
3830++Your local _master_ branch is gone, as it's replaced with the _main_ branch.
3831++The _main_ branch is also available on the remote.
3832++But the remote still has a _master_ branch.
3833++Other collaborators will continue to use the _master_ branch as the base of their work, until you make some further changes.
3834++
3835++Now you have a few more tasks in front of you to complete the transition:
3836++
3837++* Any projects that depend on this one will need to update their code and/or configuration.
3838++* Update any test-runner configuration files.
3839++* Adjust build and release scripts.
3840++* Redirect settings on your repo host for things like the repo's default branch, merge rules, and other things that match branch names.
3841++* Update references to the old branch in documentation.
3842++* Close or merge any pull requests that target the old branch.
3843++
3844++After you've done all these tasks, and are certain the main branch performs just as the _master_ branch, you can delete the _master_ branch:
3845++
3846++[source, console]
3847++----
3848++$ git push origin --delete master
3849++----
3850+diff -au /tmp/book/03-git-branching/sections/nutshell.asc.tmp ../../git/progit2/progit2/book/03-git-branching/sections/nutshell.asc
3851+--- /tmp/book/03-git-branching/sections/nutshell.asc.tmp 2020-10-25 11:05:02.202637091 +0900
3852++++ ../../git/progit2/progit2/book/03-git-branching/sections/nutshell.asc 2020-09-26 08:56:07.950296410 +0900
3853+@@ -1,34 +1,41 @@
3854+-[[r_git_branches_overview]]
3855++[[_git_branches_overview]]
38663856 === Branches in a Nutshell
38673857
38683858 To really understand the way Git does branching, we need to take a step back and examine how Git stores its data.
38693859
3870--As you may remember from <<ch01-getting-started#what_is_git_section>>, Git doesn't store data as a series of changesets or differences, but instead as a series of _snapshots_.
3871-+As you may remember from <<ch01-introduction#ch01-introduction>>, Git doesn't store data as a series of changesets or differences, but instead as a series of snapshots.
3860+-As you may remember from <<ch01-introduction#ch01-introduction>>, Git doesn't store data as a series of changesets or differences, but instead as a series of snapshots.
3861++As you may remember from <<ch01-getting-started#what_is_git_section>>, Git doesn't store data as a series of changesets or differences, but instead as a series of _snapshots_.
38723862
38733863 When you make a commit, Git stores a commit object that contains a pointer to the snapshot of the content you staged.
3874--This object also contains the author's name and email address, 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.
3875-+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.
3864+-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.
3865++This object also contains the author's name and email address, 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.
38763866
38773867 To visualize this, let's assume that you have a directory containing three files, and you stage them all and commit.
3878--Staging the files computes a checksum for each one (the SHA-1 hash we mentioned in <<ch01-getting-started#what_is_git_section>>), stores that version of the file in the Git repository (Git refers to them as _blobs_), and adds that checksum to the staging area:
3879-+Staging the files checksums each one (the SHA-1 hash we mentioned in <<ch01-introduction#ch01-introduction>>), stores that version of the file in the Git repository (Git refers to them as blobs), and adds that checksum to the staging area:
3868+-Staging the files checksums each one (the SHA-1 hash we mentioned in <<ch01-introduction#ch01-introduction>>), stores that version of the file in the Git repository (Git refers to them as blobs), and adds that checksum to the staging area:
3869++Staging the files computes a checksum for each one (the SHA-1 hash we mentioned in <<ch01-getting-started#what_is_git_section>>), stores that version of the file in the Git repository (Git refers to them as _blobs_), and adds that checksum to the staging area:
38803870
3881--[source,console]
3882------
3883--$ git add README test.rb LICENSE
3884--$ git commit -m 'Initial commit'
3885------
3886--
3887--When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores them as a tree object in the Git repository.
3888-+When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores those tree objects in the Git repository.
3871+-When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores those tree objects in the Git repository.
3872++[source,console]
3873++----
3874++$ git add README test.rb LICENSE
3875++$ git commit -m 'Initial commit'
3876++----
3877++
3878++When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores them as a tree object in the Git repository.
38893879 Git then creates a commit object that has the metadata and a pointer to the root project tree so it can re-create that snapshot when needed.(((git commands, commit)))
38903880
3891--Your Git repository now contains five objects: three _blobs_ (each representing the contents of one of the three files), one _tree_ that lists the contents of the directory and specifies which file names are stored as which blobs, and one _commit_ with the pointer to that root tree and all the commit metadata.
3892-+Your Git repository now contains five objects: one blob for the contents of each of your three files, one tree that lists the contents of the directory and specifies which file names are stored as which blobs, and one commit with the pointer to that root tree and all the commit metadata.
3881+-Your Git repository now contains five objects: one blob for the contents of each of your three files, one tree that lists the contents of the directory and specifies which file names are stored as which blobs, and one commit with the pointer to that root tree and all the commit metadata.
3882++Your Git repository now contains five objects: three _blobs_ (each representing the contents of one of the three files), one _tree_ that lists the contents of the directory and specifies which file names are stored as which blobs, and one _commit_ with the pointer to that root tree and all the commit metadata.
38933883
38943884 .A commit and its tree
3895--image::images/commit-and-tree.png[A commit and its tree]
3896-+image::images/commit-and-tree.png[A commit and its tree.]
3885+-image::images/commit-and-tree.png[A commit and its tree.]
3886++image::images/commit-and-tree.png[A commit and its tree]
38973887
38983888 If you make some changes and commit again, the next commit stores a pointer to the commit that came immediately before it.
38993889
39003890 .Commits and their parents
3901--image::images/commits-and-parents.png[Commits and their parents]
3902-+image::images/commits-and-parents.png[Commits and their parents.]
3891+-image::images/commits-and-parents.png[Commits and their parents.]
3892++image::images/commits-and-parents.png[Commits and their parents]
39033893
39043894 A branch in Git is simply a lightweight movable pointer to one of these commits.
39053895 The default branch name in Git is `master`.
39063896 As you start making commits, you're given a `master` branch that points to the last commit you made.
3907--Every time you commit, the `master` branch pointer moves forward automatically.
3908-+Every time you commit, it moves forward automatically.
3897+-Every time you commit, it moves forward automatically.
3898++Every time you commit, the `master` branch pointer moves forward automatically.
39093899
3910--[NOTE]
3900++[NOTE]
39113901 ====
39123902 The ``master'' branch in Git is not a special branch.(((master)))
39133903 It is exactly like any other branch.
3914-@@ -43,108 +36,62 @@
3904+@@ -36,62 +43,108 @@
39153905 ====
39163906
39173907 .A branch and its commit history
3918--image::images/branch-and-history.png[A branch and its commit history]
3919-+image::images/branch-and-history.png[A branch and its commit history.]
3908+-image::images/branch-and-history.png[A branch and its commit history.]
3909++image::images/branch-and-history.png[A branch and its commit history]
39203910
3921--[[_create_new_branch]]
3911++[[_create_new_branch]]
39223912 ==== Creating a New Branch
39233913
3924--(((branches, creating)))
3925--What happens when you create a new branch?
3926-+What happens if you create a new branch?
3914+-What happens if you create a new branch?
3915++(((branches, creating)))
3916++What happens when you create a new branch?
39273917 Well, doing so creates a new pointer for you to move around.
3928--Let's say you want to create a new branch called `testing`.
3929-+Let's say you create a new branch called testing.
3918+-Let's say you create a new branch called testing.
3919++Let's say you want to create a new branch called `testing`.
39303920 You do this with the `git branch` command:(((git commands, branch)))
39313921
3932--[source,console]
3933------
3934--$ git branch testing
3935------
3936--
3922++[source,console]
3923++----
3924++$ git branch testing
3925++----
3926++
39373927 This creates a new pointer to the same commit you're currently on.
39383928
39393929 .Two branches pointing into the same series of commits
3940--image::images/two-branches.png[Two branches pointing into the same series of commits]
3941-+image::images/two-branches.png[Two branches pointing into the same series of commits.]
3930+-image::images/two-branches.png[Two branches pointing into the same series of commits.]
3931++image::images/two-branches.png[Two branches pointing into the same series of commits]
39423932
39433933 How does Git know what branch you're currently on?
39443934 It keeps a special pointer called `HEAD`.
39453935 Note that this is a lot different than the concept of `HEAD` in other VCSs you may be used to, such as Subversion or CVS.
39463936 In Git, this is a pointer to the local branch you're currently on.
39473937 In this case, you're still on `master`.
3948--The `git branch` command only _created_ a new branch -- it didn't switch to that branch.
3949-+The `git branch` command only _created_ a new branch – it didn't switch to that branch.
3938+-The `git branch` command only _created_ a new branch – it didn't switch to that branch.
3939++The `git branch` command only _created_ a new branch -- it didn't switch to that branch.
39503940
39513941 .HEAD pointing to a branch
3952--image::images/head-to-master.png[HEAD pointing to a branch]
3953-+image::images/head-to-master.png[HEAD pointing to a branch.]
3942+-image::images/head-to-master.png[HEAD pointing to a branch.]
3943++image::images/head-to-master.png[HEAD pointing to a branch]
39543944
39553945 You can easily see this by running a simple `git log` command that shows you where the branch pointers are pointing.
39563946 This option is called `--decorate`.
39573947
3958--[source,console]
3959------
3960--$ git log --oneline --decorate
3961--f30ab (HEAD -> master, testing) Add feature #32 - ability to add new formats to the central interface
3962--34ac2 Fix bug #1328 - stack overflow under certain conditions
3963--98ca9 Initial commit
3964------
3965--
3966--You can see the `master` and `testing` branches that are right there next to the `f30ab` commit.
3967-+You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit.
3948+-You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit.
3949++[source,console]
3950++----
3951++$ git log --oneline --decorate
3952++f30ab (HEAD -> master, testing) Add feature #32 - ability to add new formats to the central interface
3953++34ac2 Fix bug #1328 - stack overflow under certain conditions
3954++98ca9 Initial commit
3955++----
3956++
3957++You can see the `master` and `testing` branches that are right there next to the `f30ab` commit.
39683958
3969--[[_switching_branches]]
3959++[[_switching_branches]]
39703960 ==== Switching Branches
39713961
3972--(((branches, switching)))
3962++(((branches, switching)))
39733963 To switch to an existing branch, you run the `git checkout` command.(((git commands, checkout)))
39743964 Let's switch to the new `testing` branch:
39753965
3976--[source,console]
3977------
3978--$ git checkout testing
3979------
3980--
3966++[source,console]
3967++----
3968++$ git checkout testing
3969++----
3970++
39813971 This moves `HEAD` to point to the `testing` branch.
39823972
39833973 .HEAD points to the current branch
3984--image::images/head-to-testing.png[HEAD points to the current branch]
3985-+image::images/head-to-testing.png[HEAD points to the current branch.]
3974+-image::images/head-to-testing.png[HEAD points to the current branch.]
3975++image::images/head-to-testing.png[HEAD points to the current branch]
39863976
39873977 What is the significance of that?
39883978 Well, let's do another commit:
39893979
3990--[source,console]
3991------
3992--$ vim test.rb
3993--$ git commit -a -m 'made a change'
3994------
3995--
3980++[source,console]
3981++----
3982++$ vim test.rb
3983++$ git commit -a -m 'made a change'
3984++----
3985++
39963986 .The HEAD branch moves forward when a commit is made
3997--image::images/advance-testing.png[The HEAD branch moves forward when a commit is made]
3998-+image::images/advance-testing.png[The HEAD branch moves forward when a commit is made.]
3987+-image::images/advance-testing.png[The HEAD branch moves forward when a commit is made.]
3988++image::images/advance-testing.png[The HEAD branch moves forward when a commit is made]
39993989
40003990 This is interesting, because now your `testing` branch has moved forward, but your `master` branch still points to the commit you were on when you ran `git checkout` to switch branches.
40013991 Let's switch back to the `master` branch:
40023992
4003--[source,console]
4004------
4005--$ git checkout master
4006------
4007--
4008--[NOTE]
4009--.`git log` doesn't show _all_ the branches _all_ the time
4010--====
4011--If you were to run `git log` right now, you might wonder where the "testing" branch you just created went, as it would not appear in the output.
4012--
4013--The branch hasn't disappeared; Git just doesn't know that you're interested in that branch and it is trying to show you what it thinks you're interested in.
4014--In other words, by default, `git log` will only show commit history below the branch you've checked out.
4015--
4016--To show commit history for the desired branch you have to explicitly specify it: `git log testing`.
4017--To show all of the branches, add `--all` to your `git log` command.
4018--====
4019--
3993++[source,console]
3994++----
3995++$ git checkout master
3996++----
3997++
3998++[NOTE]
3999++.`git log` doesn't show _all_ the branches _all_ the time
4000++====
4001++If you were to run `git log` right now, you might wonder where the "testing" branch you just created went, as it would not appear in the output.
4002++
4003++The branch hasn't disappeared; Git just doesn't know that you're interested in that branch and it is trying to show you what it thinks you're interested in.
4004++In other words, by default, `git log` will only show commit history below the branch you've checked out.
4005++
4006++To show commit history for the desired branch you have to explicitly specify it: `git log testing`.
4007++To show all of the branches, add `--all` to your `git log` command.
4008++====
4009++
40204010 .HEAD moves when you checkout
4021--image::images/checkout-master.png[HEAD moves when you checkout]
4022-+image::images/checkout-master.png[HEAD moves when you checkout.]
4011+-image::images/checkout-master.png[HEAD moves when you checkout.]
4012++image::images/checkout-master.png[HEAD moves when you checkout]
40234013
40244014 That command did two things.
40254015 It moved the HEAD pointer back to point to the `master` branch, and it reverted the files in your working directory back to the snapshot that `master` points to.
40264016 This also means the changes you make from this point forward will diverge from an older version of the project.
40274017 It essentially rewinds the work you've done in your `testing` branch so you can go in a different direction.
40284018
4029--[NOTE]
4019++[NOTE]
40304020 .Switching branches changes files in your working directory
40314021 ====
40324022 It's important to note that when you switch branches in Git, files in your working directory will change.
4033-@@ -154,36 +101,18 @@
4023+@@ -101,18 +154,36 @@
40344024
40354025 Let's make a few changes and commit again:
40364026
4037--[source,console]
4038------
4039--$ vim test.rb
4040--$ git commit -a -m 'made other changes'
4041------
4042--
4043--Now your project history has diverged (see <<divergent_history>>).
4044-+Now your project history has diverged (see <<rdivergent_history>>).
4027+-Now your project history has diverged (see <<rdivergent_history>>).
4028++[source,console]
4029++----
4030++$ vim test.rb
4031++$ git commit -a -m 'made other changes'
4032++----
4033++
4034++Now your project history has diverged (see <<divergent_history>>).
40454035 You created and switched to a branch, did some work on it, and then switched back to your main branch and did other work.
40464036 Both of those changes are isolated in separate branches: you can switch back and forth between the branches and merge them together when you're ready.
40474037 And you did all that with simple `branch`, `checkout`, and `commit` commands.
40484038
4049--[[divergent_history]]
4039++[[divergent_history]]
40504040 .Divergent history
4051--image::images/advance-master.png[Divergent history]
4052-+image::images/advance-master.png[Divergent history.]
4041+-image::images/advance-master.png[Divergent history.]
4042++image::images/advance-master.png[Divergent history]
40534043
40544044 You can also see this easily with the `git log` command.
40554045 If you run `git log --oneline --decorate --graph --all` it will print out the history of your commits, showing where your branch pointers are and how your history has diverged.
40564046
4057--[source,console]
4058------
4059--$ git log --oneline --decorate --graph --all
4060--* c2b9e (HEAD, master) Made other changes
4061--| * 87ab2 (testing) Made a change
4062--|/
4063--* f30ab Add feature #32 - ability to add new formats to the central interface
4064--* 34ac2 Fix bug #1328 - stack overflow under certain conditions
4065--* 98ca9 initial commit of my project
4066------
4067--
4068--Because a branch in Git is actually a simple file that contains the 40 character SHA-1 checksum of the commit it points to, branches are cheap to create and destroy.
4069-+Because a branch in Git is in actuality a simple file that contains the 40 character SHA-1 checksum of the commit it points to, branches are cheap to create and destroy.
4047+-Because a branch in Git is in actuality a simple file that contains the 40 character SHA-1 checksum of the commit it points to, branches are cheap to create and destroy.
4048++[source,console]
4049++----
4050++$ git log --oneline --decorate --graph --all
4051++* c2b9e (HEAD, master) Made other changes
4052++| * 87ab2 (testing) Made a change
4053++|/
4054++* f30ab Add feature #32 - ability to add new formats to the central interface
4055++* 34ac2 Fix bug #1328 - stack overflow under certain conditions
4056++* 98ca9 initial commit of my project
4057++----
4058++
4059++Because a branch in Git is actually a simple file that contains the 40 character SHA-1 checksum of the commit it points to, branches are cheap to create and destroy.
40704060 Creating a new branch is as quick and simple as writing 41 bytes to a file (40 characters and a newline).
40714061
40724062 This is in sharp contrast to the way most older VCS tools branch, which involves copying all of the project's files into a second directory.
4073-@@ -192,18 +121,3 @@
4063+@@ -121,3 +192,18 @@
40744064 These features help encourage developers to create and use branches often.
40754065
40764066 Let's see why you should do so.
4077--
4078--[NOTE]
4079--.Creating a new branch and switching to it at the same time
4080--====
4081--It's typical to create a new branch and want to switch to that new branch at the same time -- this can be done in one operation with `git checkout -b <newbranchname>`.
4082--====
4083--
4084--[NOTE]
4085--====
4086--From Git version 2.23 onwards you can use `git switch` instead of `git checkout` to:
4087--
4088--- Switch to an existing branch: `git switch testing-branch`.
4089--- Create a new branch and switch to it: `git switch -c new-branch`. The `-c` flag stands for create, you can also use the full flag: `--create`.
4090--- Return to your previously checked out branch: `git switch -`.
4091--====
4092-diff -au ../../git/progit2/progit2/book/03-git-branching/sections/rebasing.asc /tmp/book/03-git-branching/sections/rebasing.asc.tmp
4093---- ../../git/progit2/progit2/book/03-git-branching/sections/rebasing.asc 2020-08-17 16:38:51.075694960 +0900
4094-+++ /tmp/book/03-git-branching/sections/rebasing.asc.tmp 2020-10-25 09:24:25.673967517 +0900
4095-@@ -1,144 +1,94 @@
4096--[[_rebasing]]
4097-+[[r_rebasing]]
4067++
4068++[NOTE]
4069++.Creating a new branch and switching to it at the same time
4070++====
4071++It's typical to create a new branch and want to switch to that new branch at the same time -- this can be done in one operation with `git checkout -b <newbranchname>`.
4072++====
4073++
4074++[NOTE]
4075++====
4076++From Git version 2.23 onwards you can use `git switch` instead of `git checkout` to:
4077++
4078++- Switch to an existing branch: `git switch testing-branch`.
4079++- Create a new branch and switch to it: `git switch -c new-branch`. The `-c` flag stands for create, you can also use the full flag: `--create`.
4080++- Return to your previously checked out branch: `git switch -`.
4081++====
4082+diff -au /tmp/book/03-git-branching/sections/rebasing.asc.tmp ../../git/progit2/progit2/book/03-git-branching/sections/rebasing.asc
4083+--- /tmp/book/03-git-branching/sections/rebasing.asc.tmp 2020-10-25 11:05:02.207637372 +0900
4084++++ ../../git/progit2/progit2/book/03-git-branching/sections/rebasing.asc 2020-08-17 16:38:51.075694960 +0900
4085+@@ -1,94 +1,144 @@
4086+-[[r_rebasing]]
4087++[[_rebasing]]
40984088 === Rebasing
40994089
4100--(((rebasing)))
4090++(((rebasing)))
41014091 In Git, there are two main ways to integrate changes from one branch into another: the `merge` and the `rebase`.
41024092 In this section you'll learn what rebasing is, how to do it, why it's a pretty amazing tool, and in what cases you won't want to use it.
41034093
41044094 ==== The Basic Rebase
41054095
4106--If you go back to an earlier example from <<_basic_merging>>, you can see that you diverged your work and made commits on two different branches.
4107-+If you go back to an earlier example from <<r_basic_merging>>, you can see that you diverged your work and made commits on two different branches.
4096+-If you go back to an earlier example from <<r_basic_merging>>, you can see that you diverged your work and made commits on two different branches.
4097++If you go back to an earlier example from <<_basic_merging>>, you can see that you diverged your work and made commits on two different branches.
41084098
41094099 .Simple divergent history
4110--image::images/basic-rebase-1.png[Simple divergent history]
4111-+image::images/basic-rebase-1.png[Simple divergent history.]
4100+-image::images/basic-rebase-1.png[Simple divergent history.]
4101++image::images/basic-rebase-1.png[Simple divergent history]
41124102
41134103 The easiest way to integrate the branches, as we've already covered, is the `merge` command.
41144104 It performs a three-way merge between the two latest branch snapshots (`C3` and `C4`) and the most recent common ancestor of the two (`C2`), creating a new snapshot (and commit).
41154105
4116--[[rebasing-merging-example]]
4106++[[rebasing-merging-example]]
41174107 .Merging to integrate diverged work history
4118--image::images/basic-rebase-2.png[Merging to integrate diverged work history]
4119-+image::images/basic-rebase-2.png[Merging to integrate diverged work history.]
4108+-image::images/basic-rebase-2.png[Merging to integrate diverged work history.]
4109++image::images/basic-rebase-2.png[Merging to integrate diverged work history]
41204110
41214111 However, there is another way: you can take the patch of the change that was introduced in `C4` and reapply it on top of `C3`.
41224112 In Git, this is called _rebasing_.
4123--With the `rebase` command, you can take all the changes that were committed on one branch and replay them on a different branch.(((git commands, rebase)))
4124-+With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.(((git commands, rebase)))
4113+-With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.(((git commands, rebase)))
4114++With the `rebase` command, you can take all the changes that were committed on one branch and replay them on a different branch.(((git commands, rebase)))
41254115
4126--For this example, you would check out the `experiment` branch, and then rebase it onto the `master` branch as follows:
4127-+In this example, you'd run the following:
4116+-In this example, you'd run the following:
4117++For this example, you would check out the `experiment` branch, and then rebase it onto the `master` branch as follows:
41284118
4129--[source,console]
4130------
4131--$ git checkout experiment
4132--$ git rebase master
4133--First, rewinding head to replay your work on top of it...
4134--Applying: added staged command
4135------
4136--
4137--This operation works by going to the common ancestor of the two branches (the one you're on and the one you're rebasing onto), getting the diff introduced by each commit of the branch you're on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn.
4138-+It works by going to the common ancestor of the two branches (the one you're on and the one you're rebasing onto), getting the diff introduced by each commit of the branch you're on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn.
4119+-It works by going to the common ancestor of the two branches (the one you're on and the one you're rebasing onto), getting the diff introduced by each commit of the branch you're on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn.
4120++[source,console]
4121++----
4122++$ git checkout experiment
4123++$ git rebase master
4124++First, rewinding head to replay your work on top of it...
4125++Applying: added staged command
4126++----
4127++
4128++This operation works by going to the common ancestor of the two branches (the one you're on and the one you're rebasing onto), getting the diff introduced by each commit of the branch you're on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn.
41394129
41404130 .Rebasing the change introduced in `C4` onto `C3`
4141--image::images/basic-rebase-3.png[Rebasing the change introduced in `C4` onto `C3`]
4142-+image::images/basic-rebase-3.png[Rebasing the change introduced in `C4` onto `C3`.]
4131+-image::images/basic-rebase-3.png[Rebasing the change introduced in `C4` onto `C3`.]
4132++image::images/basic-rebase-3.png[Rebasing the change introduced in `C4` onto `C3`]
41434133
41444134 At this point, you can go back to the `master` branch and do a fast-forward merge.
41454135
4146--[source,console]
4147------
4148--$ git checkout master
4149--$ git merge experiment
4150------
4151--
4152--.Fast-forwarding the `master` branch
4153--image::images/basic-rebase-4.png[Fast-forwarding the `master` branch]
4154-+.Fast-forwarding the master branch
4155-+image::images/basic-rebase-4.png[Fast-forwarding the master branch.]
4136+-.Fast-forwarding the master branch
4137+-image::images/basic-rebase-4.png[Fast-forwarding the master branch.]
4138++[source,console]
4139++----
4140++$ git checkout master
4141++$ git merge experiment
4142++----
4143++
4144++.Fast-forwarding the `master` branch
4145++image::images/basic-rebase-4.png[Fast-forwarding the `master` branch]
41564146
4157--Now, the snapshot pointed to by `C4'` is exactly the same as the one that was pointed to by `C5` in <<rebasing-merging-example,the merge example>>.
4158-+Now, the snapshot pointed to by `C4'` is exactly the same as the one that was pointed to by `C5` in the merge example.
4147+-Now, the snapshot pointed to by `C4'` is exactly the same as the one that was pointed to by `C5` in the merge example.
4148++Now, the snapshot pointed to by `C4'` is exactly the same as the one that was pointed to by `C5` in <<rebasing-merging-example,the merge example>>.
41594149 There is no difference in the end product of the integration, but rebasing makes for a cleaner history.
41604150 If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel.
41614151
4162--Often, you'll do this to make sure your commits apply cleanly on a remote branch -- perhaps in a project to which you're trying to contribute but that you don't maintain.
4163-+Often, you'll do this to make sure your commits apply cleanly on a remote branch – perhaps in a project to which you're trying to contribute but that you don't maintain.
4152+-Often, you'll do this to make sure your commits apply cleanly on a remote branch – perhaps in a project to which you're trying to contribute but that you don't maintain.
4153++Often, you'll do this to make sure your commits apply cleanly on a remote branch -- perhaps in a project to which you're trying to contribute but that you don't maintain.
41644154 In this case, you'd do your work in a branch and then rebase your work onto `origin/master` when you were ready to submit your patches to the main project.
4165--That way, the maintainer doesn't have to do any integration work -- just a fast-forward or a clean apply.
4166-+That way, the maintainer doesn't have to do any integration work – just a fast-forward or a clean apply.
4155+-That way, the maintainer doesn't have to do any integration work – just a fast-forward or a clean apply.
4156++That way, the maintainer doesn't have to do any integration work -- just a fast-forward or a clean apply.
41674157
4168--Note that the snapshot pointed to by the final commit you end up with, whether it's the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot -- it's only the history that is different.
4169-+Note that the snapshot pointed to by the final commit you end up with, whether it's the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot – it's only the history that is different.
4158+-Note that the snapshot pointed to by the final commit you end up with, whether it's the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot – it's only the history that is different.
4159++Note that the snapshot pointed to by the final commit you end up with, whether it's the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot -- it's only the history that is different.
41704160 Rebasing replays changes from one line of work onto another in the order they were introduced, whereas merging takes the endpoints and merges them together.
41714161
41724162 ==== More Interesting Rebases
41734163
41744164 You can also have your rebase replay on something other than the rebase target branch.
4175--Take a history like <<rbdiag_e>>, for example.
4176-+Take a history like <<rrbdiag_e>>, for example.
4165+-Take a history like <<rrbdiag_e>>, for example.
4166++Take a history like <<rbdiag_e>>, for example.
41774167 You branched a topic branch (`server`) to add some server-side functionality to your project, and made a commit.
41784168 Then, you branched off that to make the client-side changes (`client`) and committed a few times.
41794169 Finally, you went back to your server branch and did a few more commits.
41804170
4181--[[rbdiag_e]]
4171++[[rbdiag_e]]
41824172 .A history with a topic branch off another topic branch
4183--image::images/interesting-rebase-1.png[A history with a topic branch off another topic branch]
4184-+image::images/interesting-rebase-1.png[A history with a topic branch off another topic branch.]
4173+-image::images/interesting-rebase-1.png[A history with a topic branch off another topic branch.]
4174++image::images/interesting-rebase-1.png[A history with a topic branch off another topic branch]
41854175
41864176 Suppose you decide that you want to merge your client-side changes into your mainline for a release, but you want to hold off on the server-side changes until it's tested further.
4187--You can take the changes on `client` that aren't on `server` (`C8` and `C9`) and replay them on your `master` branch by using the `--onto` option of `git rebase`:
4188-+You can take the changes on client that aren't on server (`C8` and `C9`) and replay them on your `master` branch by using the `--onto` option of `git rebase`:
4177+-You can take the changes on client that aren't on server (`C8` and `C9`) and replay them on your `master` branch by using the `--onto` option of `git rebase`:
4178++You can take the changes on `client` that aren't on `server` (`C8` and `C9`) and replay them on your `master` branch by using the `--onto` option of `git rebase`:
41894179
4190--[source,console]
4191------
4192--$ git rebase --onto master server client
4193------
4194--
4195--This basically says, ``Take the `client` branch, figure out the patches since it diverged from the `server` branch, and replay these patches in the `client` branch as if it was based directly off the `master` branch instead.''
4196-+This basically says, ``Check out the client branch, figure out the patches from the common ancestor of the `client` and `server` branches, and then replay them onto `master`.''
4180+-This basically says, ``Check out the client branch, figure out the patches from the common ancestor of the `client` and `server` branches, and then replay them onto `master`.''
4181++[source,console]
4182++----
4183++$ git rebase --onto master server client
4184++----
4185++
4186++This basically says, ``Take the `client` branch, figure out the patches since it diverged from the `server` branch, and replay these patches in the `client` branch as if it was based directly off the `master` branch instead.''
41974187 It's a bit complex, but the result is pretty cool.
41984188
41994189 .Rebasing a topic branch off another topic branch
4200--image::images/interesting-rebase-2.png[Rebasing a topic branch off another topic branch]
4201-+image::images/interesting-rebase-2.png[Rebasing a topic branch off another topic branch.]
4190+-image::images/interesting-rebase-2.png[Rebasing a topic branch off another topic branch.]
4191++image::images/interesting-rebase-2.png[Rebasing a topic branch off another topic branch]
42024192
4203--Now you can fast-forward your `master` branch (see <<rbdiag_g>>):
4204-+Now you can fast-forward your `master` branch (see <<rrbdiag_g>>):
4193+-Now you can fast-forward your `master` branch (see <<rrbdiag_g>>):
4194++Now you can fast-forward your `master` branch (see <<rbdiag_g>>):
42054195
4206--[source,console]
4207------
4208--$ git checkout master
4209--$ git merge client
4210------
4211--
4212--[[rbdiag_g]]
4213--.Fast-forwarding your `master` branch to include the client branch changes
4214--image::images/interesting-rebase-3.png[Fast-forwarding your `master` branch to include the client branch changes]
4215-+.Fast-forwarding your master branch to include the client branch changes
4216-+image::images/interesting-rebase-3.png[Fast-forwarding your master branch to include the client branch changes.]
4217-
4218- Let's say you decide to pull in your server branch as well.
4219--You can rebase the `server` branch onto the `master` branch without having to check it out first by running `git rebase <basebranch> <topicbranch>` -- which checks out the topic branch (in this case, `server`) for you and replays it onto the base branch (`master`):
4220-+You can rebase the server branch onto the `master` branch without having to check it out first by running `git rebase [basebranch] [topicbranch]` – which checks out the topic branch (in this case, `server`) for you and replays it onto the base branch (`master`):
4196+-.Fast-forwarding your master branch to include the client branch changes
4197+-image::images/interesting-rebase-3.png[Fast-forwarding your master branch to include the client branch changes.]
4198++[source,console]
4199++----
4200++$ git checkout master
4201++$ git merge client
4202++----
42214203 +
4222-+This replays your `server` work on top of your `master` work, as shown in <<rrbdiag_h>>.
4204++[[rbdiag_g]]
4205++.Fast-forwarding your `master` branch to include the client branch changes
4206++image::images/interesting-rebase-3.png[Fast-forwarding your `master` branch to include the client branch changes]
42234207
4224--[source,console]
4225------
4226--$ git rebase master server
4227------
4228--
4229--This replays your `server` work on top of your `master` work, as shown in <<rbdiag_h>>.
4208+ Let's say you decide to pull in your server branch as well.
4209+-You can rebase the server branch onto the `master` branch without having to check it out first by running `git rebase [basebranch] [topicbranch]` – which checks out the topic branch (in this case, `server`) for you and replays it onto the base branch (`master`):
42304210 -
4231--[[rbdiag_h]]
4232--.Rebasing your server branch on top of your `master` branch
4233--image::images/interesting-rebase-4.png[Rebasing your server branch on top of your `master` branch]
4234-+.Rebasing your server branch on top of your master branch
4235-+image::images/interesting-rebase-4.png[Rebasing your server branch on top of your master branch.]
4211+-This replays your `server` work on top of your `master` work, as shown in <<rrbdiag_h>>.
4212++You can rebase the `server` branch onto the `master` branch without having to check it out first by running `git rebase <basebranch> <topicbranch>` -- which checks out the topic branch (in this case, `server`) for you and replays it onto the base branch (`master`):
4213+
4214+-.Rebasing your server branch on top of your master branch
4215+-image::images/interesting-rebase-4.png[Rebasing your server branch on top of your master branch.]
4216++[source,console]
4217++----
4218++$ git rebase master server
4219++----
4220++
4221++This replays your `server` work on top of your `master` work, as shown in <<rbdiag_h>>.
4222++
4223++[[rbdiag_h]]
4224++.Rebasing your server branch on top of your `master` branch
4225++image::images/interesting-rebase-4.png[Rebasing your server branch on top of your `master` branch]
42364226
42374227 Then, you can fast-forward the base branch (`master`):
42384228
4239--[source,console]
4240------
4241--$ git checkout master
4242--$ git merge server
4243------
4244--
4245--You can remove the `client` and `server` branches because all the work is integrated and you don't need them anymore, leaving your history for this entire process looking like <<rbdiag_i>>: