Add chapter on Git remotes

39_workflow-git-remotes.Rmd

@@ -0,0 +1,123 @@
+# Remotes {#remotes}
+
+Practice managing your remotes.
+
+Remote repositories are versions of your project that are hosted on the
+Internet or another network. A single project can have 1, 2 or even hundreds of
+remotes. You pull others changes from remotes and push your changes to remotes.
+
+## Listing what remotes exist
+
+`git remote` lists the names of available remotes, but usually it is more
+useful to see what ULRs each note corresponds to (with `-v`).
+
+```{bash}
+git remote -v
+```
+
+## Adding a new remote
+
+`git clone` automatically adds a new remote, so often you do not need to do
+this manually initially. However after the initial clone it is often useful to
+add additional remotes.
+
+Use `git remote add` to add a new remote
+
+```shell
+git remote add happygit https://github.com/jennybc/happy-git-with-r.git
+```
+
+Note when you add a remote you give it a name (here `happygit`), which you can use instead of the entire URL.
+
+```shell
+git fetch happygit
+```
+
+## Fetching data from remotes
+
+To get new data from a remote use `git fetch <remote_name>`. This retrieves the
+data locally, but importantly it does _not_ change the state of your repository
+in any way. To incorporate the data into your repository you need to merge or
+rebase your project with the remote project.
+
+```shell
+# Fetch the data
+git fetch happygit
+
+# Now merge it with our local master
+git merge happygit/master master
+
+# git pull is a shortcut which does the above in one command
+git pull happygit master
+```
+
+## Pushing to remotes
+
+Use `git push <remote> <branch>` to push your local changes to the `<branch>`
+branch on the `<remote>` remote.
+
+```shell
+# push my local changes to the origin remote's master branch
+git push origin master
+
+# push my local changes to the happygit remote's test branch
+git push happygit test
+```
+
+## Renaming and changing remotes
+
+`git remote rename` can be used to rename a remote
+
+```shell
+git remote rename happygit hg
+```
+
+`git remote set-url` can be used to change the URL for a remote. This is
+sometimes useful if you initially set up a remote using https, but now want to
+use the SSH URL instead (or vise versa).
+
+```shell
+git remote set-url happygit [email protected]:jennybc/happy-git-with-r.git
+```
+
+One fairly common workflow is you initially cloned a repository on GitHub
+locally (without forking it), but now want to create your own fork and push
+changes to it. I generally like to have the main repository called `upstream`
+and my forked repository called `origin`. So in this case you will need to
+first rename the repository, then add your fork as a new remote.
+
+```shell
+git remote rename origin upstream
+git remote add origin [email protected]:jimhester/happy-git-with-r.git
+```
+
+## Upstream tracking branches
+
+It is possible to set the branch on the remote each of your local remotes
+corresponds to. `git clone` sets this up automatically, so for your own master
+branch this is not something you will run into. However by default if you
+create a new branch and try to push to it you will see something like this.
+
+```shell
+git checkout -b mybranch
+git push
+# fatal: The current branch foo has no upstream branch.
+# To push the current branch and set the remote as upstream, use
+#
+#     git push --set-upstream origin foo
+```
+
+You can do as the error message says and explicitly set the upstream branch
+with `--set-upstream`. However I would recommend instead changing the default
+behavior of `push` to automatically set the upstream branch to the branch with
+the same name on the remote.
+
+You can do this by changing the git `push.default` option to `current`.
+
+```shell
+git config --global push.default current
+```
+
+See also Working with Remotes:
+
+<https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes>

_bookdown.yml

@@ -34,15 +34,17 @@ rmd_files: [
   "31_workflow-first-use-r-script-and-github.Rmd",
   "32_workflow-make-github-repo-browsable.Rmd",
   "36_workflow-explore-extend-pull-request.Rmd",
-  "38_workflow-git-commands.Rmd",
+  "37_workflow-git-commands.Rmd",
+  "38_workflow-git-branches.Rmd",
+  "39_workflow-git-remotes.Rmd",
 
   "40_prompt-clone.Rmd",
   "41_prompt-fork.Rmd",
   "42_prompt-fork-pr-bingo.Rmd",
   "43_prompt-burn-it-all-down.Rmd",
   "44_prompt-practice-resets.Rmd",
-  "45_prompt-search-github.Rmd",
   "46_prompt-pull.Rmd",
+  "47_prompt-search-github.Rmd",
 
   "60_classroom-overview.Rmd",