diff --git a/how-tos/2018-mkeditors_github-notes_installation+use_1.md b/how-tos/2018-mkeditors_github-notes_installation+use_1.md new file mode 100644 index 00000000..0e6e44ed --- /dev/null +++ b/how-tos/2018-mkeditors_github-notes_installation+use_1.md @@ -0,0 +1,230 @@ +> 2018-09-24 Notes by M&K team during training

+>Attendees: Terry, Pamela, Sophie, Tillmann, Tianna, and Naomi + + +# Git + +- Resource: Pro Git book, written by Scott Chacon and Ben Straub + > [https://git-scm.com/book/en/v2](https://git-scm.com/book/en/v2) + > (available online, as pdf and epub for free) + +# GitHub + +- Resource: + - [https://help.github.com/](https://help.github.com/) + + - [https://help.github.com/articles/git-and-github-learning-resources/](https://help.github.com/articles/git-and-github-learning-resources/) + +- A website that hosts repositories through a version control program + - called “Git” + +- Allows for distributed version control + +- You control when your local repository pushes to the remote server + - (=”origin”) + +# Installing GitHub + +**PART I** + +OSX: + +- Open the Terminal + +- Command: git (return) + +- Command: cd + +- Command: mkdir Github + + - Note: it is not necessary to make a directory for your Github + > work, but it does help to organize your files so that Git can + > have a specific place to look + +- Command: cd Github + +WINDOWS + +- Git command shell (separate installation process) + +**PART II** + +- Go to github.com + +- Create an account + +- Join the cu-mkp organization (accessible at [https://github.com/cu-mkp](https://github.com/cu-mkp)) + +- New cu-mkp “team” + - ([https://github.com/orgs/cu-mkp/teams](https://github.com/orgs/cu-mkp/teams)) has been created, **MK-editors** + + - Given write access to m-k-manuscript-data + > ([https://github.com/cu-mkp/m-k-manuscript-data](https://github.com/cu-mkp/m-k-manuscript-data)) + +- **\*\*\*Editorial team will be working in cu-mkp / + - m-k-manuscript-data** + +- Clone the desired repository + + - Look for the green “clone or download” button (upper right) + + - Select “clone with SSH” + + - SSH is a security protocol that enables computers to talk to each other using public key cryptography + + - Everyone has a private key and a public key + + - [https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) + + - [https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/) + + - If you are interested, some background on public key cryptography: + + - Basic description: [https://www.comodo.com/resources/small-business/digital-certificates2.php](https://www.comodo.com/resources/small-business/digital-certificates2.php) + + - Fuller description and history: [https://www.theatlantic.com/magazine/archive/2002/09/a-primer-on-public-key-encryption/302574/](https://www.theatlantic.com/magazine/archive/2002/09/a-primer-on-public-key-encryption/302574/) + + - Copy the repository address + +- Command: git clone \[repository address\] + + +# Working with the Git repository from within the Terminal + +- See: + - [https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) for a full and authoritative (but understandable) review of the process + +- “.git” directory contains files that tracks and manages everything in the repository + + - Becomes aware of files + + - Tracks the files - anytime something happens to a file, it compares the repo before and after a change, and logs the differences as a delta + + - This is a record of all changes to the repo + +- There are three states of your local repository + + - **Untracked** - create file in directory but git repo does not know about it + + - Use “add” command to make git aware of a new file (it is then “staged”) + + - Command: git add . + + - This adds your previously untracked file to the repo’s *awareness* ! + + - If you make a change to this file, you will lose the previous version, since git is not recording the file and its changes + + - **Tracked** - git is aware of a file in your local repository + + - Use the “commit” command to make git track the staged file + + - Command: git commit -m ‘\[short message, e.g., adding + - TESTFILE\]’ \[filename, e.g., TESTFILE\] + + - Saves to local repository + + - **Committed** - the current version of the file is being logged by the local repository + + - I.e., committing = taking a snapshot of the file + + - NB: you should be committing often because any of those committed “snapshots” can be returned to / recovered at any time + + - There is a version of the file saved in your local repo, and its changes will be logged in the local repo + +- “Syncing” your local repository with the remote (or origin) + + - **Pull** from the origin to your local + + - Command: git pull --rebase + + - “--rebase” will sync all recent changes in the remote repo first and then include the your local ones. This will eliminate an annoying message asking you to explain a merge. If the merge screen asking to justify appears, type: :q + + - **Push** from your local to the origin + + - Command: git push + + - If your local repo is behind the origin, you will be unable to push + + - Always pull --rebase before you push + +# Navigating and working in the command line + +- For more info on bash: [https://programminghistorian.org/en/lessons/intro-to-bash](https://programminghistorian.org/en/lessons/intro-to-bash) + + - Contains information, tutorials, and commands + +- Command: man \[command, e.g., ls\] + + - Brings up the manual for that particular command, showing its rules + +- Command: git status + + - Lets you know the relative status of your local repo v the remote/origin + +- Command: git log + + - Lets you see what’s been going on in Git recently + +- Command: df -h + + - Checks how much free space you have on your computer + +- Command: ls + + - Gives you a list of the folders/files in your current directory + +- Command: ls -la + + - Gives you a list of ALL (even hidden) files in your current directory + +- Command: cd + + - = change directory: helps you change directories + + - If you type “cd” with nothing after it, it will take you back to your home directory + + - If you type “cd” with the name of a parent or child directory relative to where you are, you will move to that directory + + - SHORTCUT: type “cd” and then the first character or two of your desired directory, then press \[tab\] and it will fill in the directory that matches the beginning of these characters + + - If this freezes, then there is more than one directory that begins the same way. Type another character or two so it is unique + +- Command: cd .. + + - = go up a level in directories + + - cd ../.. = go up 2 levels! + +- Command: less \[filename of a file in your current directory\] + + - Allows you to see the file’s contents + + - NB: for filenames with spaces, precede each space with a backslash + +- Command: q + + - = quit + + - If you are stuck in a screen, use the q command to get back to the command line + +- Command: pwd + + - = print working directory: tells you where you are (what directory you’re in) + +- Command: mkdir + + - = make directory: create new directory + +- Command: mv \[filename\] \[new filename\] + + - = move (but actually means rename the file) + +- Command: touch + + - Creates a quick file + +- DANGER: Command: rm -fr/ + + - = remove, force (don’t ask questions or check if you’re sure), recursively from this directory + + - wipes your hard drive — DO NOT DO THIS diff --git a/how-tos/fa21-github-digital-workflow-1.md b/how-tos/fa21-github-digital-workflow-1.md new file mode 100644 index 00000000..b49e1319 --- /dev/null +++ b/how-tos/fa21-github-digital-workflow-1.md @@ -0,0 +1,66 @@ +# FA21 Digital Sprints - Github & Digital Workflows + +## Main workflow: setting up to work in a branch in a github project + +1. Create issue (or find one already created) +2. Assign to someone (or yourself) +3. Open the command line +4. If you are using the Linux Subsystem for Windows, run the command: + 1. `winhome` +5. Navigate to the repository you want to work in, e.g., `m-k-manuscript-data` + 1. For example, if this is where you start: `/mnt/c/Users/naomi/`, run the commands: + 2. /mnt/c/Users/naomi/ `cd Github` + 3. /mnt/c/Users/naomi/Github/ `cd m-k-manuscript-data` +6. Pull the most updated version of the repository + 1. `git fetch` + 2. `git pull` +7. Create new branch titled "issue[##]" (no spaces or special characters) + 1. `git checkout -b [name of branch e.g. issue73]` +8. Make edits to repository files (in text editors such as Atom, oXygen, or in whatever program suits the files you are working with) +9. Add file in local repository for tracking in github repository + 1. `git add .` + 2. `git commit -m '#[issue##]: [commit message]'` (this will ensure that this commit us linked to the issue you are working on) +10. Push to the remote server (for the first time, MUST BE TRACKED) + 1. `git push -u origin [branchname]` +11. Submit a pull request in github interface (browser) to merge your issue branch with master + 1. Go to the "pull request" tab where a message should appear asking if you would like to open a pull request + 2. Another option: In branch dropdown menu, select the branch you want to merge, then hit the "new pull request" +12. THC or NJR will merge the pull request unless there are conflicts to be resolved +13. Close the issue +14. `git checkout master` (= switch back to master branch) + 1. `git checkout main` (master/main depending on the repository) + +## Other helpful commands + +- `pwd` "print working directory" -- tells you where you are in the command line +- `ls` "list" -- tells you what files and folders are in the directory you are in +- `cd` "change directory" -- this followed by the name of the directory or a path will move you to that directory +- `cd ..` -- moves you up one directory +- `less` [name of file] script reader +- `q` "quit" -- exit out of a programming that is running + +## Clone repository from github (to make a local version) + +- [https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) +- Terry says SSH (better option) if you're using your regular computer (i.e., the same public key that's on your computer and associated with your GitHub account); otherwise HTTPS + - See [https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) + - When you get to step 2., after the "touch…" command, do the following: + - dyn-209-2-208-139:Github generaleditor$ `touch ~/.ssh/config` + - dyn-209-2-208-139:Github generaleditor$ `nano ~/.ssh/config` + - _This will open the text editor_ + - _Paste in the "\* host…"_ + - _Press "ctrl" + "x", then "y", then "return"_ + - dyn-209-2-208-139:Github generaleditor$ + - `$ git clone [https://github.com/](https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)[_YOUR-USERNAME_](https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)[/](https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)[_YOUR-REPOSITORY_](https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)_`_ + + +## Check what branch you are in and make sure it is correct + +- See also [https://www.git-tower.com/learn/git/faq/checkout-remote-branch](https://www.git-tower.com/learn/git/faq/checkout-remote-branch) +- _Navigate into the desired directory (i.e. m-k-manuscript-data)_ +- `git branch` _(tells you which branch you are in)_ +- `git fetch` _(tells you what is happening in remote repo)_ +- `git status` _(tells you which branch you're on and how far ahead or behind you are from Origin)_ +- If status is behind, pull the most current version + - `git fetch` + - `git pull`