diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json index 6ecf900..cee8102 100644 --- a/_freeze/index/execute-results/html.json +++ b/_freeze/index/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "ab10ec0937af57241d756ba979442bde", + "hash": "34057b3efdeb32051e063b60fbe52d7a", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"Overview\"\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://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! \n\n\"Logo\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 \"SciComp Team\" dropdown menu in the \"People\" page.\n\n### Citing These Materials\n\nIf you'd like to cite these materials, please use the following citation:\n\n> Lyon, N.J., Chen, A., and Brun, J. (2025). Collaborative Coding with GitHub (v1.3). Zenodo. [https://doi.org/10.5281/zenodo.16966957](https://doi.org/10.5281/zenodo.16966957)\n\n## Workshop Preparation\n\nThe below preparation includes some code chunks for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In both cases, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the \"Console\" tab of RStudio while {{< fa terminal >}} command line code should be run in the \"Terminal\" tab of RStudio.\n\nIf you get errors with the provided code, _double check that you are running it in the right place!_\n\n:::{.callout-note}\n#### Institution-Owned Computers\n\nIf your institution has 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\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 {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\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. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent \"[Happy Git and GitHub for the useR](https://happygitwithr.com/)\" ebook.\n\n:::{.panel-tabset}\n#### {{< fa brands apple >}} Mac\n\nIn RStudio's \"Terminal\" pane, run the following {{< fa terminal >}} command line code.\n\n```\n# Run me in RStudio's \"Terminal\"\nxcode-select --install\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).\n\n#### {{< fa brands windows >}} Windows\n\n[Install Git for Windows](https://gitforwindows.org/) (a.k.a. \"Git Bash\"). When asked about \"Adjusting your PATH environment\", **select \"Git from the command line and also from 3rd-party software\"**.\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).\n\n#### {{< fa brands linux >}} Linux\n\nInstall Git via your distro's package manager (in the {{< fa terminal >}} Terminal).\n\nIf you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:\n\n```\nsudo apt-get install git\n```\n\nIf instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:\n\n```\nsudo yum install git\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).\n\n:::\n\n### 4. Check Git's Installation Worked\n\nRegardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this in the \"Terminal\" pane of RStudio.\n\n```\n# Run me in RStudio's \"Terminal\"\nwhich git\n```\n\nRStudio should be able to detect Git so let's check from that side too. In RStudio click through the following menus: \"Tools\" {{< fa arrow-right >}} \"Global Options\" {{< fa arrow-right >}} \"Git / SVN\" (cardboard box icon in left sidebar). **If you see a file path under \"Git executable\" then you are good to go!**\n\n:::{.callout-note}\n#### Git Not Detected?\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 before checking again.\n:::\n\n### 5. 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### 6. 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**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\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\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so, your token will be safely stored in RStudio! \n\n

\n\"Screenshot\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) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be run in the \"Terminal\" pane of RStudio.**\n\nFirst, we need 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### 7. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\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\"Figure\n

