adfg-dsf / git_book

A Quarto Book describing best practices for Git use at ADF&G

Git_book

A Quarto Book describing best practices for Git use at ADF&G

A short book designed to help Division of Sport Fisheries Biometricans and Quantitative Biologist use Git and GitHub. The book was motivated by the gluttony of Git installation instructions and programmer specific Git content that is available online with seemingly sparse layman level instructions for how to use Git once it is installed. This book is intended to make sure ADF&G has a record of technical analysis carried out by staff, increase knowledge transfer between both contemporaneous and succeeding staff, and improve overall reproducible research practices within the Division.

ADF&G Division of Sport Fisheries Introduction to Git (adfg-dsf.github.io)

git_book's Issues

Draft 2 edit list

• Which branches to push to remote?
• The network drive should always be kept up to date.
• Push git_practice to ADF&G remote.
• Now that the git code chunks are broken up it might make sense to disperse the text between each chunk.

Needed additions for next commit

Plan to open the book to review from Jiaqi, Matt, and Randy. Particularly need to develop a consensus about transitioning to GitHub and how mandatory it should be. The following list represents my known edits prior to this review.

• Move statement about Sport Fish transition to a new (last) chapter that describes several possible workflows associated with the transition. I'm not sure what these are but two examples might be1) just commit everything as is, 2) Follow the book.
• Add workarounds to the RStudio appendix in the "can't do with the RStudio GUI" section.
• Add "can't view commit description" to the "can't do with the RStudio GUI" section.
• Examples of good and bad commit titles and messages.
• Specify that ADFG work should be pushed to the ADFG-DSF account.
• Decide on either I or we.
• Change "one" to "once" in the read me
• What to include in your repository

add BFG

Recently had an issue where I could not push a repository due to size and some of the violators were deep in my history. tracked it down and removed the largest files with an add on call BFG. Complicated but may be worth adding to the book as I could see this situation coming up. First you need to identify the problem...

To find out what is in your index
git ls-files --stage

To identify the largest files in a repository
git ls-files -z | xargs -0 ls -l | sort -nrk5 | head -n 10

Once you know what needs to go...
add the file to your .gitignore

Remove them from the index
git rm --cached 'path/to/file’

Now create a copy of your repository as this is dangerous. Visit https://rtyley.github.io/bfg-repo-cleaner/ download bfg-1.14.0jar and put the file in the repository folder.
java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 50M

(the 50M part can be replaced with other sizes). be careful, this is dark magic. In my case it removed more stuff than I thought it would (I wasn't sure where to see the 50M number in the prior commands outputs) and deleted something I just wanted removed from the history. This was not a problem (I had a backup for the deletion and the other stuff which was removed should have been) but it was scary.

At a later time I realized I had committed a file which was confidential and should not be posted to GitHub (publicly or even within our organization). This time I ran:
java -jar bfg-1.14.0.jar --delete-files "Copy of Sport Fish survey comments_sg.xlsx"

I think I would do that with file size issues in the future as It felt safer to specify the file I wanted removed. Another weird thing. When ran BFG with a size limit it left the record of the file in each commit with "-DELETED" appended to the name. When I specified the file name it was gone form the git history with no record of having ever been there.

Need to research the implications of doing this when it has already been shared.

Comments on Git Book; Suggestion for RStudio GUI Step-by-Step Book or Training Class

I think the Git Book is really solid and helpful as it is. There are spelling and grammatical errors throughout the book, and perhaps places that could be clearer, use less lingo, or explain the use of terms for the reader. However, I feel like it is a helpful guide for those who have had some exposure to Git in the past, really want to learn how Git works, and learn the specific Git code to do tasks. So, awesome job!!

Based on my personal journey trying to understand Git, I would point new hires with no Git experience towards a Git, GitHub, and GUI training class, teach them about Git myself, or point them towards a separate book detailing a more step-by-step version of how to set up a GitHub account, how to set up Git, how to set up R and RStudio, and then instructions about how to use Git, GitHub, and RStudio together. Personally, I really struggled to understand Git and the whole conversation about this Git Book until I used those instructions from the standards group to set up Git and then was shown in-person how to use Git and connect to GitHub through RStudio. I understand this Git Book more every day, and think it is a useful tool should I ever need to dig deeper into Git code to do tasks. So far, the functionality of RStudio and GitHub have been enough for the analyses I do. It is also a fairly gradual learning curve to learn how to use Git through RStudio for RStudio users, compared to learning the ins and outs of Git.

Thus, why I'm suggesting we create a Git, GitHub, & RStudio step-by-step book or training class.