diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json index 449ad96..e3801bc 100644 --- a/_freeze/index/execute-results/html.json +++ b/_freeze/index/execute-results/html.json @@ -1,10 +1,8 @@ { - "hash": "37ad8cad92a554e98c25a3954deb1da7", + "hash": "6b3aab448a8632e6e69933ef720c2165", "result": { - "markdown": "---\ntitle: \"Overview\"\n---\n\n\n### Welcome!\n\nThis workshop provides an overview of what \"version control\" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using `git` via RStudio and GitHub**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://nceas.github.io/scicomp-workshop-collaborative-coding/issues) on our GitHub repository if you see clear areas for improvement! \n\n\n\nTo maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. Depending on whether you've used RStudio and/or GitHub before you may have already completed some or all of these steps but please read through the following materials regardless to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the \"Content Creators\" tab. \n\n## Programs to Install\n\n**Note for those of you with a dedicated IT team that has sole power to install software on your computer:** you will need to contact them before the workshop to install the following programs.\n\n### R & RStudio\n\n**Install [R](https://www.r-project.org/) and its more convenient (in our opinion) user-interface: [RStudio](https://www.rstudio.com/products/rstudio/download/)**.\n\nIf you already have R, check that you have at least version 4.0.0 by running the following code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\nversion$version.string\n```\n:::\n\n\nIf your version starts with a 3 (e.g., the above code returns \"R version 3...\"), please update R to make sure all packages behave as expected.\n\n### `git`\n\n**[Install `git`](https://happygitwithr.com/install-git.html)**\n\n**If you are a Windows user**, be sure to follow along with \"Option 1\" in the instructions linked above! That variant gives some under-the-hood tools we'll implicitly rely on later.\n\n:::callout-tip\n## RStudio not detecting `git`?\n\nIf you had your RStudio session open while you installed `git` for the first time, RStudio may not have detected `git` on your computer. In that case, please close and restart RStudio. Check if RStudio is able to detect it now by going to Tools -> Global Options -> Git/SVN. If you see a file path under \"Git executable\" then you are good to go!\n:::\n\nOnce you've successfully installed R, RStudio, and `git`, follow the rest of the setup instructions below.\n\n## Accounts to Create / Connect\n\n### GitHub\n\n**[Create a GitHub account](https://happygitwithr.com/github-acct.html)** using your web browser of choice.\n\nNext, you will have to **connect `git` to your GitHub profile** and then **create a personal access token (PAT)**. A token is essentially a more secure password that `git` requires. You can accomplish these two steps by running the following code in RStudio:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\n#install.packages(c(\"usethis\", \"gitcreds\"))\nlibrary(usethis); library(gitcreds)\n\n# Add your GitHub username and email\nusethis::use_git_config(user.name = \"Jane Doe\",\n user.email = \"jane@example.org\")\n\n# Create a token (Note this will open a GitHub browser tab)\n# See steps 6-10 in GitHub's tutorial (link below)\nusethis::create_github_token()\n\n# Copy your Personal Access Token at the end of the above step!\n\n# Now, give your token to RStudio\n# After you run this line you'll follow some prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set()\n```\n:::\n\n\nAt the end of the above steps your token should be set! For additional information, see [GitHub's PAT Tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or the [Happy Git with R PAT Tutorial](https://happygitwithr.com/https-pat.html). If this seems a little intimidating, please keep in mind that your experience with downloading programs and creating web accounts will help with these tasks even if you have more minimal coding experience!\n\n## GitHub + Science Publications\n\nThe reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations.\n\nIn the ecology and evolutionary biology sphere, Pereira Braga et al. published \"[Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108)\" in _Methods in Ecology & Evolution_. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper's second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) [Pereira Braga et al. 2023](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108) for more detail than we've included in this blurb.\n\nIf you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the **blue** bars). We also think that some of the intermediate technical difficulty uses (**orange** bars) may be relevant to working group priorities and goals.\n\n

\n\n

\n", - "supporting": [ - "index_files" - ], + "markdown": "---\ntitle: \"Overview\"\n---\n\n\n### Welcome!\n\nThis workshop provides an overview of what \"version control\" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using Git via RStudio and GitHub**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://nceas.github.io/scicomp-workshop-collaborative-coding/issues) on our GitHub repository if you see clear areas for improvement! \n\n\n\nTo maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. Depending on whether you've used RStudio and/or GitHub before you may have already completed some or all of these steps but please read through the following materials regardless to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the \"Content Creators\" tab. \n\n## Workshop Preparation\n\n**For those of you with a dedicated IT team that has sole power to install software on your computer:** you will need to contact them before the workshop to do the installation bits of the prep steps we outline below.\n\n### 1. Install R\n\nBegin by installing [R](https://www.r-project.org/). If you already have R, check that you have at least version 4.0.0 by running the following code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\nversion$version.string\n```\n:::\n\n\nIf your version starts with a 3 (e.g., the above code returns \"R version 3...\"), please update R to make sure all packages behave as expected.\n\n### 2. Install RStudio\n\nOnce you have R (ver. ≥4.0), install [RStudio](https://posit.co/download/rstudio-desktop/). If you already have RStudio installed, you may want to make sure that you're using a recent version to take advantage of some quality of life improvements that are broadly useful.\n\n### 3. Install Git\n\nWith R and RStudio installed you can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Jennifer Bryan's \"Happy Git and GitHub for the useR\" digital book does a really nice job covering how to install Git for different computer operating systems (i.e., Mac vs. Windows vs. Linux).\n\nConsult Dr. Bryan's [Git installation instructions](https://happygitwithr.com/install-git.html) and _be sure to follow the steps relevant for **your** operating system!_ **If you are a Windows user**, be sure to follow along with \"Option 1\" in the instructions linked above! That variant gives some under-the-hood tools we'll implicitly rely on later.\n\n:::callout-tip\n## RStudio not detecting Git?\n\nIf you had your RStudio session open while you installed Git for the first time, RStudio may not have detected Git on your computer. In that case, please close and restart RStudio. Check if RStudio is able to detect it now by going to Tools -> Global Options -> Git/SVN. If you see a file path under \"Git executable\" then you are good to go!\n:::\n\n### 4. Create a GitHub Account\n\nNow that you're all done installing programs, it's time to create an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others. Dr. Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) and we also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub. \n\n### 5. Connect Git and GitHub\n\nThe last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication:\n\n1. Personal Access Token (PAT)\n2. Secure Shell (SSH) \n\nWhat's the difference? Essentially, authenticating via token makes many things \"just work\" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's \"[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)\" page.\n\nFollow the steps of your chosen authentication method in the tabs below.\n\n:::panel-tabset\n#### Personal Access Token\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\n#install.packages(c(\"usethis\", \"gitcreds\"))\nlibrary(usethis); library(gitcreds)\n\n# Add your GitHub username and email\nusethis::use_git_config(user.name = \"Jane Doe\",\n user.email = \"jane@example.org\")\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's tutorial (link below)\nusethis::create_github_token()\n```\n:::\n\n\n_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll never get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\ngitcreds::gitcreds_set()\n## After you run this line you'll follow some prompts in the \"Console\" tab of RStudio\n```\n:::\n\n\n##### Further Information\n\nYou may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\nBegin by using the command line (a.k.a. \"shell\" or \"Terminal\") to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not have SSH keys (yet).\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nls -al ~/.ssh/\n```\n:::\n\n\nIf you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend \"lter\" plus your GitHub username to keep things simple.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t ed25519 -C \"lter-github\"\n```\n:::\n\n\n:::callout-tip\n## Older Computer?\n\nIf you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nssh-keygen -t rsa -b 4096 -C \"lter-github\"\n```\n:::\n\n:::\n\nAccept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. If SSH keys are totally new to you, we recommend skipping the passphrase step.\n\nOnce you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).\n\nFinally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic. \n\n##### Further Information\n\nYou may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful.\n:::\n\n## GitHub + Science Publications\n\nThe reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team's disciplinary backgrounds and motivations.\n\nIn the ecology and evolutionary biology sphere, Pereira Braga et al. published \"[Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108)\" in _Methods in Ecology & Evolution_. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper's second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) [Pereira Braga et al. 2023](https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.14108) for more detail than we've included in this blurb.\n\nIf you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the **blue** bars). We also think that some of the intermediate technical difficulty uses (**orange** bars) may be relevant to working group priorities and goals.\n\n

\n\n

\n", + "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" ], diff --git a/_freeze/server/execute-results/html.json b/_freeze/server/execute-results/html.json index f739c0b..deadeb4 100644 --- a/_freeze/server/execute-results/html.json +++ b/_freeze/server/execute-results/html.json @@ -1,7 +1,7 @@ { - "hash": "1abd04026b0e532395436d03a64641be", + "hash": "e62f02594cdd0ecc308e5e707e6c3fa9", "result": { - "markdown": "---\ntitle: \"NCEAS' Server\"\n---\n\n\n## Module Learning Objectives\n\nBy the end of this module, you will be able to:\n\n- Summarize the primary steps for getting set up on a server\n- Connect your GitHub self with your server self\n\n## Overview\n\nWorking on [NCEAS' Server](https://aurora.nceas.ucsb.edu/) is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your \"RStudio\" again for the instance of RStudio accessed through Aurora. GitHub's Personal Access Token is referred to as \"token\" hereafter for simplicity.\n\n## Getting Started on the Server\n\n### Necessary Software\n\nThe only software that you will need on your personal computer to get set up on NCEAS' server is RStudio!\n\nYou likely have worked in the \"Console\" tab of RStudio (where run lines and outputs appear; see below) but RStudio has another tab to the right of the \"Console\" called \"Terminal\" which offers RStudio users access to the **command line** (a.k.a. the **shell**). If you are a veteran command line user you may prefer to use the standalone Terminal app on MacOS or [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/) on Windows but for the sake of keeping your tool kit streamlined, we'll walk through getting set up on NCEAS' server using only RStudio's Terminal tab.\n\n

\n\n

\n\nThe Terminal does not accept R syntax (and the Console doesn't accept Terminal syntax) so you may notice that some of the code we'll walk you through below is formatted differently than you would write an R script.\n\n

\n\n

\n\n### Get your Invite Ready!\n\nAfter your group RSVP'd for this workshop, our team contacted NCEAS' IT team to get you an invite email to create an account on the server. An example of what that email may look like is included below but there are two key pieces of information:\n\n1. Your username\n2. Your temporary password (covered by a **red bar** in the screenshot).\n\nIf you have not received that email, check your Spam folder for emails from Thomas Hetmank (hetmank@nceas.ucsb.edu) or Nick Outin (outin@nceas.ucsb.edu). If you have not received the email and it is not in your Spam, reach out to our team and we will work to get an invite sent to you.\n\n

\n\n

\n\n### Signing into the Server\n\nIn the following instructions, all words that look `like this` should be typed into the Terminal tab and run by pressing return or enter. Note that typing these commands into an R script or R Markdown will not work because it will attempt to run in the Console. All words that look `[like this]` (i.e., bracketed) should also be typed into the Terminal tab but the specific text should be replaced in a user-specific way that is clarified in the nearby text.\n\n1. In the Terminal pane of RStudio, you will \"ssh\" into the server by running the following code: `ssh [your username]@aurora.nceas.ucsb.edu`. It is @aurora because **the name of the server is Aurora**.\n\n2. If this is the first time you've accessed the server you will need to enter `yes` to accept the server's SSH key.\n\n3. You will then be prompted to enter your `[temporary password]` (see the above email example). **Note that the cursor will not advance as you type but it is registering your entries! There will be no indication that you are typing (such as: \"•••••••••\")** This throws off many users so hopefully the above note helps set your mind at ease.\n\n4. You will then be prompted to change your \"expired\" password. We consider your temporary password to be expired as soon as you use it because sharing passwords via email is not secure and this \"expiration\" lets you set the password to something that only you know at the outset of your time in the server. **Note again that the cursor will not advance as you type but it is working!** To update your password, enter your `[temporary password]`, then `[your strong new password]` and finally re-type `[your strong new password]` to confirm it. Note that your new password should not be \"your strong new password\" :)\n\n5. You are ready to go! Run `exit` to log out of the server in the Terminal tab.\n\n6. Now that you have set a new password, use your favorite web browser (e.g., Firefox, Chrome, etc.) to access [Aurora](https://aurora.nceas.ucsb.edu/) and click \"Login to RStudio Server\"\n\n8. In the resulting page, you can sign in with the same username and password you just signed in on the Terminal tab with.\n\n9. You should now be in something that looks very much like RStudio but is housed in a tab on your browser! We will work together from here on out so once you have reached this point, let our team know and we can gather the group before continuing.\n\nIf the above steps have not resulted in successfully accessing Aurora, consult [NCEAS' instructions on first login](https://help.nceas.ucsb.edu/NCEAS/Computing/first_login_to_nceas_analytical_server) and/or [SSH-specific instructions for Mac vs. Windows](https://help.nceas.ucsb.edu/NCEAS/Computing/connecting_to_linux_using_ssh.html) and/or email us!\n\n## Working on the Server\n\n### Step 1: Connect Server RStudio with GitHub\n\nTo begin, load the `usethis` package (install if needed).\n\n::: {.cell}\n\n```{.r .cell-code}\n# install.packages(\"usethis\")\nlibrary(usethis)\n```\n:::\n\n\nNext, configure your name and the email address you use for your GitHub account.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::use_git_config(user.name = \"Jane Doe\",\n user.email = \"jane@example.org\")\n```\n:::\n\n\nIf you would like to check that this worked, you can go to the \"Terminal\" tab (next to the \"Console\" tab) and run `git config --global --list`.\n\n### Step 2: Create GitHub Token\n\nYou may use your token that you already generated for your local RStudio if that is easiest, but you can also create a new token specifically for your Server identity.\n\nTo create a token, you can again use the `usethis` package to send you to the relevant part of the GitHub website.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::create_github_token()\n```\n:::\n\n\nOnce you have walked through that process and created a new token **COPY** the long string of letters and numbers. It is often a good move to take a screenshot of the token and store it on your computer for a rainy day.\n\n### Step 3: Store GitHub Token\n\nTo store the token in your server identity, run the following line of code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ngitcreds::gitcreds_set()\n```\n:::\n\n\nIn the \"Console\" tab you will be prompted to follow a short set of questions (answered via entering numbers in the Console) including the Console requesting your GitHub token.\n\n**PASTE** the long string you copied in the previous step into the supplied field and continue. Note that if you did not copy the token (or copied something else between then and now thus losing the token from your clipboard) you can refer to the screenshot we recommended you take upon first generating the token.\n\n### Step 4: Preserve GitHub Token\n\nYou will also need to tell the server to remember your token so that you don't need to re-do the \"Store GitHub Token\" section every time you start a new R session.\n\nUnfortunately, there are two limitations to this step:\n\n1) Storage can only be done in the \"Terminal\" pane with the command line (don't worry, it's only one line!)\n\n2) Storage must be for a finite amount of time (though it can be a long time!)\n\nTo make the system remember your token, in the \"Terminal\" pane of RStudio type the following:\n\n`git config --global credential.helper 'cache --timeout=10000000'`\n\nThis will cache your \"credentials\" (i.e., your token) for a long time so that you need not worry about this for the time being.\n\nNot running the above line will make your personal access token expire immediately in the system, even though GitHub considers its expiration date (that you set earlier) separately. \n\n### Optional Other Steps\n\nYou may want to configure additional settings, such as:\n\n- The default branch name (for new repositories)\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::git_default_branch_configure(name = \"main\")\n```\n:::\n", + "markdown": "---\ntitle: \"NCEAS' Server\"\n---\n\n\n## Module Learning Objectives\n\nBy the end of this module, you will be able to:\n\n- Summarize the primary steps for getting set up on a server\n- Connect your GitHub self with your server self\n\n## Overview\n\nWorking on [NCEAS' Server](https://aurora.nceas.ucsb.edu/) is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your \"RStudio\" again for the instance of RStudio accessed through Aurora. GitHub's Personal Access Token is referred to as \"token\" hereafter for simplicity.\n\n## Getting Started on the Server\n\n### Necessary Software\n\nThe only software that you will need on your personal computer to get set up on NCEAS' server is RStudio!\n\nYou likely have worked in the \"Console\" tab of RStudio (where run lines and outputs appear; see below) but RStudio has another tab to the right of the \"Console\" called \"Terminal\" which offers RStudio users access to the **command line** (a.k.a. the **shell**). If you are a veteran command line user you may prefer to use the standalone Terminal app on MacOS or [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/) on Windows but for the sake of keeping your tool kit streamlined, we'll walk through getting set up on NCEAS' server using only RStudio's Terminal tab.\n\n

\n\n

\n\nThe Terminal does not accept R syntax (and the Console doesn't accept Terminal syntax) so you may notice that some of the code we'll walk you through below is formatted differently than you would write an R script.\n\n

\n\n

\n\n### Get your Invite Ready!\n\nAfter your group RSVP'd for this workshop, our team contacted NCEAS' IT team to get you an invite email to create an account on the server. An example of what that email may look like is included below but there are two key pieces of information:\n\n1. Your username\n2. Your temporary password (covered by a **red bar** in the screenshot).\n\nIf you have not received that email, check your Spam folder for emails from Thomas Hetmank (hetmank@nceas.ucsb.edu) or Nick Outin (outin@nceas.ucsb.edu). If you have not received the email and it is not in your Spam, reach out to our team and we will work to get an invite sent to you.\n\n

\n\n

\n\n### Signing into the Server\n\nIn the following instructions, all words that look `like this` should be typed into the Terminal tab and run by pressing return or enter. Note that typing these commands into an R script or R Markdown will not work because it will attempt to run in the Console. All words that look `[like this]` (i.e., bracketed) should also be typed into the Terminal tab but the specific text should be replaced in a user-specific way that is clarified in the nearby text.\n\n1. In the Terminal pane of RStudio, you will \"ssh\" into the server by running the following code: `ssh [your username]@aurora.nceas.ucsb.edu`. It is @aurora because **the name of the server is Aurora**.\n\n2. If this is the first time you've accessed the server you will need to enter `yes` to accept the server's SSH key.\n\n3. You will then be prompted to enter your `[temporary password]` (see the above email example). **Note that the cursor will not advance as you type but it is registering your entries! There will be no indication that you are typing (such as: \"•••••••••\")** This throws off many users so hopefully the above note helps set your mind at ease.\n\n4. You will then be prompted to change your \"expired\" password. We consider your temporary password to be expired as soon as you use it because sharing passwords via email is not secure and this \"expiration\" lets you set the password to something that only you know at the outset of your time in the server. **Note again that the cursor will not advance as you type but it is working!** To update your password, enter your `[temporary password]`, then `[your strong new password]` and finally re-type `[your strong new password]` to confirm it. Note that your new password should not be \"your strong new password\" :)\n\n5. You are ready to go! Run `exit` to log out of the server in the Terminal tab.\n\n6. Now that you have set a new password, use your favorite web browser (e.g., Firefox, Chrome, etc.) to access [Aurora](https://aurora.nceas.ucsb.edu/) and click \"Login to RStudio Server\"\n\n8. In the resulting page, you can sign in with the same username and password you just signed in on the Terminal tab with.\n\n9. You should now be in something that looks very much like RStudio but is housed in a tab on your browser! We will work together from here on out so once you have reached this point, let our team know and we can gather the group before continuing.\n\nIf the above steps have not resulted in successfully accessing Aurora, consult [NCEAS' instructions on first login](https://help.nceas.ucsb.edu/NCEAS/Computing/first_login_to_nceas_analytical_server) and/or [SSH-specific instructions for Mac vs. Windows](https://help.nceas.ucsb.edu/NCEAS/Computing/connecting_to_linux_using_ssh.html) and/or email us!\n\n### Connecting GitHub and the Server\n\nYour server \"self\" is essentially a different computer that you access via a browser (or command line in some cases). Because of this, you will need to tell GitHub that your server self is allowed to access your GitHub self's content. To do this you'll need to authenticate via personal access token or SSH key pair. Revisit our [authentication instructions](https://nceas.github.io/scicomp-workshop-collaborative-coding/#connect-git-and-github) in the \"Workshop Preparation\" section of the workshop home page for details.\n\n:::callout-tip\n## Server + PAT Note\n\nIf you choose token-based authentication you'll also need to tell the server to store your token for some amount of time otherwise the server will \"forget\" it between sessions.\n\nIn the Terminal pane of the server's RStudio session run the following code: \n\n\n::: {.cell}\n\n```{.bash .cell-code}\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n:::\n\n\nThis tells your server self to remember your token for 10 million minutes (roughly 20 years).\n:::\n\n### Optional Other Steps\n\nYou may want to configure additional settings, such as:\n\n- The default branch name (for new repositories)\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::git_default_branch_configure(name = \"main\")\n```\n:::\n\n\n## Working on the Server\n\nOnce you're properly set up, working on the server should be completely seamless! Instead of opening RStudio on your computer you'll open a browser and work on the server from there but otherwise the feeling and process of version control should be identical. Eventually you may even want to make commits on your computer, push them to GitHub (after pulling!), then pull those same commits down to your server self and continue working there.\n\nYou'll find working on the server to be dramatically faster for computationally-intense operations so we hope this guide has been helpful in getting you prepared to take advantage of that benefit!\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/branches.qmd b/branches.qmd index da34308..1331a16 100644 --- a/branches.qmd +++ b/branches.qmd @@ -6,25 +6,25 @@ title: "Branches" By the end of this module, you will be able to: -- Define "branch" in the context of `git`/GitHub +- Define "branch" in the context of Git/GitHub - Summarize the main steps of a workflow that uses branches - Create a branch on an existing repository ## What is a Branch? -A **branch** is essentially a working environment in your `git` repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the `git` vocabulary words discussed earlier (e.g., "commit", "push", etc.). +A **branch** is essentially a working environment in your Git repository that is separate from your main working area. This can be incredibly useful when you have a task to work on but you don't want to risk damaging the version of your code that already works. Note that "branch" can be either a noun or a verb as with many of the Git vocabulary words discussed earlier (e.g., "commit", "push", etc.). Branches are typically created with **the intent to put the work in the branch back into the main branch when you are done with it.** Implicit in that rationale is the fact that most branches are created with a specific task/sub-task in mind and known to be temporary from the outset. -As an example, imagine that you want to put a better engine in your car but you don't want to risk damaging your car as you go about that job. In `git` terms you could create a branch to work on those mechanical improvements while at the same time preserving your original car separately (in the "main" branch). When you're done experimenting and happy with the new version of your car, you can merge the two cars keeping all of the improvements you made in your branch. +As an example, imagine that you want to put a better engine in your car but you don't want to risk damaging your car as you go about that job. In Git terms you could create a branch to work on those mechanical improvements while at the same time preserving your original car separately (in the "main" branch). When you're done experimenting and happy with the new version of your car, you can merge the two cars keeping all of the improvements you made in your branch. -Even if you think you've never worked with `git` branches you actually have! All `git` repositories actually start in a branch named "main" so even if you've never intentionally created a branch, you've been working in your "main" branch all along. +Even if you think you've never worked with Git branches you actually have! All Git repositories actually start in a branch named "main" so even if you've never intentionally created a branch, you've been working in your "main" branch all along. ## Brief Overview of Branch Workflow -Before diving into the specifics of how to use branches while working with `git`, let's take a look at a general overview of that process. +Before diving into the specifics of how to use branches while working with Git, let's take a look at a general overview of that process. -As with many other `git` operations, the first thing to do is **pull** from GitHub to your local repository to ensure that you're working with the most up-to-date version of everything in the repo (see **Step 1** below). +As with many other Git operations, the first thing to do is **pull** from GitHub to your local repository to ensure that you're working with the most up-to-date version of everything in the repo (see **Step 1** below). Once that is done, you can create a branch on your local machine (automatically shifting your RStudio project into that new branch). Doing this on your machine also updates GitHub to show that there are multiple branches (see **Step 2** below). @@ -38,7 +38,7 @@ Given that most branches are not used again after they are merged, it is often a However, deletion of the branch either locally or via GitHub **must** come *after* step 5! -As you can see from the above text and the below diagram, branches have a few more moving parts than the `git` and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts"). +As you can see from the above text and the below diagram, branches have a few more moving parts than the Git and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts").

@@ -64,7 +64,7 @@ Once you're happy with the name, click **"Create"** (you can ignore the other op

-This will create a confirmation message that is superficially similar to the format of messages returned by other `git` actions. +This will create a confirmation message that is superficially similar to the format of messages returned by other Git actions.

@@ -85,7 +85,7 @@ You can now work in a branch *in the same way* that you work with GitHub via RSt 3. **Pull** from GitHub to reduce the chances of a conflict 4. **Push** your committed changes to GitHub -The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in `git` is functionally done in the "main" branch of your repository. +The reason you use the same workflow is--as previously stated--even if you don't typically use branches, all work in Git is functionally done in the "main" branch of your repository. For a more in-depth review of the RStudio-GitHub workflow, see Chapter 3: Using GitHub via Rstudio diff --git a/conflicts.qmd b/conflicts.qmd index 64d09db..9422775 100644 --- a/conflicts.qmd +++ b/conflicts.qmd @@ -12,7 +12,7 @@ By the end of this module, you will be able to: ## What is a Merge Conflict? -Merge conflicts are a normal part of the `git` workflow so don't get discouraged when you run into them! They occur when `git` cannot figure out how to automatically merge new changes together. This can happen when you and your collaborators change the same lines in the same file without first pulling the changes that the other party has made. +Merge conflicts are a normal part of the Git workflow so don't get discouraged when you run into them! They occur when Git cannot figure out how to automatically merge new changes together. This can happen when you and your collaborators change the same lines in the same file without first pulling the changes that the other party has made. ## Brief Overview of Merge Conflict Workflow @@ -70,7 +70,7 @@ After clicking **Pull**, we get a new error mess ![](images/conflicts/conflicts-7-birds-pull.png) -Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. `git` is urging us to manually fix the conflicted lines before continuing. +Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. Git is urging us to manually fix the conflicted lines before continuing.

diff --git a/forks.qmd b/forks.qmd index 7301b69..432c879 100644 --- a/forks.qmd +++ b/forks.qmd @@ -6,21 +6,21 @@ title: "Forks" By the end of this module, you will be able to: -- Define "fork" in the context of `git`/GitHub +- Define "fork" in the context of Git/GitHub - Contrast forks with branches - Use the fork feature on GitHub for an existing repository ## What is a Fork? -A **fork** is a duplicate of a `git` repository that is owned by someone other than you. Any repository that you can view on GitHub, you can fork. Forks allow you to start with a complete repository and then edit it for your own use as needed. +A **fork** is a duplicate of a Git repository that is owned by someone other than you. Any repository that you can view on GitHub, you can fork. Forks allow you to start with a complete repository and then edit it for your own use as needed. -The difference between **forks** and **branches** is a source of great confusion for many (even veteran!) `git` users but hopefully this list helps to clarify: +The difference between **forks** and **branches** is a source of great confusion for many (even veteran!) Git users but hopefully this list helps to clarify: 1. A fork creates a new repository while a branch exists within a given repository 2. A fork is owned by a different user/organization than the original, a branch does not change repository ownership -3. A fork's "parent" repository is not recognized by `git` but `git` does 'know' which branch a given branch originates from. +3. A fork's "parent" repository is not recognized by Git but Git does 'know' which branch a given branch originates from. ## Choosing Whether to Fork or to Branch @@ -32,7 +32,7 @@ It is important to note that both forks and branches can be merged back into the ## Brief Overview of Fork Workflow -Forking is (arguably) one of the more straightforward `git` workflows but before we cover it in detail, let's review the broader context. +Forking is (arguably) one of the more straightforward Git workflows but before we cover it in detail, let's review the broader context. You begin by going to the GitHub page for a repository that you do not own. From there, there is a convenient "Fork" button you can click that (after a screen very much like that of creating a new repository) creates a duplicate of the repository in your profile's repository list. diff --git a/git_ignore.qmd b/git_ignore.qmd index 91162e7..062b08c 100644 --- a/git_ignore.qmd +++ b/git_ignore.qmd @@ -12,7 +12,7 @@ By the end of this module, you will be able to: ## Overview -The purpose of the `.gitignore` is evident in its name: anything included in it is *ignored by `git`*. This can be useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a GitHub repository you plan to make public at some point. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators. +The purpose of the `.gitignore` is evident in its name: anything included in it is *ignored by Git*. This can be useful if you want to include data in your local version of your repository but don't want to risk sharing that data by committing it to a GitHub repository you plan to make public at some point. This file exists at the top level of every repository and can be customized however is most useful to you and your collaborators. ## Creating a `.gitignore` @@ -50,7 +50,7 @@ After you click it you'll be looking at a file that looks very similar to any ot

-Now let's add something to it! As you can see from the Git pane of the above image (top right), after cloning our new repository, the only file `git` is flagging as untracked is the .Rproj file created whenever you make a new RStudio project. +Now let's add something to it! As you can see from the Git pane of the above image (top right), after cloning our new repository, the only file Git is flagging as untracked is the .Rproj file created whenever you make a new RStudio project. If we add `*.Rproj` to our `.gitignore`, the Git pane will show that the only change is that lines have been added to the `.gitignore`. The .Rproj file with the double yellow question marks next to it is gone! @@ -81,7 +81,7 @@ There are many different opinions on what should go into a `.gitignore` but we h 3. **Other Considerations** - Some people recommend adding everything your script creates to the `.gitignore`. The theory being that if someone wants to see those outputs, they would only need to run your script(s) in order to create their own versions - - Another way of thinking about this is to create a dedicated folder to store products in (e.g., "data", "exports", etc.) and then add that folder to the `.gitignore`. This means you don't need to worry about adding specific files to the `.gitignore` so long as all the files live in a folder you've already designated as something for `git` to not track + - Another way of thinking about this is to create a dedicated folder to store products in (e.g., "data", "exports", etc.) and then add that folder to the `.gitignore`. This means you don't need to worry about adding specific files to the `.gitignore` so long as all the files live in a folder you've already designated as something for Git to not track 4. Do you have another idea for what you typically add to a `.gitignore`? @@ -135,11 +135,11 @@ Ultimately, this is up to you and your team to decide! Hopefully our outlined re ## Ignoring Previously Tracked Content -Imagine a situation where you commit a data file to your GitHub repository and push that commit. Now your data file is tracked by `git` and every time you alter that file RStudio's "Git" pane will notify you that the file changed by placing the blue "M" next to the file's name. Let's say that eventually you decide that you want to (1) remove the file from your GitHub repository and (2) stop `git` from tracking *future* changes to the file. If this is the case, you'll need to do the following: +Imagine a situation where you commit a data file to your GitHub repository and push that commit. Now your data file is tracked by Git and every time you alter that file RStudio's "Git" pane will notify you that the file changed by placing the blue "M" next to the file's name. Let's say that eventually you decide that you want to (1) remove the file from your GitHub repository and (2) stop Git from tracking *future* changes to the file. If this is the case, you'll need to do the following: 1. Either (A) delete the file or (B) move it out of the repository's folder - - Either option will register as "deleting" the file from `git`'s perspective + - Either option will register as "deleting" the file from Git's perspective 2. **Commit** the deletion @@ -147,4 +147,4 @@ Imagine a situation where you commit a data file to your GitHub repository and p 4. Add the name of that file to your `.gitignore` -Once you've done these steps, even if you put the file back in your repository, `git` won't track its addition or any changes to it over time. +Once you've done these steps, even if you put the file back in your repository, Git won't track its addition or any changes to it over time. diff --git a/github.qmd b/github.qmd index ba08e3d..4cb2de5 100644 --- a/github.qmd +++ b/github.qmd @@ -1,19 +1,19 @@ --- -title: "`git` & GitHub" +title: "Git & GitHub" --- ## Module Learning Objectives By the end of this module, you will be able to: -- Describe the difference between `git` and GitHub +- Describe the difference between Git and GitHub - Navigate GitHub via a web browser - Use GitHub to create a new repository - Edit a new repository through GitHub's interface ## Version Control Background -Version control systems (including `git`) are built to preserve the iterative versions that we create on the way to a final product. For instance, when writing a scientific manuscript we might have several discrete stages (e.g., separate drafts after successive rounds of feedback from collaborators) as well as the sort of small-scale changes we don't necessarily preserve in separate files (e.g., workshopping a particular sentence for rhetorical flow). +Version control systems (including Git) are built to preserve the iterative versions that we create on the way to a final product. For instance, when writing a scientific manuscript we might have several discrete stages (e.g., separate drafts after successive rounds of feedback from collaborators) as well as the sort of small-scale changes we don't necessarily preserve in separate files (e.g., workshopping a particular sentence for rhetorical flow). **Version control systems provide a framework for preserving these changes without cluttering your computer with all of the files that precede the final version.** @@ -21,19 +21,19 @@ Version control systems (including `git`) are built to preserve the iterative ve

-## `git`-Specific Background +## Git-Specific Background -`git` can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In `git` (and other version control systems) terms, this "tracked folder" is called a **repository** (which formally is a specific data structure storing versioning information). +Git can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In Git (and other version control systems) terms, this "tracked folder" is called a **repository** (which formally is a specific data structure storing versioning information). Although there many ways to start a new repository, [GitHub](https://github.com/) (or any other cloud solutions, such as [GitLab](https://about.gitlab.com/)) provide among the most convenient way of starting a repository. -Let's distinguish between `git` and GitHub: +Let's distinguish between Git and GitHub: -- __`git`__: version control software used to track files in a folder (a repository) - - `git` creates the versioned history of a repository -- __GitHub__: website that allows users to store their `git` repositories and share them with others (i.e. a graphical user interface or "GUI") +- __Git__: version control software used to track files in a folder (a repository) + - Git creates the versioned history of a repository +- __GitHub__: website that allows users to store their Git repositories and share them with others (i.e. a graphical user interface or "GUI") -**GitHub is a company that hosts `git` repositories online** and provides several collaboration features. GitHub fosters a great user community and has built a nice web interface to `git`, also adding great visualization/rendering capacities of your data. +**GitHub is a company that hosts Git repositories online** and provides several collaboration features. GitHub fosters a great user community and has built a nice web interface to Git, also adding great visualization/rendering capacities of your data. - **GitHub.com**: - **A user account**: @@ -86,7 +86,7 @@ And finally, if we examine one of the changes made on April 25, we can see exact -The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what `git` and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow. +The red lines have been deleted while the green lines are new additions. Tracking these changes, and seeing how they relate to released versions of software and files is exactly what Git and GitHub are good for. We will show how they can really be effective for tracking versions of scientific code, figures, and manuscripts to accomplish a reproducible workflow. Note: it is possible to edit and add files entirely on the GitHub website, by navigating to the specific file or repository. However, for this workshop, we will be editing and adding files through RStudio instead. diff --git a/index.qmd b/index.qmd index 64ef174..da3dd81 100644 --- a/index.qmd +++ b/index.qmd @@ -4,51 +4,61 @@ title: "Overview" ### Welcome! -This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using `git` via RStudio and GitHub**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://nceas.github.io/scicomp-workshop-collaborative-coding/issues) on our GitHub repository if you see clear areas for improvement! +This workshop provides an overview of what "version control" systems are and how they fit into collaborative coding within your team. Specifically, **we are focusing here on an introductory approach to version control that focuses on using Git via RStudio and GitHub**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://nceas.github.io/scicomp-workshop-collaborative-coding/issues) on our GitHub repository if you see clear areas for improvement! To maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. Depending on whether you've used RStudio and/or GitHub before you may have already completed some or all of these steps but please read through the following materials regardless to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the "Content Creators" tab. -## Programs to Install +## Workshop Preparation -**Note for those of you with a dedicated IT team that has sole power to install software on your computer:** you will need to contact them before the workshop to install the following programs. +**For those of you with a dedicated IT team that has sole power to install software on your computer:** you will need to contact them before the workshop to do the installation bits of the prep steps we outline below. -### R & RStudio +### 1. Install R -**Install [R](https://www.r-project.org/) and its more convenient (in our opinion) user-interface: [RStudio](https://www.rstudio.com/products/rstudio/download/)**. +Begin by installing [R](https://www.r-project.org/). If you already have R, check that you have at least version 4.0.0 by running the following code: -If you already have R, check that you have at least version 4.0.0 by running the following code: - -```{r, eval = F} +```{r r-ver-check, eval = F} version$version.string ``` If your version starts with a 3 (e.g., the above code returns "R version 3..."), please update R to make sure all packages behave as expected. -### `git` +### 2. Install RStudio + +Once you have R (ver. ≥4.0), install [RStudio](https://posit.co/download/rstudio-desktop/). If you already have RStudio installed, you may want to make sure that you're using a recent version to take advantage of some quality of life improvements that are broadly useful. -**[Install `git`](https://happygitwithr.com/install-git.html)** +### 3. Install Git -**If you are a Windows user**, be sure to follow along with "Option 1" in the instructions linked above! That variant gives some under-the-hood tools we'll implicitly rely on later. +With R and RStudio installed you can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Jennifer Bryan's "Happy Git and GitHub for the useR" digital book does a really nice job covering how to install Git for different computer operating systems (i.e., Mac vs. Windows vs. Linux). + +Consult Dr. Bryan's [Git installation instructions](https://happygitwithr.com/install-git.html) and _be sure to follow the steps relevant for **your** operating system!_ **If you are a Windows user**, be sure to follow along with "Option 1" in the instructions linked above! That variant gives some under-the-hood tools we'll implicitly rely on later. :::callout-tip -## RStudio not detecting `git`? +## RStudio not detecting Git? -If you had your RStudio session open while you installed `git` for the first time, RStudio may not have detected `git` on your computer. In that case, please close and restart RStudio. Check if RStudio is able to detect it now by going to Tools -> Global Options -> Git/SVN. If you see a file path under "Git executable" then you are good to go! +If you had your RStudio session open while you installed Git for the first time, RStudio may not have detected Git on your computer. In that case, please close and restart RStudio. Check if RStudio is able to detect it now by going to Tools -> Global Options -> Git/SVN. If you see a file path under "Git executable" then you are good to go! ::: -Once you've successfully installed R, RStudio, and `git`, follow the rest of the setup instructions below. +### 4. Create a GitHub Account + +Now that you're all done installing programs, it's time to create an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others. Dr. Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) and we also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub. -## Accounts to Create / Connect +### 5. Connect Git and GitHub -### GitHub +The last step to take before you're all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you'll need to _authenticate_ yourself. There are two paths for authentication: -**[Create a GitHub account](https://happygitwithr.com/github-acct.html)** using your web browser of choice. +1. Personal Access Token (PAT) +2. Secure Shell (SSH) -Next, you will have to **connect `git` to your GitHub profile** and then **create a personal access token (PAT)**. A token is essentially a more secure password that `git` requires. You can accomplish these two steps by running the following code in RStudio: +What's the difference? Essentially, authenticating via token makes many things "just work" while authenticating via SSH will work for some things but in other contexts you would _also_ need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan's "[HTTPS versus SSH](https://happygitwithr.com/https-pat#https-vs-ssh)" page. -```{r token-process, eval = FALSE} +Follow the steps of your chosen authentication method in the tabs below. + +:::panel-tabset +#### Personal Access Token + +```{r token-process-1, eval = FALSE} # Install the `usethis` and `gitcreds` packages #install.packages(c("usethis", "gitcreds")) library(usethis); library(gitcreds) @@ -58,17 +68,56 @@ usethis::use_git_config(user.name = "Jane Doe", user.email = "jane@example.org") # Create a token (Note this will open a GitHub browser tab) -# See steps 6-10 in GitHub's tutorial (link below) +## See steps 6-10 in GitHub's tutorial (link below) usethis::create_github_token() +``` -# Copy your Personal Access Token at the end of the above step! +_Copy your token at the end of the above step._ Once you leave the page where your token is displayed you'll never get to see it again! So if you close that page without copying it you'll need to make a new one in order to continue. +```{r token-process-2, eval = FALSE} # Now, give your token to RStudio -# After you run this line you'll follow some prompts in the "Console" tab of RStudio gitcreds::gitcreds_set() +## After you run this line you'll follow some prompts in the "Console" tab of RStudio ``` -At the end of the above steps your token should be set! For additional information, see [GitHub's PAT Tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or the [Happy Git with R PAT Tutorial](https://happygitwithr.com/https-pat.html). If this seems a little intimidating, please keep in mind that your experience with downloading programs and creating web accounts will help with these tasks even if you have more minimal coding experience! +##### Further Information + +You may also find [GitHub's PAT tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful. + +#### SSH + +Begin by using the command line (a.k.a. "shell" or "Terminal") to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn't exist, you do not have SSH keys (yet). + +```{bash ssh-check, eval = F} +ls -al ~/.ssh/ +``` + +If you do need to create an SSH key pair you can do so via the command line. When you create a key pair you'll need to include a descriptive comment to help 'future you' if you ever have multiple key pairs in your life. We recommend "lter" plus your GitHub username to keep things simple. + +```{bash ssh-make, eval = F} +ssh-keygen -t ed25519 -C "lter-github" +``` + +:::callout-tip +## Older Computer? + +If you get a warning/error because your system is too old to support the Ed25519 algorithm (that's the variant recommended by GitHub) you can instead use: + +```{bash ssh-make-variant, eval = F} +ssh-keygen -t rsa -b 4096 -C "lter-github" +``` +::: + +Accept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. If SSH keys are totally new to you, we recommend skipping the passphrase step. + +Once you've generated the key pair, follow [GitHub's instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) on adding that key pair to your computer's ssh-agent (roughly equivalent to a password manager but just for SSH key pairs). + +Finally, you need to share the public key with your GitHub self. Once again we'll refer you to [the phenomenal materials](https://happygitwithr.com/ssh-keys#provide-public-key-to-github) generated by Dr. Bryan on this topic. + +##### Further Information + +You may also find [GitHub's SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or the [Happy Git with R SSH tutorial](https://happygitwithr.com/ssh-keys) helpful. +::: ## GitHub + Science Publications diff --git a/rstudio.qmd b/rstudio.qmd index 2ce9cb7..b2a5145 100644 --- a/rstudio.qmd +++ b/rstudio.qmd @@ -7,12 +7,12 @@ title: "RStudio" By the end of this module, you will be able to: - Describe the computer-to-GitHub order of operations -- Define fundamental `git` vocabulary +- Define fundamental Git vocabulary - Create a local version-controlled repository that is connected to GitHub -## Overview of `git` Workflow +## Overview of Git Workflow -Before we get into using `git` and GitHub through RStudio, it will be helpful to review the major steps of including version control as you work on code. +Before we get into using Git and GitHub through RStudio, it will be helpful to review the major steps of including version control as you work on code. Beginning on your local computer, you make **changes** to a file in a folder that you have previously marked for version control tracking (i.e., a **working directory**). Once those changes are made you can **stage changes** within your local computer. After staging, it is best to retrieve the latest file versions from the cloud. You likely will already be up-to-date but this preemptive step can save you a lot of heartache down the line. Once you've confirmed that you have the latest file versions, you can shift the revised file(s) to the cloud where any GitHub users with access to your project can access the most recent file and look at the history of all previous changes. @@ -20,7 +20,7 @@ Beginning on your local computer, you make **changes

-## `git` Vocabulary +## Git Vocabulary Finally, it will be helpful to introduce four key pieces of vocabulary before we dive into the interactive component of this workshop. @@ -38,7 +38,7 @@ Finally, it will be helpful to introduce four key pieces of vocabulary before we ## Cloning a Repository -Now, the first step in using `git` with RStudio is cloning the repository from GitHub. Note for clarity that in the screenshots below, **GitHub is in dark mode** while **RStudio is in light mode**. To clone a repository, follow these steps: +Now, the first step in using Git with RStudio is cloning the repository from GitHub. Note for clarity that in the screenshots below, **GitHub is in dark mode** while **RStudio is in light mode**. To clone a repository, follow these steps: Navigate to the repository on GitHub and click on **Code**. Select **HTTPS** and copy the link. @@ -59,7 +59,7 @@ Select **Version Control**.

-Select **`git`**. +Select **Git**.

@@ -77,14 +77,14 @@ Now we have finished cloning the repository to our RStudio! Notice that we are w ## Workflow Refresher -The typical workflow with `git` goes like this: +The typical workflow with Git goes like this: **Step 1**: You modify files in your working directory and save them as usual. **Step 2**: You **stage** files to mark your intention to "commit" them and then **commit** that version of those files. - In RStudio, "staging" is done by checking the box next to a given file in the "Git" tab - - Committing files permanently stores them as snapshots to your `git` directory + - Committing files permanently stores them as snapshots to your Git directory **Step 3**: You **pull** the most recent changes to make sure you've been editing the latest versions. @@ -107,19 +107,19 @@ This 2-step process enables you to flexibly group files into a specific commit. ## Creating a New File -Let's try out a simple `git` workflow by first creating a new file. This is **Step 1** of the process. We can add new R scripts and files to our repository through RStudio. Try creating a new script by going to **File** > **New File** > **R Script**. Feel free to type anything you want into this script as an example. Name this script after yourself. In the screenshot below, I have named my script `angel-script.R`. +Let's try out a simple Git workflow by first creating a new file. This is **Step 1** of the process. We can add new R scripts and files to our repository through RStudio. Try creating a new script by going to **File** > **New File** > **R Script**. Feel free to type anything you want into this script as an example. Name this script after yourself. In the screenshot below, I have named my script `angel-script.R`. -Once you are done, navigate to the **`git`** tab on the upper left corner. You should see your new script show up there along with a `.gitignore` and `git-practice.Rproj` file. Do not worry about the `.gitignore` file for now, it was created by RStudio to make sure that some temporary files are not tracked by `git`. The `git-practice.Rproj` file will save your settings and open tabs when you close the project, and will restore these settings the next time you open it. +Once you are done, navigate to the **Git** tab on the upper left corner. You should see your new script show up there along with a `.gitignore` and `git-practice.Rproj` file. Do not worry about the `.gitignore` file for now, it was created by RStudio to make sure that some temporary files are not tracked by Git. The `git-practice.Rproj` file will save your settings and open tabs when you close the project, and will restore these settings the next time you open it. -Notice that there are color-coded icons next to the files in the "Git" tab. These icons are shorthand for the status--according to `git`--of every* file in your working directory. Not technically "every" file because files that are tracked but haven't been modified are not included. See below for definitions. +Notice that there are color-coded icons next to the files in the "Git" tab. These icons are shorthand for the status--according to Git--of every* file in your working directory. Not technically "every" file because files that are tracked but haven't been modified are not included. See below for definitions.

-In our case, it means that our R script, `.gitignore`, and `git-practice.Rproj` files have never been tracked by `git` (since these files were just created). Note also that the `README.md` file is not listed, but it exists (check the Files pane). It is because files that are tracked but have no modifications since the last commit are not listed. +In our case, it means that our R script, `.gitignore`, and `git-practice.Rproj` files have never been tracked by Git (since these files were just created). Note also that the `README.md` file is not listed, but it exists (check the Files pane). It is because files that are tracked but have no modifications since the last commit are not listed. ### Adding our Script to the Next Commit @@ -129,11 +129,11 @@ Let us look at the diff of our script. Click on the **Diff** tab.

-Checking our script, we can see the new lines that we just typed are in green, which indicates that these lines have been added for `git`. We would like to save a snapshot of this version of our script. Since we've just done **Step 1**, here are the rest of the steps we will need to do to get our script to show up on our GitHub repository: +Checking our script, we can see the new lines that we just typed are in green, which indicates that these lines have been added for Git. We would like to save a snapshot of this version of our script. Since we've just done **Step 1**, here are the rest of the steps we will need to do to get our script to show up on our GitHub repository: **Step 2**: Add the file to the next commit by checking the box in front of the file name. Note that the two `?` icons will change to a single `A` on the left to show you that this file is now staged to be part of the next commit. -**Step 3**: In the right pane, type a short but descriptive commit message detailing what you have done so far. Then click on the **Commit** button to save this version of the script in the `git` database. +**Step 3**: In the right pane, type a short but descriptive commit message detailing what you have done so far. Then click on the **Commit** button to save this version of the script in the Git database. @@ -141,17 +141,17 @@ If all of the above steps went well, you should see something like this: -Notice that `git` tells us that `1 file changed` because we've just added a new file to our commit. Now close the window. Before sending our changes back to GitHub, we should make sure that the copy of the repository on RStudio is completely up-to-date with the one on GitHub to avoid any conflicts. +Notice that Git tells us that `1 file changed` because we've just added a new file to our commit. Now close the window. Before sending our changes back to GitHub, we should make sure that the copy of the repository on RStudio is completely up-to-date with the one on GitHub to avoid any conflicts. ### Getting the Latest Updates -There are two `git` commands to exchange between a local and remote versions of a repository: +There are two Git commands to exchange between a local and remote versions of a repository: -- `pull`: `git` will get the latest remote version and try to merge it with your local version +- `pull`: Git will get the latest remote version and try to merge it with your local version -- `push`: `git` will send your local version to the remote version of the repository (in our case GitHub) +- `push`: Git will send your local version to the remote version of the repository (in our case GitHub) -**Before sending your local version to the remote**, you should always get the latest remote version first. In other words, you should pull first and push second. This is the way `git` protects the remote version against incompatibilities with the local version. You always deal with potential problems on your local machine. Therefore your sequence will always be: +**Before sending your local version to the remote**, you should always get the latest remote version first. In other words, you should pull first and push second. This is the way Git protects the remote version against incompatibilities with the local version. You always deal with potential problems on your local machine. Therefore your sequence will always be: 1. Commit 2. `pull` @@ -203,4 +203,4 @@ If your personal access token (PAT) was not set up correctly with RStudio or if Great! Now that your script has been added to the group repository, you should try to repeat the same workflow over again just to get a feel for how it works. Go back to RStudio and edit your own script. Save those edits, add your edited file to the staging area, write a commit message, then commit your changes. After committing, make sure to pull first then push after! When you pull, you might notice that scripts from your group members/collaborators will show up in your RStudio files. -Make sure to work on your own script. If you and another group member work on the same script at the same time, this may lead to merge conflicts with `git`. If two people were to work on the same script, they may be making different edits on the same lines, and `git` would not know which edits to keep. To avoid merge conflicts, be mindful of what files you are working on and always communicate this to your group members! +Make sure to work on your own script. If you and another group member work on the same script at the same time, this may lead to merge conflicts with Git. If two people were to work on the same script, they may be making different edits on the same lines, and Git would not know which edits to keep. To avoid merge conflicts, be mindful of what files you are working on and always communicate this to your group members! diff --git a/server.qmd b/server.qmd index 3ffd7ab..110cb9b 100644 --- a/server.qmd +++ b/server.qmd @@ -66,66 +66,23 @@ In the following instructions, all words that look `like this` should be typed i If the above steps have not resulted in successfully accessing Aurora, consult [NCEAS' instructions on first login](https://help.nceas.ucsb.edu/NCEAS/Computing/first_login_to_nceas_analytical_server) and/or [SSH-specific instructions for Mac vs. Windows](https://help.nceas.ucsb.edu/NCEAS/Computing/connecting_to_linux_using_ssh.html) and/or email us! -## Working on the Server - -### Step 1: Connect Server RStudio with GitHub - -To begin, load the `usethis` package (install if needed). -```{r load-libraries, eval = F} -# install.packages("usethis") -library(usethis) -``` - -Next, configure your name and the email address you use for your GitHub account. - -```{r config-user-profile, eval = F} -usethis::use_git_config(user.name = "Jane Doe", - user.email = "jane@example.org") -``` +### Connecting GitHub and the Server -If you would like to check that this worked, you can go to the "Terminal" tab (next to the "Console" tab) and run `git config --global --list`. +Your server "self" is essentially a different computer that you access via a browser (or command line in some cases). Because of this, you will need to tell GitHub that your server self is allowed to access your GitHub self's content. To do this you'll need to authenticate via personal access token or SSH key pair. Revisit our [authentication instructions](https://nceas.github.io/scicomp-workshop-collaborative-coding/#connect-git-and-github) in the "Workshop Preparation" section of the workshop home page for details. -### Step 2: Create GitHub Token +:::callout-tip +## Server + PAT Note -You may use your token that you already generated for your local RStudio if that is easiest, but you can also create a new token specifically for your Server identity. +If you choose token-based authentication you'll also need to tell the server to store your token for some amount of time otherwise the server will "forget" it between sessions. -To create a token, you can again use the `usethis` package to send you to the relevant part of the GitHub website. +In the Terminal pane of the server's RStudio session run the following code: -```{r create-token, eval = F} -usethis::create_github_token() +```{bash token-remember, eval = F} +git config --global credential.helper 'cache --timeout=10000000' ``` -Once you have walked through that process and created a new token **COPY** the long string of letters and numbers. It is often a good move to take a screenshot of the token and store it on your computer for a rainy day. - -### Step 3: Store GitHub Token - -To store the token in your server identity, run the following line of code: - -```{r store-token, eval = F} -gitcreds::gitcreds_set() -``` - -In the "Console" tab you will be prompted to follow a short set of questions (answered via entering numbers in the Console) including the Console requesting your GitHub token. - -**PASTE** the long string you copied in the previous step into the supplied field and continue. Note that if you did not copy the token (or copied something else between then and now thus losing the token from your clipboard) you can refer to the screenshot we recommended you take upon first generating the token. - -### Step 4: Preserve GitHub Token - -You will also need to tell the server to remember your token so that you don't need to re-do the "Store GitHub Token" section every time you start a new R session. - -Unfortunately, there are two limitations to this step: - -1) Storage can only be done in the "Terminal" pane with the command line (don't worry, it's only one line!) - -2) Storage must be for a finite amount of time (though it can be a long time!) - -To make the system remember your token, in the "Terminal" pane of RStudio type the following: - -`git config --global credential.helper 'cache --timeout=10000000'` - -This will cache your "credentials" (i.e., your token) for a long time so that you need not worry about this for the time being. - -Not running the above line will make your personal access token expire immediately in the system, even though GitHub considers its expiration date (that you set earlier) separately. +This tells your server self to remember your token for 10 million minutes (roughly 20 years). +::: ### Optional Other Steps @@ -136,3 +93,9 @@ You may want to configure additional settings, such as: ```{r default-branch-name, eval = F} usethis::git_default_branch_configure(name = "main") ``` + +## Working on the Server + +Once you're properly set up, working on the server should be completely seamless! Instead of opening RStudio on your computer you'll open a browser and work on the server from there but otherwise the feeling and process of version control should be identical. Eventually you may even want to make commits on your computer, push them to GitHub (after pulling!), then pull those same commits down to your server self and continue working there. + +You'll find working on the server to be dramatically faster for computationally-intense operations so we hope this guide has been helpful in getting you prepared to take advantage of that benefit!