\n", + "markdown": "---\ntitle: \"Overview\"\n---\n\n### Welcome!\n\n\"Logo\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 GitHub either by itself or with Git via RStudio**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! \n\n### Citing These Materials\n\nIf you'd like to cite these materials, please use the following citation:\n\n> Lyon, N.J., Chen, A., and Brun, J. (2025). Collaborative Coding with GitHub (v1.3). Zenodo. [https://doi.org/10.5281/zenodo.16966957](https://doi.org/10.5281/zenodo.16966957)\n\n## Workshop Preparation\n\nTo maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. You may have already completed some or all of these steps but please read through and confirm that you've done all of the steps that are relevant to you 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 \"SciComp Team\" dropdown menu in the \"People\" page.\n\n:::{.callout-note}\n#### Institution-Owned Computers\n\nIf your institution has 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\nThere are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs.\n\n:::{.panel-tabset}\n### GitHub By Itself\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\n### GitHub with RStudio\n\n:::{.callout-note}\n#### Running Code in Following Steps\n\nThe below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In either case, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the \"Console\" tab of RStudio while {{< fa terminal >}} command line code should be run in the \"Terminal\" tab of RStudio.\n\nIf you get errors with the provided code, _double check that you are running it in the right place!_\n:::\n\n#### 1. Create a GitHub Account\n\nStart by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. \n\nDr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.\n\n\n#### 2. Install R\n\nNow you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\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\n#### 3. 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\n#### 4. Install Git\n\nYou can now install Git! Git is the software that actually does the behind-the-scenes version control operations we'll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent \"[Happy Git and GitHub for the useR](https://happygitwithr.com/)\" ebook.\n\n:::{.panel-tabset}\n#### {{< fa brands apple >}} Mac\n\nRun the following {{< fa terminal >}} command line code.\n\n```\nxcode-select --install\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#macos).\n\n#### {{< fa brands windows >}} Windows\n\n[Install Git for Windows](https://gitforwindows.org/) (a.k.a. \"Git Bash\"). When asked about \"Adjusting your PATH environment\", **select \"Git from the command line and also from 3rd-party software\"**.\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows).\n\n#### {{< fa brands linux >}} Linux\n\nInstall Git via your distro's package manager (in the {{< fa terminal >}} Terminal).\n\nIf you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows:\n\n```\nsudo apt-get install git\n```\n\nIf instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead:\n\n```\nsudo yum install git\n```\n\nFor more detailed instructions, see [here](https://happygitwithr.com/install-git#linux).\n\n:::\n\n\n#### 5. Check that Git's Installation Worked\n\nRegardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this code.\n\n```\nwhich git\n```\n\n:::{.panel-tabset}\n#### Confirm Connection in RStudio\n\nRStudio should also be able to detect Git so let's check from that side too. In RStudio click through the following menus: \"Tools\" {{< fa arrow-right >}} \"Global Options\" {{< fa arrow-right >}} \"Git / SVN\" (cardboard box icon in left sidebar). **If you see a file path under \"Git executable\" then you are good to go!**\n\nIf Git was _not_ detected, this may be caused by having your RStudio session open while you installed Git for the first time. **In that case, please close and restart RStudio before checking again.**\n\n:::\n\n\n#### 6. 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 with RStudio\n\n**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\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\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so (and hit \"Enter\"), your token will be safely stored in RStudio! \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) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.**\n\nFirst, we need 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 (yet) have SSH keys.\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\n\n#### 7. Celebrate!\n\nAfter following all the previous preparation steps, your setup should now be complete.\n\n\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\"Figure\n

