forked from ecohealthalliance/eha-ma-handbook
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathversioning.Rmd
114 lines (90 loc) · 6.23 KB
/
versioning.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
# Version Control, Git and Github {#versioning}
- *Can I go back to before I made that mistake?*
- *Can others see changes others have made to the project and can I see
theirs?*
**Version control** is essential to long-term project management and
collaboration. We primarily use git for this - we recommend it for any project
with more than one file of code. It has a steep learning curve but is very
powerful.
- [GitHub](http://github.com) is a web service for sharing git-versioned
projects that has many great tools for collaboration. We have an
organizational GitHub account so we can have private repositories and work
in teams with shared projects.
- For projects with little code-based work, there are other options, as well:
- Google Docs/Word Track Changes are limited to *single documents*
- Dropbox can track all files in a shared project/folder
- Allows one to view/revert to any previous version of a file in the
folder
- Easily sharable
- Does not travel well - history is lost when project moves elsewhere
- File histories are independent - does not track interrelated
changes.
- Avoid filename-based version control:
## Learn
Git has a steep learning curve and we recommend you spend some time learning
rather than only trying to pick it up as you go along.
- Work through the online book [Happy Git with R](http://happygitwithr.com/), which will
help you get git and GitHub setup and working with R and RStudio, and teach you some
basic workflows.
- Take the Software Carpentry course [Version Control with Git](https://swcarpentry.github.io/git-novice/) (free) to reinforce some key concepts and learn how work with versions on a day-to-day basis.
## Install
- Go through the installation steps [Happy Git with
R](http://happygitwithr.com/)'s "Installation" and "Connect" chapters and
Appendix B
- Note when setting up your GitHub account that one account can have multiple
e-mail addresses associated with it, so you can split your work and personal
stuff without needing multiple accounts (see
[here](https://help.github.com/articles/managing-notification-emails-for-organizations/)).
- Give [Noam]([email protected]) (Modeling & Analytics),the `r params$data_librarian` or the `r params$infrastructure_lead` your GitHub username so they can
make you a member of the [organizational EHA
account](https://github.com/ecohealthalliance) and be given access to the
appropriate teams.
- If you are using a GitHub account you previously created with another
e-mail, be sure to add your EHA e-mail under [Email
Settings](https://github.com/settings/notifications) and set "Custom
Routing" under [your notification
settings](https://github.com/settings/notifications) so that notifications
related to the EHA organization go to your EHA e-mail.
- Install Dropbox on your computer with your EHA account (note you can have
separate personal and EHA Dropbox folders)
- Check that your EHA email gives you access to Google Drive. If you prefer
it, or your supervisor specifies it, [install it locally on your
computer](https://tools.google.com/dlpage/drive)
##. Personal Access Tokens
Github requires you to use personal access tokens (PATs) when authenticating (signing in).
These tokens provide specific levels of access to repositories and a user's github
account. The `usethis` package has a [good overview](https://usethis.r-lib.org/articles/git-credentials.html) of managing your PATs and some
helpful functions that will be highlighted below.
Good practices for managing GITHUB PATS:
1) Set an expiration date - github will notify you about expiration
2) Give them an informative name
3) Give minimal permissions - tokens should be able to do no more than necessary
4) Describe the token's purpose in the notes field
5) Save the PAT in an encrypted file storage system - password managers like [1Password](https://team-ecohealthalliance.1password.com/signin?landing-page=%2Fhome) or [Bitwarden](https://bitwarden.com/) are a good option
### Creating Tokens
There are a number of ways to create tokens, see [github docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for a comprehensive review.
You can create tokens using the function `usethis::create_github_token()`.
This function will open the token management page on github and pre-select
a sensible set of permissions.
The next easiest way to generate tokens is to navigate to the [tokens management page](https://github.com/settings/tokens) and click generate token >> classic token.
There you will be presented with a number of options for permissions. You will
probably want to select the "repo" option so that you can read and write to a
repository.
Historically, Github PATs have been stored in the .Renviron/.env file with the variable
GITHUB_PAT. The `usethis`, `gert`,and `gh` packages are moving towards a more secure method for
storing credentials. See [storing git credentials](https://usethis.r-lib.org/articles/git-credentials.html#put-your-pat-into-the-local-git-credential-store) for more information.
### Regenerating Tokens
When your token is about to expire, you will get a notification from github. That's
your cue to go to the [tokens management page](https://github.com/settings/tokens),
select the appropriate token, and then click "regenerate token". Copy and paste
that token into your secure storage location and then update your git credentials
in R.
See [PAT maintenance](https://usethis.r-lib.org/articles/git-credentials.html#ongoing-pat-maintenance)
### Useful References
- [Atlassian GIT Tutorials](https://www.atlassian.com/git/tutorials) - Nice diagrams and plan language descriptions
- [GIT CLI Cheatsheet](https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet)
- [GIT Ignore reference](https://git-scm.com/docs/gitignore)
- [Github Learning Resources](https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources)
- [Git Tower cheat sheet](https://www.git-tower.com/blog/git-cheat-sheet/)
- [Git basics overview](https://github.com/ecohealthalliance/collinschwantes-misc/blob/main/git-basic.md)