Merge branch 'progit:master' into patch-1

HonkingGoose · HonkingGoose · commit e06c02d89fff · 2021-06-04T15:46:28.000+02:00
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -13,10 +13,6 @@ assignees: ''
 <!-- * This bug is about the Pro Git book, version 2, English language. -->
 <!-- * This bug is about the book as found on the [website](https://www.git-scm.com/book/en/v2) or the pdf. -->
 <!-- * If you found an issue in the pdf/epub/mobi files, you've checked if the problem is also present in the Pro Git book on the [website](https://www.git-scm.com/book/en/v2). -->
-<!-- * This bug is **not** about a translation, if so please file a bug with the translation project. You can find a table of translation projects here: [progit2/TRANSLATING.md](https://github.com/progit/progit2/blob/master/TRANSLATING.md) -->
-<!-- * This bug is **not** about the git-scm.com site, if so please file a bug here: [git-scm.com/issues/new](https://github.com/git/git-scm.com/issues/new) -->
-<!-- * This bug is **not** about git the program itself, if so please file a bug here: [git-scm.com/community](https://git-scm.com/community) -->
-<!-- * This bug is **not** about Git for Windows, if so please file a bug here: [git-for-windows/git](https://github.com/git-for-windows/git). -->
 
 **Which version of the book is affected?**
 <!-- It's important for us to know if the problem is in the source or in the tooling for the pdf/epub/mobi files. -->
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,16 @@
+contact_links:
+  - name: Translation bug
+    url: https://github.com/progit/progit2/blob/master/TRANSLATING.md
+    about: Refer to this table to find out where to report translation bugs.
+
+  - name: Report bugs for git-scm.com site
+    url: https://github.com/git/git-scm.com/issues/
+    about: Please report problems with the git-scm.com site here.
+
+  - name: Bug is about Git program itself
+    url: https://git-scm.com/community
+    about: Please report problems with the Git program here.
+
+  - name: Bug is about Git for Windows
+    url: https://github.com/git-for-windows/git/issues
+    about: Please report problems with Git for Windows here.
diff --git a/Gemfile b/Gemfile
@@ -1,16 +1,16 @@
 source 'https://rubygems.org'
 
-gem 'rake', ' 13.0.1'
-gem 'asciidoctor', '2.0.12'
+gem 'rake', '13.0.3'
+gem 'asciidoctor', '2.0.15'
 
-gem 'json', '2.4.1'
-gem 'awesome_print', '1.8.0'
+gem 'json', '2.5.1'
+gem 'awesome_print', '1.9.2'
 
 gem 'asciidoctor-epub3', '1.5.0.alpha.19'
-gem 'asciidoctor-pdf', '1.5.3'
+gem 'asciidoctor-pdf', '1.5.4'
 
 gem 'coderay', '1.1.3'
-gem 'pygments.rb', '1.2.1'
+gem 'pygments.rb', '2.2.0'
 gem 'thread_safe', '0.3.6'
-gem 'epubcheck-ruby', '4.2.4.0'
-gem 'html-proofer', '3.18.2'
+gem 'epubcheck-ruby', '4.2.5.0'
+gem 'html-proofer', '3.19.0'
diff --git a/README.asc b/README.asc
@@ -29,6 +29,27 @@ Converting to PDF...
  -- PDF output at progit.pdf
 ----
 
+You can generate just one of the supported formats (HTML, EPUB, or PDF).
+Use one of the following commands:
+
+To generate the HTML book:
+
+----
+$ bundle exec rake book:build_html
+----
+
+To generate the EPUB book:
+
+----
+$ bundle exec rake book:build_epub
+----
+
+To generate the PDF book:
+
+----
+$ bundle exec rake book:build_pdf
+----
+
 == Signaling an Issue
 
 Before signaling an issue, please check that there isn't already a similar one in the bug tracking system.
diff --git a/Rakefile b/Rakefile
@@ -6,31 +6,84 @@ namespace :book do
     end
   end
 
-  desc 'build basic book formats'
-  task :build do
+  # Variables referenced for build
+  version_string = ENV['TRAVIS_TAG'] || `git describe --tags`.chomp
+  if version_string.empty?
+    version_string = '0'
+  end
+  date_string = Time.now.strftime('%Y-%m-%d')
+  params = "--attribute revnumber='#{version_string}' --attribute revdate='#{date_string}'"
+  header_hash = `git rev-parse --short HEAD`.strip
 
-    begin
-      version_string = ENV['TRAVIS_TAG'] || `git describe --tags`.chomp
-      if version_string.empty?
-        version_string = '0'
+  # Check contributors list
+  # This checks commit hash stored in the header of list against current HEAD
+  def check_contrib
+    if File.exist?('book/contributors.txt')
+      current_head_hash = `git rev-parse --short HEAD`.strip
+      header = `head -n 1 book/contributors.txt`.strip
+      # Match regex, then coerce resulting array to string by join
+      header_hash = header.scan(/[a-f0-9]{7,}/).join
+
+      if header_hash == current_head_hash
+        puts "Hash on header of contributors list (#{header_hash}) matches the current HEAD (#{current_head_hash})"
+      else
+        puts "Hash on header of contributors list (#{header_hash}) does not match the current HEAD (#{current_head_hash}), refreshing"
+        `rm book/contributors.txt`
+        # Reenable and invoke task again
+        Rake::Task['book/contributors.txt'].reenable
+        Rake::Task['book/contributors.txt'].invoke
       end
-      date_string = Time.now.strftime("%Y-%m-%d")
-      params = "--attribute revnumber='#{version_string}' --attribute revdate='#{date_string}'"
-      puts "Generating contributors list"
-      `git shortlog -s | grep -v -E "(Straub|Chacon)" | cut -f 2- | column -c 120 > book/contributors.txt`
+    end
+  end
+
+  desc 'build basic book formats'
+  task :build => [:build_html, :build_epub, :build_pdf] do
+    begin
+        # Run check
+        Rake::Task['book:check'].invoke
 
-      puts "Converting to HTML..."
+        # Rescue to ignore checking errors
+        rescue => e
+        puts e.message
+        puts 'Error when checking books (ignored)'
+    end
+  end
+
+  desc 'build basic book formats (for ci)'
+  task :ci => [:build_html, :build_epub, :build_pdf] do
+      # Run check, but don't ignore any errors
+      Rake::Task['book:check'].invoke
+  end
+
+  desc 'generate contributors list'
+  file 'book/contributors.txt' do
+      puts 'Generating contributors list'
+      `echo "Contributors as of #{header_hash}:\n" > book/contributors.txt`
+      `git shortlog -s | grep -v -E "(Straub|Chacon|dependabot)" | cut -f 2- | column -c 120 >> book/contributors.txt`
+  end
+
+  desc 'build HTML format'
+  task :build_html => 'book/contributors.txt' do
+      check_contrib()
+
+      puts 'Converting to HTML...'
       `bundle exec asciidoctor #{params} -a data-uri progit.asc`
-      puts " -- HTML output at progit.html"
+      puts ' -- HTML output at progit.html'
 
-      exec_or_raise('htmlproofer --check-html progit.html')
+  end
+
+  desc 'build Epub format'
+  task :build_epub => 'book/contributors.txt' do
+      check_contrib()
 
-      puts "Converting to EPub..."
+      puts 'Converting to EPub...'
       `bundle exec asciidoctor-epub3 #{params} progit.asc`
-      puts " -- Epub output at progit.epub"
+      puts ' -- Epub output at progit.epub'
 
-      exec_or_raise('epubcheck progit.epub')
+  end
 
+  desc 'build Mobi format'
+  task :build_mobi => 'book/contributors.txt' do
       # Commented out the .mobi file creation because the kindlegen dependency is not available.
       # For more information on this see: #1496.
       # This is a (hopefully) temporary fix until upstream asciidoctor-epub3 is fixed and we can offer .mobi files again.
@@ -39,12 +92,47 @@ namespace :book do
       # `bundle exec asciidoctor-epub3 #{params} -a ebook-format=kf8 progit.asc`
       # puts " -- Mobi output at progit.mobi"
 
-      puts "Converting to PDF... (this one takes a while)"
+      # FIXME: If asciidoctor-epub3 supports Mobi again, uncomment these lines below
+      puts "Converting to Mobi isn't supported yet."
+      puts "For more information see issue #1496 at https://github.com/progit/progit2/issues/1496."
+      exit(127)
+  end
+
+  desc 'build PDF format'
+  task :build_pdf => 'book/contributors.txt' do
+      check_contrib()
+
+      puts 'Converting to PDF... (this one takes a while)'
       `bundle exec asciidoctor-pdf #{params} progit.asc 2>/dev/null`
-      puts " -- PDF output at progit.pdf"
+      puts ' -- PDF output at progit.pdf'
+  end
+
+  desc 'Check generated books'
+  task :check => [:build_html, :build_epub] do
+      puts 'Checking generated books'
 
+      exec_or_raise('htmlproofer --check-html progit.html')
+      exec_or_raise('epubcheck progit.epub')
+  end
+
+  desc 'Clean all generated files'
+  task :clean do
+    begin
+        puts 'Removing generated files'
+
+        FileList['book/contributors.txt', 'progit.html', 'progit.epub', 'progit.pdf'].each do |file|
+            rm file
+
+            # Rescue if file not found
+            rescue Errno::ENOENT => e
+              begin
+                  puts e.message
+                  puts 'Error removing files (ignored)'
+              end
+        end
     end
   end
+
 end
 
 task :default => "book:build"
diff --git a/book/01-introduction/sections/about-version-control.asc b/book/01-introduction/sections/about-version-control.asc
@@ -44,7 +44,7 @@ However, this setup also has some serious downsides.
 The most obvious is the single point of failure that the centralized server represents.
 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.
 If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything -- the entire history of the project except whatever single snapshots people happen to have on their local machines.
-Local VCS systems suffer from this same problem -- whenever you have the entire history of the project in a single place, you risk losing everything.
+Local VCSs suffer from this same problem -- whenever you have the entire history of the project in a single place, you risk losing everything.
 
 ==== Distributed Version Control Systems
 
diff --git a/book/01-introduction/sections/installing.asc b/book/01-introduction/sections/installing.asc
@@ -51,10 +51,6 @@ A macOS Git installer is maintained and available for download at the Git websit
 .Git macOS Installer
 image::images/git-osx-installer.png[Git macOS installer]
 
-You can also install it as part of the GitHub for macOS install.
-Their GUI Git tool has an option to install command line tools as well.
-You can download that tool from the GitHub for macOS website, at https://desktop.github.com[].
-
 ==== Installing on Windows
 
 There are also a few ways to install Git on Windows.(((Windows, installing)))
@@ -65,12 +61,6 @@ Note that this is a project called Git for Windows, which is separate from Git i
 To get an automated installation you can use the https://chocolatey.org/packages/git[Git Chocolatey package].
 Note that the Chocolatey package is community maintained.
 
-Another easy way to get Git installed is by installing GitHub Desktop.
-The installer includes a command line version of Git as well as the GUI.
-It also works well with PowerShell, and sets up solid credential caching and sane CRLF settings.(((PowerShell)))(((CRLF)))(((credential caching)))
-We'll learn more about those things a little later, but suffice it to say they're things you want.
-You can download this from the https://desktop.github.com[GitHub Desktop website].
-
 ==== Installing from Source
 
 Some people may instead find it useful to install Git from source, because you'll get the most recent version.
diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc
@@ -57,7 +57,7 @@ At this point, you have a Git repository with tracked files and an initial commi
 ==== Cloning an Existing Repository
 
 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`.
-If you're familiar with other VCS systems such as Subversion, you'll notice that the command is "clone" and not "checkout".
+If you're familiar with other VCSs such as Subversion, you'll notice that the command is "clone" and not "checkout".
 This is an important distinction -- instead of getting just a working copy, Git receives a full copy of nearly all data that the server has.
 Every version of every file for the history of the project is pulled down by default when you run `git clone`.
 In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there -- see <<ch04-git-on-the-server#_getting_git_on_a_server>> for more details).
diff --git a/book/02-git-basics/sections/recording-changes.asc b/book/02-git-basics/sections/recording-changes.asc
@@ -27,7 +27,7 @@ If you run this command directly after a clone, you should see something like th
 $ git status
 On branch master
 Your branch is up-to-date with 'origin/master'.
-nothing to commit, working directory clean
+nothing to commit, working tree clean
 ----
 
 This means you have a clean working directory; in other words, none of your tracked files are modified.
@@ -579,7 +579,7 @@ This command removes all files whose names end with a `~`.
 ==== Moving Files
 
 (((files, moving)))
-Unlike many other VCS systems, Git doesn't explicitly track file movement.
+Unlike many other VCSs, Git doesn't explicitly track file movement.
 If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file.
 However, Git is pretty smart about figuring that out after the fact -- we'll deal with detecting file movement a bit later.
 
diff --git a/book/02-git-basics/sections/remotes.asc b/book/02-git-basics/sections/remotes.asc
@@ -179,7 +179,7 @@ $ git remote show origin
 ----
 
 It lists the URL for the remote repository as well as the tracking branch information.
-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.
+The command helpfully tells you that if you're on the `master` branch and you run `git pull`, it will automatically merge the remote's `master` branch into the local one after it has been fetched.
 It also lists all the remote references it has pulled down.
 
 That is a simple example you're likely to encounter.
diff --git a/book/02-git-basics/sections/undoing.asc b/book/02-git-basics/sections/undoing.asc
@@ -136,8 +136,8 @@ You can see that the changes have been reverted.
 
 [IMPORTANT]
 =====
-It's important to understand that `git checkout -- <file>` is a dangerous command.
-Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
+It's important to understand that `git checkout \-- <file>` is a dangerous command.
+Any local changes you made to that file are gone -- Git just replaced that file with the last staged or committed version.
 Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
 =====
 
@@ -230,6 +230,6 @@ Changes to be committed:
 [IMPORTANT]
 =====
 It's important to understand that `git restore <file>` is a dangerous command.
-Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version.
+Any local changes you made to that file are gone -- Git just replaced that file with the last staged or committed version.
 Don't ever use this command unless you absolutely know that you don't want those unsaved local changes.
 =====
diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc
@@ -82,7 +82,7 @@ Do not rename branches that are still in use by other collaborators.
 Do not rename a branch like master/main/mainline without having read the section "Changing the master branch name".
 ====
 
-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.
+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.
 You also want to change the branch name on the remote (GitHub, GitLab, other server).
 How do you do this?
 
@@ -93,7 +93,7 @@ Rename the branch locally with the `git branch --move` command:
 $ git branch --move bad-branch-name corrected-branch-name
 ----
 
-This replaces your bad-branch-name with corrected-branch-name, but this change is only local for now.
+This replaces your `bad-branch-name` with `corrected-branch-name`, but this change is only local for now.
 To let others see the corrected branch on the remote, push it:
 
 [source,console]
@@ -113,10 +113,8 @@ $ git branch --all
   remotes/origin/main
 ----
 
-Notice that you're on the branch corrected-branch-name.
-The corrected branch is available on the remote.
-However the bad branch is also still present on the remote.
-You can delete the bad branch from the remote:
+Notice that you're on the branch `corrected-branch-name` and it's available on the remote.
+However, the branch with the bad name is also still present there but you can delete it by executing the following command:
 
 [source,console]
 ----
@@ -131,19 +129,19 @@ Now the bad branch name is fully replaced with the corrected branch name.
 ====
 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.
 Before you do this, make sure you consult with your collaborators.
-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.
+Also, make sure you do a thorough search through your repo and update any references to the old branch name in your code and scripts.
 ====
 
-Rename your local _master_ branch into _main_ with the following command
+Rename your local `master` branch into `main` with the following command:
 
 [source,console]
 ----
 $ git branch --move master main
 ----
 
-There's no _master_ branch locally anymore, because it's renamed to the _main_ branch.
+There's no local `master` branch anymore, because it's renamed to the `main` branch.
 
-To let others see the new _main_ branch, you need to push it to the remote.
+To let others see the new `main` branch, you need to push it to the remote.
 This makes the renamed branch available on the remote.
 
 [source,console]
@@ -162,10 +160,10 @@ git branch --all
   remotes/origin/master
 ----
 
-Your local _master_ branch is gone, as it's replaced with the _main_ branch.
-The _main_ branch is also available on the remote.
-But the remote still has a _master_ branch.
-Other collaborators will continue to use the _master_ branch as the base of their work, until you make some further changes.
+Your local `master` branch is gone, as it's replaced with the `main` branch.
+The `main` branch is present on the remote.
+However, the old `master` branch is still present on the remote.
+Other collaborators will continue to use the `master` branch as the base of their work, until you make some further changes.
 
 Now you have a few more tasks in front of you to complete the transition:
 
@@ -176,7 +174,7 @@ Now you have a few more tasks in front of you to complete the transition:
 * Update references to the old branch in documentation.
 * Close or merge any pull requests that target the old branch.
 
-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:
+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:
 
 [source, console]
 ----
diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc
diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc
diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc
diff --git a/book/07-git-tools/sections/reset.asc b/book/07-git-tools/sections/reset.asc
diff --git a/book/10-git-internals/sections/refs.asc b/book/10-git-internals/sections/refs.asc
