github.qmd

# GitHub 

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
```

```{r}
#| label: git_contrib_box
#| echo: false
#| results: asis
#| eval: true
git_contrib_box()
```

If you're new to GitHub, the steps below will walk you through setting up Git and GitHub from RStudio using the **Git** pane. The initial files in the project are below: 


## Example Shiny project

Let's assume we've just created `projApp`, a new Shiny application *without* the package structure (it was initially created using the **New Project Wizard** with a Git repo initialized).

The files in `projApp` are below: 

```{verbatim}
#| eval: false 
#| code-fold: false
projApp/
  ├── app.R
  └── projApp.Rproj

1 directory, 2 files
```

After creating the project, we'll head over to GitHub and create am empty repo with the same name. We'll see the following options:

:::: {.column-page-inset-right}

::: {#fig-gh_repo_initial}

![New repository on GitHub](img/gh_repo_initial.png){#fig-gh_repo_initial width="100%" fig-align="center"}

Empty GitHub repository options
:::

::::

We're interested in the second option, "**...push an existing repository from the command line**". One option is to copy the Git commands and enter them into the **Terminal** pane in Posit workbench, but we're going to use Posit Workbench's **Git** pane. 

## Committing changes 

We'll commit these initial files to the repo using the **Commit** icon in the **Git** pane (each file initially has a yellow question mark icon):

::: {#fig-git_pane_commit}

![Commit changes](img/git_pane_commit.png){#fig-git_pane_commit width='100%' fig-align="center"}

After selecting each file, the icon turns to a blue 'A' (which means the file or change has been 'added' to the repo)

![First commit](img/git_first_commit.png){#fig-git_first_commit width='100%'}

Click on **Commit** to open the Git window. Stage all the files, add a commit message, and click **Commit**
:::

We'll add a brief commit message and click **Commit**. This is the equivalent of entering the following commands in the Terminal:


:::{style='font-weight: bold; font-size: 1.40em;'}

``` sh
git add .
git commit -m 'first commit'
```

:::

```{r}
#| label: co_box_commit
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g",
  fold = FALSE, 
  look = "default",
  header = "Committing changes to a repository with a message",
  contents = "

**`git commit -m 'first commit'`**
  
When you run `git commit -m 'first commit'`, you are committing your staged changes (i.e., changes you've previously added to the staging area using `git add`) with the message 'first commit'. 
  
This message is then stored in the Git history, allowing anyone who looks at the commit logs to see a brief description of what was done in that particular commit.

- **`git commit`**: This command captures a snapshot of the changes in your project's tracked files and directories. By committing, you're saving the current state of those files in the Git repository.

- **`-m`**: This flag indicates that a commit message will be provided directly from the command line.

- **`'first commit'`**: This is the commit message associated with this commit. Commit messages are useful for documenting the changes you've made, making it easier for others (and your future self) to understand the evolution and purpose of changes in the project.
  
  ")
```

Review the output from the commit.
  
::: {#fig-git_first_commit_output}

![First commit output](img/git_first_commit_output.png){#fig-git_first_commit_output width='100%' fig-align="center"}

The `.gitignore`, `app.R`, and `sap.Rproj` files have been committed to `main`
:::

The output tells us the contents of `projApp` are part of our local `main` branch. Now we need to make sure the local branch has a remote on GitHub at the following URL: `https://github.com/<username>/sap.git`. 

```{r}
#| label: co_box_branch_main
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g",
  fold = FALSE, 
  look = "minimal",
  header = "Add a new remote to your Git repository",
  contents = "


`git remote` `add` `origin` `https://github.com/<username>/<repo>.git`

- **`git remote`**: used to manage and set remotes ('remote repositories') for your project

- **`add`**: specifies that you want to add a new remote.

- **`origin`**: a convention widely used in the Git community is to name the primary remote repository `origin`.

- **`https://github.com/<username>/<repo>.git`**: This is the URL to the Git repository (hosted on GitHub). Replace `<username>` with the GitHub username of the repository owner and `<repo>` with the name of the repository.

So, when you run this command, you're telling Git: 'I want to add a new remote called `origin`, and the URL for this remote is `https://github.com/<username>/<repo>.git'`.'

After executing this command, you can then push to and pull from the repository using this remote by referring to its name (`origin`). For instance, `git push origin master` would push your local `main` branch to the `main` branch on the `origin` remote.
  
  "
)
```

## New branch, add remote

Click the **New Branch** icon in the **Git** pane and create a new `main` branch. Then click on **Add Remote...** and name the remote `origin`. 

::: {#fig-git_remote_add_origin}

![Add branch and remote name](img/git_remote_add_origin.png){#fig-git_remote_add_origin width='100%' fig-align='center'}


The **Remote URL** is the link from the Quick Setup above. 

![Add remote URL](img/remote_url.png){#fig-git_remote_add_origin width='100%' fig-align='center'}


Create new `main` branch to track `origin`
:::

After clicking **Add** and **Create**, you'll be asked to checkout or overwrite the existing `main` branch. In this case, we can select **Overwrite** (because we're already on the `main` branch).

::: {#fig-git_main_track_origin_main}

![Overwrite `main`](img/git_overwrite_main.png){#fig-git_main_track_origin_main width='55%' fig-align='center'}

:::


## Push a local branch to remote (and set branch to track remote branch)

The **`git push -u origin main`** commands tell Git to "*push the `main` branch to the `origin` remote, and also set the local `main` branch to track the `main` branch on `origin`*."

- **`git push`**: used to push commits from your local repository to a remote repository.

- **`origin`**: name of the remote repository you want to push to. When you `clone` a repo or `add` a remote using `git remote add`, it's common to name the `main` remote `origin` (though it could technically be any name).

- **`main`**: name of the branch you're pushing to the remote repository.

- **`-u or --set-upstream`**: When this option is used, it sets a tracking relationship between the local and upstream remote branches. This means that in the future, using `git pull` or `git push` doesn't require specifying the remote or branch (Git will know you're referring to the `origin`/`main` branch). 



::: {#fig-git_main_track_origin_main}

![branch main set up to track origin/main](img/git_main_track_origin_main.png){#fig-git_main_track_origin_main width='100%' fig-align='center'}

`main` will now track the remote (`origin`)
:::

## Renaming branches

The Git UI above called the `git branch -B main` commands, so we'll break these down below: 

- **`git branch`** without any arguments would list all the local branches in the current repository. But, with certain options (like `-M`), you can perform other branch-related operations.

- **`-M`**: This option stands for 'move/rename' and forcibly renames the branch. If a branch named `main` already exists, it will be overwritten because of the forceful nature of the `-M` option. If you want to avoid accidentally overwriting an existing branch, you could use `-m` (lowercase) instead. The lowercase `-m` will rename only if the target name doesn’t already exist.

- **`main`**: This is the new name for the currently checked-out branch.

```{r}
#| label: co_box_M_main
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g",
  fold = FALSE, 
  look = "minimal",
  header = "Do I have to call the default branch `main`?",
  contents = "
Most Git users started transitioning from `master` to `main` as the default branch name for new repositories, but it's not required. You can call the default branch anythign (for example, in `sap`, the default is the first chapter (`01_whole-app-game`))
  ")
```


The complete workflow for setting up Git from the command line is below: 
  
``` sh
# make and add changes 
git add .
# commit changes
git commit 'first commit'
# set remote on GitHub
git remote add origin https://github.com/<username>/<repo>.git
# rename the current branch to main
git branch -M main
# push and set upstream to origin (remote)
git push -u origin main
```