usage-existing-project-github-first.Rmd

# Existing project, GitHub first {#existing-github-first}

This is a novice-friendly workflow for bringing an existing R project into the RStudio and Git/GitHub universe.

We do this in a slightly goofy way, in order to avoid using Git at the command line.
You won't want to work this way forever, but it's perfectly fine as you're getting started!
At first, the main goal is to accumulate some experience and momentum.
There is nothing goofy about the GitHub repo that this creates, it is completely standard.
Transition to a more elegant process when you're ready.

We assume you've got your existing R project isolated in a directory on your computer.
If that's not already true, make it so.
Create a directory and marshal all the existing data and R scripts there.
It doesn't really matter where you do this, but note where the project currently lives.

## Make a repo on GitHub

```{r echo = FALSE, results = "asis"}
dat <- list(
  repository_name_text = glue::glue("
    `myrepo` or a similarly short name for this existing project. Approach \\
    this similar to a variable name, in code: descriptive but brief, no \\
    whitespace. Letters, digits, `-`, `.`, or `_` are allowed."),
  description_text = glue::glue("
    \"Analysis of the stuff\" or any short description of the project. Write \\
    this for humans."),
  initialize_text = "Initialize this repository with: Add a README file."
)
insert <- glue::glue_data(
  dat,
  readr::read_file("child-create-a-github-repo.Rmd"),
  .open = "<<<", .close = ">>>"
)
res <- knitr::knit_child(text = insert, quiet = TRUE)
cat(res, sep = '\n')
```

## New RStudio Project via git clone {#git-clone-usethis-rstudio}

```{r echo = FALSE, results = "asis"}
insert <- readr::read_file("child-clone-a-github-repo.Rmd")
res <- knitr::knit_child(text = insert, quiet = TRUE)
cat(res, sep = '\n')
```

## Bring your existing project over

Using your favorite method of moving or copying files, copy the files that constitute your existing project into the directory for this new project.

In RStudio, consult the Git pane and the file browser.

  * Are you seeing all the files? They should be here if your move/copy was successful.
  * Are they showing up in the Git pane with questions marks? They should be appearing as new untracked files.
  
## Stage and commit

Commit your files to this repo. How?

  * Click the "Git" tab in upper right pane
  * Check the "Staged" box for all files that you want to commit.
    - Default: stage it.
    - When to reconsider: this will all go to GitHub. Consider if that is
      appropriate for each file. **You can absolutely keep a file locally,
      without committing it to the Git repo and sending to GitHub**. Just let it
      sit there in your Git pane, without being staged. No harm will be done. If
      this is a long-term situation, list the file in `.gitignore`.
  * If you're not already in the Git pop-up, click "Commit"
  * Type a message in "Commit message", such as "Init project XYZ".
  * Click "Commit"

## Push your local changes to GitHub

Click the green "Push" button to send your local changes to GitHub.
RStudio will display something like:

```console
>>> /usr/bin/git push origin HEAD:refs/heads/main
To https://github.com/jennybc/myrepo.git
   3a2171f..6d58539  HEAD -> main
```

## Confirm the local change propagated to the GitHub remote

Go back to the browser.
I assume we're still viewing your new GitHub repo.

Refresh.

You should see all the project files you committed there.

If you click on "commits," you should see one with the message you used, e.g. "Init project XYZ".

## The end

```{r echo = FALSE, results = "asis"}
cat(readLines("child-the-end-of-repo-setup.Rmd"), sep = '\n')
```