06-tools.Rmd

# Tools {#tools}

## Docker {#docker}

## Tableau {#tableau}

## GitHub {#github}

### Overview {#github-overview}

GitHub is a `git` repository hosting service. There are other, less well known repository hosting services such as: [GitLab](https://about.gitlab.com/), [Bitbucket](https://bitbucket.org/), and [Gitea](https://gitea.io/). `git` itself is a free and open source version-control system for tracking changes in source code during software development ^[https://en.wikipedia.org/wiki/Git].

### `git` {#git}

#### Install {#git-install}

1. Follow the instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install `git` onto your machine.

#### Configure `git` {#configure-git}

1. Run the following commands: 

```bash
git config --global user.name "You name here"
git config --global user.email "your_email@example.com"
```

2. Next, you need to authenticate with GitHub. Create a public/private keypair:

```bash
ssh-keygen -t rsa -C "your_email@example.com"
```

This creates two files: 

`~/.ssh/id_rsa` --your private key

and 

`~/.ssh/id_rsa.pub` --your public key

3. Copy your **public** key to your clipboard.
4. Navigate and sign in to https://github.com.
5. Go [here](https://github.com/settings/keys), and click "New SSH key".
6. Name the key whatever you'd like in the "Title" field. Usually, I put the name of the computer I'm using.
7. Paste the key in the "Key" field, and click "Add SSH key".
8. At this point in time you should be good to go. Verify by running the following in your terminal:

```bash
ssh -T git@github.com
```

You should receive a message like:

```txt
Hi username! You've successfully authenticated, but Github does
not provide shell access.
```

#### Clone a repository {#git-clone-repository}

If you've followed the directions [here](#configure-git) to configure `git` with SSH:

1. Open a terminal and navigate into the folder in which you'd like to clone the repository. For example, let's say I would like to clone this book's repository into my `~/projects` folder:

```bash
cd ~/projects
```

2. Next, run the following command:

```bash
git clone git@github.com:TheDataMine/the-examples-book.git
```

3. At this point in time, you should have a new folder called `the-examples-book` inside your `~/projects` folder.

#### Commit changes to a repository {#git-commit-changes}

Creating a commit is simple:

1. Navigate into your project repository folder. For example, let's assume our repository lives: `~/projects/the-examples-book`.

```bash
cd ~/projects/the-examples-book
```

2. Modify the repository files as you would like, saving the changes.
3. Create your commit, with an accompanying message:

```bash
git commit -m "Fixed minor spelling error."
```

#### Fetch remote changes {#git-fetch-changes}

1. Navigate to the local repository. For example, let's assume our repository lives: `~/projects/the-examples-book`.

```bash
cd ~/projects/the-examples-book
```

2. Fetch and pull the changes:

```bash
git fetch
git pull
```

#### Push local commits to the remote origin {#git-push-local-commits}

1. First [fetch any remote changes](#git-fetch-changes).
2. Then run the following commands:

```bash
git push
```

#### Create a new branch {#git-create-new-branch}

To create a new branch based off of the `master` branch do the following.

1. Checkout the master branch:

```bash
git checkout master
```

2. Create a new branch named `fix-spelling-errors-01` based off of the master branch and check the new `fix-spelling-errors-01` branch out:

```bash
git checkout -b fix-spelling-errors-01
```

#### Publish your branch to GitHub {#git-publish-branch}

If your current local branch is not present on its remote origin, [git push](#git-push-local-commits) will publish the branch to GitHub.

#### Create a pull request {#git-pull-request}

After publishing a local branch to GitHub, in order to create a pull request, simply navigate to the following link:

https://github.com/my_organization/my_repo/pull/new/my_branch_name

Replace `my_organization` with the username or organization name. For example: `thedatamine`.

Replace `my_repo` with the name of the repository. For example: `the-examples-book`.

Replace `my_branch_name` with the name of the branch you would like to have merged into the `master` branch. For example: `fix-spelling-errors-01`.

So at the end, using our examples, you would navigate to:

https://github.com/TheDataMine/the-examples-book/pull/new/fix-spelling-errors-01

Fill out the information, and click "Create pull request".

### GitHub Desktop {#github-desktop}

#### Install {#github-desktop-install}

1. Follow the excellent directions [here](https://help.github.com/en/desktop/getting-started-with-github-desktop/installing-github-desktop) to install GitHub Desktop.
2. Upon the launch of the application, you should be presented with a screen similar to this:

![](./images/gh-desktop-01.png)
3. Click on "Sign in to GitHub.com.
4. Enter your GitHub credentials in the following screen:

![](./images/gh-desktop-02.png)
5. Continue the sign in process. You will eventually be presented with a screen to select a repository. Congratulations! You've succesfully installed GitHub Desktop.

#### Commit changes to a repository {#github-desktop-commit-changes}

1. First, make a change to to a file within the repository. In this example, I added a contributor named John Smith:

![](./images/gh-desktop-10.png)
2. In the lower left-hand corner of the GUI, add a Commit title and description. Concise and detailed titles and descriptions are best. Click "Commit to `name-of-branch`" in this case, our branch name is `fix-spelling-errors-01`.
3. At this point in time the Commit is only local (on your machine). In order to update the remote respository (on GitHub), you'll need to [publish your branch](#github-desktop-publish-branch). 

If your branch is already published (present on github.com), you'll need to [push your local commits](#github-desktop-push-local-commits) to the remote origin (which is the remote `fix-spelling-errors-01` branch in this case) by clicking on the "Push origin" button:

![](./images/gh-desktop-17.png)

#### Push local commits to the remote origin {#github-desktop-push-local-commits}

1. If you have commits that are ready to be pushed to the remote origin (github.com), you'll be presented with a screen similar to this:

![](./images/gh-desktop-15.png)

2. Simply click on the "Push origin" button in order to push your local commits to the remote origin (which is in this case, a remote branch called `fix-spelling-errors-01`):

![](./images/gh-desktop-17.png)

3. You can verify that the changes have been made by navigating to the branch on github.com, and checking the commit history.

#### Create a new branch {#github-desktop-create-new-branch}

1. In GitHub Desktop, click on the "Current Branch" dropdown:

![](./images/gh-desktop-06.png)
2. Click on the "New Branch" button:

![](./images/gh-desktop-07.png)
3. When presented with the following screen, ensure that your new branch will be based on the `master` branch:

![](./images/gh-desktop-08.png)
4. Type whatever name you'd like to give the new branch. In this case, we are calling it `fix-spelling-errors-01`. Click "Create Branch".
5. Your current branch should now be `fix-spelling-errors-01` or whatever name you entered in step **(4)**. You can see this in the dropdown:

![](./images/gh-desktop-09.png)

#### Publish your branch to GitHub {#github-desktop-publish-branch}

1. If the branch you created is not already present remotely, you'll have a button available to you that says "Publish Branch". Clicking this button will push the branch to the remote repository (on github.com):

![](./images/gh-desktop-13.png)
2. You can confirm that the branch has been successfully pushed to github.com by navigating to the repository on github, and clicking on the "branches" tab:

![](./images/gh-desktop-14.png)

#### Create a pull request {#github-desktop-pull-request}

1. If the branch you are working on is already published remotely, and the remote repository and local repository are both up to date, you will be presented with a screen similar to this:

![](./images/gh-desktop-12.png)

Note that if your local repository is ahead of the remote repository, you will instead be presented with a screen similar to this:

![](./images/gh-desktop-15.png)

You will first need to [push your local commits](#github-desktop-push-local-commits) to the origin (which is the remote `fix-spelling-errors-01` branch in this case) by clicking on the "Push origin" button.

2. Click the "Create Pull Request" button. This will open up a tab in your browser:

![](./images/gh-desktop-16.png)

3. Leave a detailed comment about what you've modified or added to the book. You can click on "Preview" to see what your comment will look like. [GitHub's markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) applies here. Once satisfied, click "Create pull request". 

### Resources {#git-resources}

**[GitHub glossary](https://help.github.com/en/github/getting-started-with-github/github-glossary):**

An excellent resource to understand `git` and GitHub specific terminology.

**[Learn git branching](https://learngitbranching.js.org/):**

An interactive game that teaches you about `git` branching.

## VPNs {#vpns}