Merged commits to english repo up to the 15.10.2019 (#30)

* Added last commits from the main english repos except the one with the
svg files

* Added commits from the main english repo up to the 15.10.2019

Author: pastatopf

book/01-introduction/sections/help.asc

@@ -21,7 +21,7 @@ Diese Befehle sind nützlich, weil Sie sich die Hilfe jederzeit anzeigen lassen
 Wenn die Hilfeseiten und dieses Buch nicht ausreichen und Sie persönliche Hilfe brauchen, können Sie den `#git` oder `#github` Kanal auf dem Freenode IRC Server probieren, der unter https://freenode.net zu finden ist.
 Diese Kanäle sind in der Regel sehr gut besucht. Normalerweise findet sich unter den vielen Anwendern, die oft sehr viel Erfahrung mit Git haben, irgendjemand, der Ihnen weiterhelfen kann.(((IRC)))
 
-Wenn Sie nicht die vollständige Manpage-Hilfe benötigen, sondern nur eine kurze Beschreibung der verfügbaren Optionen für einen Git-Befehl, können Sie auch in den kompakteren „Hilfeseiten“ mit den Optionen `-h` oder `--help` nachschauen, wie in:
+Wenn Sie nicht die vollständige Manpage-Hilfe benötigen, sondern nur eine kurze Beschreibung der verfügbaren Optionen für einen Git-Befehl, können Sie auch in den kompakteren „Hilfeseiten“ mit der `-h` Option nachschauen, wie in:
 
 [source,console]
 ----

book/07-git-tools/sections/submodules.asc

@@ -185,7 +185,7 @@ Submodule path 'DbConnector': checked out 'c3f01dc8862123d317dd46284b05b6892c7b2
 Now your `DbConnector` subdirectory is at the exact state it was in when you committed earlier.
 
 There is another way to do this which is a little simpler, however.
-If you pass `--recurse-submodules` to the `git clone` command, it will automatically initialize and update each submodule in the repository.
+If you pass `--recurse-submodules` to the `git clone` command, it will automatically initialize and update each submodule in the repository, including nested submodules if any of the submodules in the repository have submodules themselves.
 
 [source,console]
 ----
@@ -206,11 +206,14 @@ Checking connectivity... done.
 Submodule path 'DbConnector': checked out 'c3f01dc8862123d317dd46284b05b6892c7b29bc'
 ----
 
+If you already cloned the project and forgot `--recurse-submodules`, you can combine the `git submodule init` and `git submodule update` steps by running `git submodule update --init`.
+To also initialize, fetch and checkout any nested submodules, you can use the foolproof `git submodule update --init --recursive`.
+
 ==== Working on a Project with Submodules
 
 Now we have a copy of a project with submodules in it and will collaborate with our teammates on both the main project and the submodule project.
 
-===== Pulling in Upstream Changes
+===== Pulling in Upstream Changes from the Submodule Remote
 
 The simplest model of using submodules in a project would be if you were simply consuming a subproject and wanted to get updates from it from time to time but were not actually modifying anything in your checkout.
 Let's walk through a simple example there.
@@ -372,6 +375,68 @@ Submodule DbConnector c3f01dc..c87d55d:
 
 Git will by default try to update *all* of your submodules when you run `git submodule update --remote` so if you have a lot of them, you may want to pass the name of just the submodule you want to try to update.
 
+===== Pulling Upstream Changes from the Project Remote
+Let's now step into the shoes of your collaborator, who has his own local clone of the the MainProject repository.
+Simply executing `git pull` to get your newly committed changes is not enough:
+
+[source,console]
+----
+$ git pull
+From https://github.com/chaconinc/MainProject
+   fb9093c..0a24cfc  master     -> origin/master
+Fetching submodule DbConnector
+From https://github.com/chaconinc/DbConnector
+   c3f01dc..c87d55d  stable     -> origin/stable
+Updating fb9093c..0a24cfc
+Fast-forward
+ .gitmodules         | 2 +-
+ DbConnector         | 2 +-
+ 2 files changed, 2 insertions(+), 2 deletions(-)
+ 
+ $ git status
+ On branch master
+Your branch is up-to-date with 'origin/master'.
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git checkout -- <file>..." to discard changes in working directory)
+  
+ 	modified:   DbConnector (new commits)
+	
+ Submodules changed but not updated:
+ 
+ * DbConnector c87d55d...c3f01dc (4):
+  < catch non-null terminated lines
+  < more robust error handling
+  < more efficient db routine
+  < better connection routine
+  
+ no changes added to commit (use "git add" and/or "git commit -a")
+----
+
+ By default, the  `git pull` command recursively fetches submodules changes, as we can see in the output of the first command above.
+However, it does not *update* the submodules.
+This is shown by the output of the `git status` command, which shows the submodule is ``modified'', and has ``new commits''.
+What's more, the brackets showing the new commits point left (<), indicating that these commits are recorded in MainProject but are not present in the local DbConnector checkout.
+To finalize the update, you need to run `git submodule update`:
+
+[source,console]
+----
+$ git submodule update --init --recursive
+Submodule path 'vendor/plugins/demo': checked out '48679c6302815f6c76f1fe30625d795d9e55fc56'
+
+ $ git status
+ On branch master
+Your branch is up-to-date with 'origin/master'.
+nothing to commit, working tree clean
+----
+
+Note that to be on the safe side, you should run `git submodule update` with the `--init` flag in case the MainProject commits you just pulled added new submodules, and with the `--recursive` flag if any submodules have nested submodules.
+
+If you want to automate this process, you can add the `--recurse-submodules` flag to the `git pull` command (since Git 2.14).
+This will make Git run `git submodule update` right after the pull, putting the submodules in the correct state.
+Moreover, if you want to make Git always pull with `--recurse-submodules`, you can set the configuration option `submodule.recurse` to true (this works for `git pull` since Git 2.15).
+This option will make Git use the `--recurse-submodules` flag for all commands that support it (except `clone`).
+
 ===== Working on a Submodule
 
 It's quite likely that if you're using submodules, you're doing so because you really want to work on the code in the submodule at the same time as you're working on the code in the main project (or across several submodules).
@@ -393,16 +458,18 @@ First of all, let's go into our submodule directory and check out a branch.
 
 [source,console]
 ----
+$ cd DbConnector/
 $ git checkout stable
 Switched to branch 'stable'
 ----
 
-Let's try it with the ``merge'' option.
+Let's try updating our submodule with the ``merge'' option.
 To specify it manually, we can just add the `--merge` option to our `update` call.
 Here we'll see that there was a change on the server for this submodule and it gets merged in.
 
 [source,console]
 ----
+$ cd ..
 $ git submodule update --remote --merge
 remote: Counting objects: 4, done.
 remote: Compressing objects: 100% (2/2), done.
@@ -433,6 +500,7 @@ Now if we update our submodule we can see what happens when we have made a local
 
 [source,console]
 ----
+$ cd ..
 $ git submodule update --remote --rebase
 First, rewinding head to replay your work on top of it...
 Applying: unicode support
@@ -793,11 +861,16 @@ This way you can simply run `git supdate` when you want to update your submodule
 
 Using submodules isn't without hiccups, however.
 
-For instance switching branches with submodules in them can also be tricky.
+===== Switching branches
+
+For instance, switching branches with submodules in them can also be tricky with Git versions older than Git 2.13.
 If you create a new branch, add a submodule there, and then switch back to a branch without that submodule, you still have the submodule directory as an untracked directory:
 
 [source,console]
 ----
+$ git --version
+git version 2.12.2
+
 $ git checkout -b add-crypto
 Switched to a new branch 'add-crypto'
 
@@ -849,6 +922,47 @@ Makefile	includes	scripts		src
 
 Again, not really very difficult, but it can be a little confusing.
 
+Newer Git versions (Git >= 2.13) simplify all this by adding the `--recurse-submodules` flag to the `git checkout` command, which takes care of placing the submodules in the right state for the branch we are switching to.
+
+[source,console]
+----
+$ git --version
+git version 2.13.3
+
+ $ git checkout -b add-crypto
+Switched to a new branch 'add-crypto'
+
+ $ git submodule add https://github.com/chaconinc/CryptoLibrary
+Cloning into 'CryptoLibrary'...
+...
+
+ $ git commit -am 'adding crypto library'
+[add-crypto 4445836] adding crypto library
+ 2 files changed, 4 insertions(+)
+ create mode 160000 CryptoLibrary
+ 
+ $ git checkout --recurse-submodules master
+Switched to branch 'master'
+Your branch is up-to-date with 'origin/master'.
+
+ $ git status
+On branch master
+Your branch is up-to-date with 'origin/master'.
+
+ nothing to commit, working tree clean
+----
+
+Using the the `--recurse-submodules` flag of `git checkout` can also be useful when you work on several branches in the superproject, each having your submodule pointing at different commits.
+Indeed, if you switch between branches that record the submodule at different commits, upon executing `git status` the submodule will appear as ``modified'', and indicate ``new commits''. That is because the submodule state is by default not carried over when switching branches.
+
+This can be really confusing, so it's a good idea to always `git checkout --recurse-submodules` when your project has submodules.
+(For older Git versions that do not have the  `--recurse-submodules` flag, after the checkout you can use `git submodule update --init --recursive` to put the submodules in the right state.)
+
+Luckily, you can tell Git (>=2.14) to always use the  `--recurse-submodules` flag by setting the configuration option `submodule.recurse`: `git config submodule.recurse true`.
+As noted above, this will also make Git recurse into submodules for every command that has a `--recurse-submodules` option (except `git clone`).
+
+ ===== Switching from subdirectories to submodules
+
 The other main caveat that many people run into involves switching from subdirectories to submodules.
 If you've been tracking files in your project and you want to move them out into a submodule, you must be careful or Git will get angry at you.
 Assume that you have files in a subdirectory of your project, and you want to switch it to a submodule.

book/B-embedding-git/sections/libgit2.asc

@@ -131,7 +131,7 @@ error = git_odb_add_backend(odb, my_backend, 1); // <3>
 
 git_repository *repo;
 error = git_repository_open(&repo, "some-path");
-error = git_repository_set_odb(odb); // <4>
+error = git_repository_set_odb(repo, odb); // <4>
 ----
 
 _(Note that errors are captured, but not handled. We hope your code is better than ours.)_