\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/prep-steps/connect_git-github/execute-results/html.json b/_freeze/prep-steps/connect_git-github/execute-results/html.json new file mode 100644 index 0000000..e96c9a5 --- /dev/null +++ b/_freeze/prep-steps/connect_git-github/execute-results/html.json @@ -0,0 +1,15 @@ +{ + "hash": "7a9b64d05332bececa69be0c6658036b", + "result": { + "engine": "knitr", + "markdown": "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:\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 with RStudio\n\n**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the \"Console\" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install the `usethis` and `gitcreds` packages\ninstall.packages(c(\"usethis\", \"gitcreds\"))\n\n# Create a token (Note this will open a GitHub browser tab)\n## See steps 6-10 in GitHub's PAT tutorial (link below)\nusethis::create_github_token() # <1>\n```\n:::\n\n1. Leave parentheses empty\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\nOnce you've copied your token, run the code below to save your credentials in RStudio.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Now, give your token to RStudio\n## After you run this line follow the prompts in the \"Console\" tab of RStudio\ngitcreds::gitcreds_set() # <2>\n```\n:::\n\n2. Leave parentheses empty here as well!\n\nThis line of code will prompt you to paste your token in the \"Console\" tab. After you do so (and hit \"Enter\"), your token will be safely stored in RStudio! \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) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful.\n\n#### SSH\n\n**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.**\n\nFirst, we need 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 (yet) have SSH keys.\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", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/_freeze/prep-steps/install_r/execute-results/html.json b/_freeze/prep-steps/install_r/execute-results/html.json new file mode 100644 index 0000000..ecc422b --- /dev/null +++ b/_freeze/prep-steps/install_r/execute-results/html.json @@ -0,0 +1,15 @@ +{ + "hash": "bda4e5977ee4b3aa942b7fdbd5575fca", + "result": { + "engine": "knitr", + "markdown": "Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Run me in RStudio's \"Console\"\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", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/_freeze/server/execute-results/html.json b/_freeze/server/execute-results/html.json index 037dffa..5ed4e9b 100644 --- a/_freeze/server/execute-results/html.json +++ b/_freeze/server/execute-results/html.json @@ -2,7 +2,7 @@ "hash": "043a5b716edba5566f1e9343cd3e58a3", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"NCEAS' Server\"\n---\n\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- Explain at least one way of uploading data to a server\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. Note that our server also runs other analytical tools such as JupyterHub for python users.\n\nOften the reason to engage with the server is to increase the scale of your analyses far beyond what your personal computer can handle. There are other advantages such as:\n\n- **Storage Capacity** -- More disk space & faster storage\n- **Computing Power** -- More CPUs & RAM (384GB!!)\n- **Security** -- Nightly backups and data are distributed across multiple drives\n- **Collaboration** -- Shared data & consistent software versions accessible to everyone on your team\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 Invited!\n\nIn order to access the server (and follow the instructions below) we'll need to create an account on the server for you. Please email [someone on our team](https://lter.github.io/scicomp/staff.html) or **scicomp@nceas.ucsb.edu** so that we can contact NCEAS' IT team and get an invite email sent to you.\n\nIn that email, please include the name and email addresses of all of your team members who want to access the server. After that information has been received, NCEAS' IT team will create accounts for all of those people and will send you an invitation email to set up your account on the server.\n\nAn 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://lter.github.io/workshop-github/#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\n\n::: {.cell}\n\n```{.bash .cell-code}\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n:::\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\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::git_default_branch_configure(name = \"main\")\n```\n:::\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\n## Uploading Data to the Server\n\n### Via RStudio\n\nIf you are uploading a single file, it may be most convenient to use RStudio's data upload capabilities. In the \"Files\" pane (default is top right but it may differ on your computer), you can click the button that is a white rectangle with a **yellow** circle with an upward facing arrow inside of it. In the below image the relevant button is in a **red** square.\n\n

\n\"\"\n

\n\nClicking that button allows you to choose (1) where you want the uploaded file to go and (2) which file you want to upload.\n\n

\n\"\"\n

\n\nYou can also download data via the RStudio interface. To download a file, check the box next to it in the \"Files\" pane.\n\n

\n\"\"\n

\n\nOnce the box is checked, click the gear icon then click the \"Export...\" option (about halfway down). In the image below this option is surrounded by a **red** square\n\n

\n\"\"\n

\n\nIn the resulting box you can choose to rename the file before downloading to your local computer. After renaming the file (or keeping its original name), click the \"Download\" button and the download should begin after a moment.\n\n

\n\"\"\n

\n\nThese methods are effective for one or a few files being up/downloaded to the same directory but can quickly become cumbersome if you want to handle many files or a few files to several different folders.\n\n### Via sFTP Software\n\nIf you want to upload or download many files we recommend using sFTP software (secure File Transfer Protocol). We use [Cyberduck](https://cyberduck.io/) internally, though there are alternatives like [WinSCP](https://winscp.net/eng/index.php). Both programs are free to use and more than capable of uploading and download many files to/from the server quickly and easily.\n\nOnce you have installed one of these programs, you can sign in to the server from the sFTP program using your server username and password and can then upload or download files from your personal computer in the same way as you would move files among folders within your personal computer.\n\n#### Cyberduck Set Up Tutorial\n\nHere we briefly demonstrate how to set up a connection between Cyberduck and NCEAS' Server. Note that you must have already installed Cyberduck to follow these steps.\n\n1. In the Cyberduck window, click the \"Open Connection\" button with an icon of a globe with a plus sign. In the below image the button has a **red** square around it.\n\n

\n\"\"\n

\n\n2. In the resulting window, input the following information:\n\n - \"Server\" -- \"aurora.nceas.ucsb.edu\"\n - \"Username\" -- whatever your username on the server is\n - \"Password\" -- your password to the server\n - \"Port\" -- change it to \"22\" (it will start as \"21\")\n\n

\n\"\"\n

\n\n3. Also, click the dropdown menu at the top that says \"FTP (File Transfer Protocol) and select \"SFTP (SSH File Transfer Protocol)\" from the set of available options.\n\n

\n\"\"\n

\n\n4. Once you've input the above information, click the \"Connect\" button and you should have access to the server! You can now click around the different folders you have access to and upload or download from there.\n\n- To download: click the files/folders that you want and they should begin downloading to your personal computer\n- To upload: drag and drop the files where you want them\n\n### Via the Command Line\n\nIf you are more comfortable with a CLI (Command Line Interface) you can also use that method of uploading/downloading. The command line includes the Terminal pane in RStudio, Terminal app for Macs, PuTTY, and gitBash among others. CLI can be a great tool to leverage filenames or types to filter specific files you would like to upload / download. Text in code chunks below are command line commands and any bracketed text `[like this]` should be replaced by some user-specific information before running.\n\nThis portion of the tutorial is focused on using the command line to interact with the server. That said, if you're interested in the command line more generally or for other purposes, please reach out to [our team](https://lter.github.io/scicomp/staff.html)!\n\n#### CLI Option A: `scp`\n\nThe `scp` command can be used to _upload_ a file or folder from your computer to the server.\n\n1A. Navigate to the folder on your computer containing the file(s) you want to upload\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n\n\n- Note that if the folder name has spaces you'll need to \"escape\" the space by using a backslash (`\\`)\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder\\ name]\n```\n:::\n\n\n\n\n2A. Now you can upload that file to the server!\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [file_name] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\n\n\nIf instead you'd like to upload all of the files in a folder, do the following:\n\n1B. Navigate to the folder containing the folder on your computer you want to upload (using `cd`)\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n\n\n2B. Use `scp` with the recursive option (`-r`) to upload all of the files in that folder\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp -r [folder] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\n\n\n- Note that this uploads all of the files in the folder *not* the folder itself so you may want to create a new folder on the server to upload your local folder's contents into.\n\nFinally, note that you can also *download* files from the server to your local machine by simply switching the order of the machines:\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [user]@aurora.nceas.ucsb.edu:/[path/to/server_folder/file_name] [local_folder] \n```\n:::\n\n\n\n\n#### CLI Option B: `sftp`\n\nThe `get` command can be used to *download* a file.\n\n1. Connect to the server\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nsftp [user]@aurora.nceas.ucsb.edu:/home/shares\n```\n:::\n\n\n\n\nYour prompt at the shell should now have switched to `sftp>` and although it is the same window you are now looking at the files on the server! Try it by typing the `ls` command at the prompts. This will list all the files and folders within the `shares` folder on Aurora.\n\n2. Enter your group's folder in the `shares` folder\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [your_group_folder]\n```\n:::\n\n\n\n\n3. If needed, continue using `cd` to get to the subfolder you want to access. Remember to \"escape\" any spaces in the folder name with backslashes!\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [subfolder]\n```\n:::\n\n\n\n\nNote that most of the bash command will work, so you can use `ls` to list files and `pwd` to check your current path.\n\n4. When you are in the folder containing the file(s) you want, download the file you want\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nget [file_name_server]\n```\n:::\n\n\n\n\n5. You can also upload a local file to the server by using the `put` sFTP command\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nput [file_name_local]\n```\n:::\n\n\n\n\n6. When you are done downloading, close the connection to the server\n\n\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nexit\n```\n:::\n", + "markdown": "---\ntitle: \"NCEAS' Server\"\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- Explain at least one way of uploading data to a server\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. Note that our server also runs other analytical tools such as JupyterHub for python users.\n\nOften the reason to engage with the server is to increase the scale of your analyses far beyond what your personal computer can handle. There are other advantages such as:\n\n- **Storage Capacity** -- More disk space & faster storage\n- **Computing Power** -- More CPUs & RAM (384GB!!)\n- **Security** -- Nightly backups and data are distributed across multiple drives\n- **Collaboration** -- Shared data & consistent software versions accessible to everyone on your team\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 Invited!\n\nIn order to access the server (and follow the instructions below) we'll need to create an account on the server for you. Please email [someone on our team](https://lter.github.io/scicomp/staff.html) or **scicomp@nceas.ucsb.edu** so that we can contact NCEAS' IT team and get an invite email sent to you.\n\nIn that email, please include the name and email addresses of all of your team members who want to access the server. After that information has been received, NCEAS' IT team will create accounts for all of those people and will send you an invitation email to set up your account on the server.\n\nAn 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://lter.github.io/workshop-github/#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\n## Uploading Data to the Server\n\n### Via RStudio\n\nIf you are uploading a single file, it may be most convenient to use RStudio's data upload capabilities. In the \"Files\" pane (default is top right but it may differ on your computer), you can click the button that is a white rectangle with a **yellow** circle with an upward facing arrow inside of it. In the below image the relevant button is in a **red** square.\n\n

\n\"\"\n

\n\nClicking that button allows you to choose (1) where you want the uploaded file to go and (2) which file you want to upload.\n\n

\n\"\"\n

\n\nYou can also download data via the RStudio interface. To download a file, check the box next to it in the \"Files\" pane.\n\n

\n\"\"\n

\n\nOnce the box is checked, click the gear icon then click the \"Export...\" option (about halfway down). In the image below this option is surrounded by a **red** square\n\n

\n\"\"\n

\n\nIn the resulting box you can choose to rename the file before downloading to your local computer. After renaming the file (or keeping its original name), click the \"Download\" button and the download should begin after a moment.\n\n

\n\"\"\n

\n\nThese methods are effective for one or a few files being up/downloaded to the same directory but can quickly become cumbersome if you want to handle many files or a few files to several different folders.\n\n### Via sFTP Software\n\nIf you want to upload or download many files we recommend using sFTP software (secure File Transfer Protocol). We use [Cyberduck](https://cyberduck.io/) internally, though there are alternatives like [WinSCP](https://winscp.net/eng/index.php). Both programs are free to use and more than capable of uploading and download many files to/from the server quickly and easily.\n\nOnce you have installed one of these programs, you can sign in to the server from the sFTP program using your server username and password and can then upload or download files from your personal computer in the same way as you would move files among folders within your personal computer.\n\n#### Cyberduck Set Up Tutorial\n\nHere we briefly demonstrate how to set up a connection between Cyberduck and NCEAS' Server. Note that you must have already installed Cyberduck to follow these steps.\n\n1. In the Cyberduck window, click the \"Open Connection\" button with an icon of a globe with a plus sign. In the below image the button has a **red** square around it.\n\n

\n\"\"\n

\n\n2. In the resulting window, input the following information:\n\n - \"Server\" -- \"aurora.nceas.ucsb.edu\"\n - \"Username\" -- whatever your username on the server is\n - \"Password\" -- your password to the server\n - \"Port\" -- change it to \"22\" (it will start as \"21\")\n\n

\n\"\"\n

\n\n3. Also, click the dropdown menu at the top that says \"FTP (File Transfer Protocol) and select \"SFTP (SSH File Transfer Protocol)\" from the set of available options.\n\n

\n\"\"\n

\n\n4. Once you've input the above information, click the \"Connect\" button and you should have access to the server! You can now click around the different folders you have access to and upload or download from there.\n\n- To download: click the files/folders that you want and they should begin downloading to your personal computer\n- To upload: drag and drop the files where you want them\n\n### Via the Command Line\n\nIf you are more comfortable with a CLI (Command Line Interface) you can also use that method of uploading/downloading. The command line includes the Terminal pane in RStudio, Terminal app for Macs, PuTTY, and gitBash among others. CLI can be a great tool to leverage filenames or types to filter specific files you would like to upload / download. Text in code chunks below are command line commands and any bracketed text `[like this]` should be replaced by some user-specific information before running.\n\nThis portion of the tutorial is focused on using the command line to interact with the server. That said, if you're interested in the command line more generally or for other purposes, please reach out to [our team](https://lter.github.io/scicomp/staff.html)!\n\n#### CLI Option A: `scp`\n\nThe `scp` command can be used to _upload_ a file or folder from your computer to the server.\n\n1A. Navigate to the folder on your computer containing the file(s) you want to upload\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n- Note that if the folder name has spaces you'll need to \"escape\" the space by using a backslash (`\\`)\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder\\ name]\n```\n:::\n\n\n2A. Now you can upload that file to the server!\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [file_name] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\nIf instead you'd like to upload all of the files in a folder, do the following:\n\n1B. Navigate to the folder containing the folder on your computer you want to upload (using `cd`)\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n2B. Use `scp` with the recursive option (`-r`) to upload all of the files in that folder\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp -r [folder] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\n- Note that this uploads all of the files in the folder *not* the folder itself so you may want to create a new folder on the server to upload your local folder's contents into.\n\nFinally, note that you can also *download* files from the server to your local machine by simply switching the order of the machines:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [user]@aurora.nceas.ucsb.edu:/[path/to/server_folder/file_name] [local_folder] \n```\n:::\n\n\n#### CLI Option B: `sftp`\n\nThe `get` command can be used to *download* a file.\n\n1. Connect to the server\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nsftp [user]@aurora.nceas.ucsb.edu:/home/shares\n```\n:::\n\n\nYour prompt at the shell should now have switched to `sftp>` and although it is the same window you are now looking at the files on the server! Try it by typing the `ls` command at the prompts. This will list all the files and folders within the `shares` folder on Aurora.\n\n2. Enter your group's folder in the `shares` folder\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [your_group_folder]\n```\n:::\n\n\n3. If needed, continue using `cd` to get to the subfolder you want to access. Remember to \"escape\" any spaces in the folder name with backslashes!\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [subfolder]\n```\n:::\n\n\nNote that most of the bash command will work, so you can use `ls` to list files and `pwd` to check your current path.\n\n4. When you are in the folder containing the file(s) you want, download the file you want\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nget [file_name_server]\n```\n:::\n\n\n5. You can also upload a local file to the server by using the `put` sFTP command\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nput [file_name_local]\n```\n:::\n\n\n6. When you are done downloading, close the connection to the server\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nexit\n```\n:::\n\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/index.qmd b/index.qmd index c91bfc0..99b70a3 100644 --- a/index.qmd +++ b/index.qmd @@ -4,11 +4,9 @@ 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://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! - Logo for GitHub -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 "SciComp Team" dropdown menu in the "People" page. +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 GitHub either by itself or with Git via RStudio**. We are always happy to improve workshop content so please don't hesitate to [post an Issue](https://github.com/lter/workshop-github/issues) on our GitHub repository if you see clear areas for improvement! ### Citing These Materials @@ -18,9 +16,7 @@ If you'd like to cite these materials, please use the following citation: ## Workshop Preparation -The below preparation includes some code chunks for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In both cases, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the "Console" tab of RStudio while {{< fa terminal >}} command line code should be run in the "Terminal" tab of RStudio. - -If you get errors with the provided code, _double check that you are running it in the right place!_ +To maximize the value of this workshop to you, **we recommend that you take the following steps before the day of the workshop**. You may have already completed some or all of these steps but please read through and confirm that you've done all of the steps that are relevant to you 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 "SciComp Team" dropdown menu in the "People" page. :::{.callout-note} #### Institution-Owned Computers @@ -28,176 +24,59 @@ The below preparation includes some code chunks for making sure everything is in If your institution has 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. ::: -### 1. Install R - -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 {{< fa brands r-project >}} R code: - -```{r r-ver-check} -#| eval: false - -# Run me in RStudio's "Console" -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. - -### 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. - -### 3. Install Git - -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. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent "[Happy Git and GitHub for the useR](https://happygitwithr.com/)" ebook. +There are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs. :::{.panel-tabset} -#### {{< fa brands apple >}} Mac - -In RStudio's "Terminal" pane, run the following {{< fa terminal >}} command line code. - -``` -# Run me in RStudio's "Terminal" -xcode-select --install -``` +### GitHub By Itself -For more detailed instructions, see [here](https://happygitwithr.com/install-git#macos). - -#### {{< fa brands windows >}} Windows - -[Install Git for Windows](https://gitforwindows.org/) (a.k.a. "Git Bash"). When asked about "Adjusting your PATH environment", **select "Git from the command line and also from 3rd-party software"**. - -For more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows). - -#### {{< fa brands linux >}} Linux - -Install Git via your distro's package manager (in the {{< fa terminal >}} Terminal). - -If you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows: - -``` -sudo apt-get install git -``` - -If instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead: - -``` -sudo yum install git -``` - -For more detailed instructions, see [here](https://happygitwithr.com/install-git#linux). - -::: +#### 1. Create a GitHub Account -### 4. Check Git's Installation Worked +{{< include prep-steps/create_github-acct.qmd >}} -Regardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this in the "Terminal" pane of RStudio. +#### 2. Celebrate! -``` -# Run me in RStudio's "Terminal" -which git -``` +{{< include prep-steps/celebrate.qmd >}} -RStudio should be able to detect Git so let's check from that side too. In RStudio click through the following menus: "Tools" {{< fa arrow-right >}} "Global Options" {{< fa arrow-right >}} "Git / SVN" (cardboard box icon in left sidebar). **If you see a file path under "Git executable" then you are good to go!** +### GitHub with RStudio :::{.callout-note} -#### Git Not Detected? +#### Running Code in Following Steps -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 before checking again. -::: - -### 5. 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. - -### 6. Connect Git and 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: - -1. Personal Access Token (PAT) -2. Secure Shell (SSH) - -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. - -Follow the steps of your chosen authentication method in the tabs below. - -:::panel-tabset -#### Personal Access Token - -**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the "Console" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived. - -```{r token-process-1} -#| eval: false - -# Install the `usethis` and `gitcreds` packages -install.packages(c("usethis", "gitcreds")) - -# Create a token (Note this will open a GitHub browser tab) -## See steps 6-10 in GitHub's PAT tutorial (link below) -usethis::create_github_token() # <1> -``` -1. Leave parentheses empty +The below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code ({{< fa brands r-project >}}) or is command line code ({{< fa terminal >}}). **In either case, you'll run all provided code in RStudio**. {{< fa brands r-project >}} R code should be run in the "Console" tab of RStudio while {{< fa terminal >}} command line code should be run in the "Terminal" tab of RStudio. -_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. - -Once you've copied your token, run the code below to save your credentials in RStudio. - -```{r token-process-2, eval = FALSE} -# Now, give your token to RStudio -## After you run this line follow the prompts in the "Console" tab of RStudio -gitcreds::gitcreds_set() # <2> -``` -2. Leave parentheses empty here as well! - -This line of code will prompt you to paste your token in the "Console" tab. After you do so, your token will be safely stored in RStudio! - -

-Screenshot of the Console prompt returned when you run 'gitcreds::gitcreds_set()' in R -

- -##### Further Information +If you get errors with the provided code, _double check that you are running it in the right place!_ +::: -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) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful. +#### 1. Create a GitHub Account -#### SSH +{{< include prep-steps/create_github-acct.qmd >}} -**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be run in the "Terminal" pane of RStudio.** +#### 2. Install R -First, we need 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). +{{< include prep-steps/install_r.qmd >}} -```{bash ssh-check, eval = F} -ls -al ~/.ssh/ -``` +#### 3. Install RStudio -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. +{{< include prep-steps/install_rstudio.qmd >}} -```{bash ssh-make, eval = F} -ssh-keygen -t ed25519 -C "lter-github" -``` +#### 4. Install Git -:::callout-tip -## Older Computer? +{{< include prep-steps/install_git.qmd >}} -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: +#### 5. Check that Git's Installation Worked -```{bash ssh-make-variant, eval = F} -ssh-keygen -t rsa -b 4096 -C "lter-github" -``` -::: +{{< include prep-steps/check_git-installation.qmd >}} -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. +#### 6. Connect Git and GitHub -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). +{{< include prep-steps/connect_git-github.qmd >}} -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. +#### 7. Celebrate! -##### Further Information +{{< include prep-steps/celebrate.qmd >}} -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. ::: -### 7. Celebrate! - -After following all the previous preparation steps, your setup should now be complete. - ## GitHub + Science Publications The 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. diff --git a/prep-steps/celebrate.qmd b/prep-steps/celebrate.qmd new file mode 100644 index 0000000..e665fa7 --- /dev/null +++ b/prep-steps/celebrate.qmd @@ -0,0 +1 @@ +After following all the previous preparation steps, your setup should now be complete. diff --git a/prep-steps/check_git-installation.qmd b/prep-steps/check_git-installation.qmd new file mode 100644 index 0000000..f857462 --- /dev/null +++ b/prep-steps/check_git-installation.qmd @@ -0,0 +1,14 @@ +Regardless of your operating system, once you've installed Git, check that worked with the following {{< fa terminal >}} command line code. All operating systems should be able to run this code. + +``` +which git +``` + +:::{.panel-tabset} +#### Confirm Connection in RStudio + +RStudio should also be able to detect Git so let's check from that side too. In RStudio click through the following menus: "Tools" {{< fa arrow-right >}} "Global Options" {{< fa arrow-right >}} "Git / SVN" (cardboard box icon in left sidebar). **If you see a file path under "Git executable" then you are good to go!** + +If Git was _not_ detected, this may be caused by having your RStudio session open while you installed Git for the first time. **In that case, please close and restart RStudio before checking again.** + +::: diff --git a/prep-steps/connect_git-github.qmd b/prep-steps/connect_git-github.qmd new file mode 100644 index 0000000..9c51920 --- /dev/null +++ b/prep-steps/connect_git-github.qmd @@ -0,0 +1,80 @@ +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: + +1. Personal Access Token (PAT) +2. Secure Shell (SSH) + +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. + +Follow the steps of your chosen authentication method in the tabs below. + +::::{.panel-tabset} +#### Personal Access Token with RStudio + +**All of the code chunks for authenticating with a token are {{< fa brands r-project >}} R code that should be run in the "Console" pane of RStudio.** You may also create a script and run the code from there if you so desire but you'll likely only need this code once so the script's value would be short-lived. + +```{r token-process-1} +#| eval: false + +# Install the `usethis` and `gitcreds` packages +install.packages(c("usethis", "gitcreds")) + +# Create a token (Note this will open a GitHub browser tab) +## See steps 6-10 in GitHub's PAT tutorial (link below) +usethis::create_github_token() # <1> +``` +1. Leave parentheses empty + +_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. + +Once you've copied your token, run the code below to save your credentials in RStudio. + +```{r token-process-2, eval = FALSE} +# Now, give your token to RStudio +## After you run this line follow the prompts in the "Console" tab of RStudio +gitcreds::gitcreds_set() # <2> +``` +2. Leave parentheses empty here as well! + +This line of code will prompt you to paste your token in the "Console" tab. After you do so (and hit "Enter"), your token will be safely stored in RStudio! + +##### 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) (this is the link referenced in the first token-authentication code chunk!) or the [Happy Git with R PAT tutorial](https://happygitwithr.com/https-pat.html) helpful. + +#### SSH + +**All of the code chunks for authenticating with SSH are {{< fa terminal >}} command line code that should be agnostic to your programming language.** + +First, we need 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 (yet) have SSH keys. + +```{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. + +:::: diff --git a/prep-steps/create_github-acct.qmd b/prep-steps/create_github-acct.qmd new file mode 100644 index 0000000..94ffc04 --- /dev/null +++ b/prep-steps/create_github-acct.qmd @@ -0,0 +1,3 @@ +Start by creating an account on [GitHub](https://github.com/). GitHub is how you'll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools. + +Dr. Jennifer Bryan has some nice guidelines for [picking a good username](https://happygitwithr.com/github-acct#username-advice) so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub. diff --git a/prep-steps/install_git.qmd b/prep-steps/install_git.qmd new file mode 100644 index 0000000..cdd65aa --- /dev/null +++ b/prep-steps/install_git.qmd @@ -0,0 +1,38 @@ +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. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan's excellent "[Happy Git and GitHub for the useR](https://happygitwithr.com/)" ebook. + +:::{.panel-tabset} +#### {{< fa brands apple >}} Mac + +Run the following {{< fa terminal >}} command line code. + +``` +xcode-select --install +``` + +For more detailed instructions, see [here](https://happygitwithr.com/install-git#macos). + +#### {{< fa brands windows >}} Windows + +[Install Git for Windows](https://gitforwindows.org/) (a.k.a. "Git Bash"). When asked about "Adjusting your PATH environment", **select "Git from the command line and also from 3rd-party software"**. + +For more detailed instructions, see [here](https://happygitwithr.com/install-git#install-git-windows). + +#### {{< fa brands linux >}} Linux + +Install Git via your distro's package manager (in the {{< fa terminal >}} Terminal). + +If you use Ubuntu or Debian Linux that {{< fa terminal >}} code is as follows: + +``` +sudo apt-get install git +``` + +If instead you use Fedora or RedHat Linux the {{< fa terminal >}} code is instead: + +``` +sudo yum install git +``` + +For more detailed instructions, see [here](https://happygitwithr.com/install-git#linux). + +::: diff --git a/prep-steps/install_r.qmd b/prep-steps/install_r.qmd new file mode 100644 index 0000000..2cd83a2 --- /dev/null +++ b/prep-steps/install_r.qmd @@ -0,0 +1,10 @@ +Now you should [install R](https://www.r-project.org/) on your computer. If you already have R, check that you have at least version 4.0.0 by running the following {{< fa brands r-project >}} R code: + +```{r r-ver-check} +#| eval: false + +# Run me in RStudio's "Console" +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. diff --git a/prep-steps/install_rstudio.qmd b/prep-steps/install_rstudio.qmd new file mode 100644 index 0000000..02461b8 --- /dev/null +++ b/prep-steps/install_rstudio.qmd @@ -0,0 +1 @@ +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.