Platform for code hosting, version control, and collaboration
Organizes a project and its state
Purpose is to store:
- folders and files for project
- README.md file for project's
- Name
- Description
- How to get started contributing
- Links to other relevant documentation, such as architecture overview
- LICENSE file
- Uses GitHub Actions
- GitHub Actions done by GitHub-hosted runners are free for public repositories, not private
- Each account includes storage and minutes for use with GitHub-hosted runners
Warning: Support for password authentication with HTTPS was removed on August 13, 2021.
- Generate ssh key (if none exists)
ssh-keygen -t ed25519 -C "[email protected]"
or for rsa / legacy systemssh-keygen -t rsa -b 4096 -C "[email protected]"
- Add passphrase (recommended)
- Start the ssh-agent
eval "$(ssh-agent -s)"
May need to use different command
- Add ssh key to ssh-agent
ssh-add ~/.ssh/id_ed25519
or whatever the name of your ssh key is - Copy ssh key
Linux:
clip < ~/.ssh/id_ed25519.pub
WSL:cat ~/.ssh/id_ed25519.pub | clip.exe
- Add ssh key to SSH and GPG keys under "Access" in profile settings
- Paste in ssh key
- Add SSH key
git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
- Connecting over HTTPS
- cache GitHub credentials in Git using a credential helper
- Connecting over SSH
- ssh keys
Versions of the repository
Main / Master Branch : used as the root of the project
Branch : a copy / snapshot of another branch at that moment in time
- Changes recommended not made on main
- A branch is behind from main if other changes were made on main that weren't added to the branch
- Common when multiple people contributing to project
- Merge conflicts arise when branches are merged together that made changes to the same parts of code
Saved changes to a branch
Shows:
- a commit message (explaining changes)
- log of changes
- author
- commit date
- id
Propose changes to a repository
i.e. Merge a branch into a branch
Creation:
- Title of pull request (Release v1.0)
- Description of the changes made
- Reference to an issue the pull request addresses
- @mentions of the person or team responsible for reviewing proposed changes
Shows:
- Conversation
- Commits that differ from base branch
- Checks
- File differences of both branches
- ONLY THE DIFFS AT THE CREATION OF THE PULL REQUEST
Tips:
- Can create pull request templates
- Link to issues and pull requests within a repository with..
#123
or #name of the pull request / issue- This will create a two-way reference
git remote rm <remote-name>
personal copy of another's repository
-
done to get a local copy separate from the commiters upstream
-
forker may
- want to go their own way unique to their vision
- need to fork in order to contribute
-
Sync fork -> upstream
- make a pull request on upstream
-
Sync upstream -> fork
- Terminal:
git fetch upstream
- Creates
upstream/main
branch
- Creates
- GitHub: Sync fork button
- Terminal:
Description:
- "What is the current behavior?"
- "What changes are you suggesting?"
Keywords: close closes closed fix fixes fixed resolve resolves resolved
- Issue in the same repository
KEYWORD #ISSUE-NUMBER
Closes #10
- Issue in a different repository
KEYWORD OWNER/REPOSITORY#ISSUE-NUMBER
Fixes octo-org/octo-repo#100
- Multiple issues
Resolves #10, closes #123, fixes octo-org/octo-repo#100
i.e. How pull-requests are used
Good for open source and independent work without coordination
- Anyone can fork
- Pull requests propose changes from fork -> upstream
- Changes approved by project maintainer
- You can allow anyone with push access to the upstream repository to make changes to your pull request
Good for small teams and organizations collaborating on private projects
- Collaborators granted push access to a single shared repository
- Branches created for topics and changes that need to be made
- Allows for code reviews and discussion about pull requests before merged into main
Shows what revision and author last modified each line of a file
File telling Git what not to track in commits
- GitHub maintains list (in github/gitignore) of recommended files to include in gitignore for
- OS
- environments
- languages
- Auto generate file
- Boilerplate
- Tag should be semantic versioned.
- Title should state what version is being released
- Notes should state what was changed.
- Just click
Generate Release Notes
- Just click
MAJOR.MINOR.PATCH
- MAJOR = incompatible API changes
- MINOR = functionality added in a backward compatible manner
- PATCH = backward compatible bug fixes
Code status | Stage | Rule | Example version |
---|---|---|---|
First release | New product | Start with 1.0.0 | 1.0.0 |
Backward compatible fix | Patch release | Increment the third digit | 1.0.1 |
Backward compatible new feature | Minor release | Increment the middle digit and reset the last digit to zero | 1.1.0 |
Breaking updates | Major release | Increment the first digit and reset the middle and last digits to zero | 2.0.0 |
- Choose the right license
https://choosealicense.com
- Good default choice is the MIT license
- Explanation of licenses https://opensource.guide/legal/#which-open-source-license-is-appropriate-for-my-project
- Figure out what license a project has https://github.com/licensee/licensee
- Create a new file
- Change name to "LICENSE"
- Click
Choose a license template
- Click the
Review and submit
green button (on right) - Click
Commit changes...
- Click
Commit changes
- Automatically generates table of contents
https://docs.github.com/en/get-started/quickstart/hello-world
- Create a repository named the same as your username, public, with a README.md file.
- Put whatever you want, some suggestions
- "About me" section describing work and interests
- Contributions you're proud of with context
- Guidance for getting help in communities where you're involved
- May need to go to repository and click the green button for "Share to profile"