From a6d397413041c3d8b6a81bb204f67a3ee365deb3 Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sat, 12 Aug 2023 15:52:15 +1000 Subject: [PATCH 01/14] Added chapter header content for Git. Mocked up pages for Git and GitHub chapters. --- src/SUMMARY.md | 33 +++++++++++++++++----- src/git/about.md | 3 -- src/git/branches.md | 1 + src/git/changes-staging-commits.md | 1 + src/git/commands.md | 3 ++ src/git/conflicts.md | 1 + src/git/create.md | 0 src/git/git.md | 45 ++++++++++++++++++++++++++++++ src/git/install.md | 1 + src/git/merging.md | 1 + src/git/rebasing.md | 1 + src/github/cloning.md | 1 + src/github/collaboration.md | 3 ++ src/github/create.md | 1 + src/github/{about.md => github.md} | 0 src/github/issues.md | 1 + src/github/milestones.md | 1 + src/github/pr.md | 1 + src/github/push-pull-fetch.md | 1 + src/github/releases.md | 1 + src/github/upload.md | 1 + src/github/workflow.md | 1 + 22 files changed, 92 insertions(+), 10 deletions(-) delete mode 100644 src/git/about.md create mode 100644 src/git/branches.md create mode 100644 src/git/changes-staging-commits.md create mode 100644 src/git/commands.md create mode 100644 src/git/conflicts.md create mode 100644 src/git/create.md create mode 100644 src/git/git.md create mode 100644 src/git/install.md create mode 100644 src/git/merging.md create mode 100644 src/git/rebasing.md create mode 100644 src/github/cloning.md create mode 100644 src/github/collaboration.md create mode 100644 src/github/create.md rename src/github/{about.md => github.md} (100%) create mode 100644 src/github/issues.md create mode 100644 src/github/milestones.md create mode 100644 src/github/pr.md create mode 100644 src/github/push-pull-fetch.md create mode 100644 src/github/releases.md create mode 100644 src/github/upload.md create mode 100644 src/github/workflow.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 32622aa..4cd58e5 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,9 +1,28 @@ # Summary -- [Welcome](./home.md) -- [TL;DR](./tlrd.md) -- [Git](./git/about.md) - -- [GitHub](./github/about.md) - -- [Acknowledgements](./acknowledgements.md) +- [Welcome](home.md) +- [TL;DR](tlrd.md) + +- [Git](git/git.md) + - [Common Commands](git/commands.md) + - [Install Git](git/install.md) + - [Creating a repository](git/create.md) + - [Changes, Staging and Commits](git/changes-staging-commits.md) + - [Branches, Stashes and Tags](git/branches.md) + - [Merging](git/merging.md) + - [Rebasing](git/rebasing.md) + - [Dealing with Conflicts](git/conflicts.md) + +- [GitHub](github/github.md) + - [Creating a remote repository](github/create.md) + - [Cloning](github/cloning.md) + - [Push, Pull, Fetch](github/push-pull-fetch.md) + - [Upload Existing Repository](github/upload.md) + - [Collaborating](github/collaboration.md) + - [Issues](github/issues.md) + - [Pull Requests](github/pr.md) + - [Milestones](github/milestones.md) + - [Tags and Releases](github/releases.md) + - [Workflow](github/workflow.md) + +- [Acknowledgements](acknowledgements.md) diff --git a/src/git/about.md b/src/git/about.md deleted file mode 100644 index 2581a73..0000000 --- a/src/git/about.md +++ /dev/null @@ -1,3 +0,0 @@ -# What is Version Control? - -~ diff --git a/src/git/branches.md b/src/git/branches.md new file mode 100644 index 0000000..3439bbb --- /dev/null +++ b/src/git/branches.md @@ -0,0 +1 @@ +# Branches diff --git a/src/git/changes-staging-commits.md b/src/git/changes-staging-commits.md new file mode 100644 index 0000000..8308a3b --- /dev/null +++ b/src/git/changes-staging-commits.md @@ -0,0 +1 @@ +# Changes, Staging and Commits diff --git a/src/git/commands.md b/src/git/commands.md new file mode 100644 index 0000000..34b35a9 --- /dev/null +++ b/src/git/commands.md @@ -0,0 +1,3 @@ +# Common Git Commands + +~ diff --git a/src/git/conflicts.md b/src/git/conflicts.md new file mode 100644 index 0000000..3d54f30 --- /dev/null +++ b/src/git/conflicts.md @@ -0,0 +1 @@ +# Dealing with Conflicts diff --git a/src/git/create.md b/src/git/create.md new file mode 100644 index 0000000..e69de29 diff --git a/src/git/git.md b/src/git/git.md new file mode 100644 index 0000000..80905e5 --- /dev/null +++ b/src/git/git.md @@ -0,0 +1,45 @@ +# About + +## What is Version Control? + +Version Control allows for changes within a repository to be tracked. This allows for you to retain a historical ledger of your source code. This allows you easier move between different points in your repository's history. It also allows you to develop features on separate branches so the changes do not affect the currently working codebase + +## What is Git? + +Git is a Source Control Management tool (SCM). It keeps a history of multiple files and directories in a bundle called a repository. Git tracks changes using save points called commits. Commits use .diff files to track the difference in files between commits. Repositories can have multiple branches allow many different developers to create new changes and fixes to a codebase that are separate from each other. You can also switch between branches to work on many different changes at once. These branches can then later be merged back together to a main branch, integrating the various changes. + +### Common Terms in Git + +- Repository - A project, workspace or folder containing your codebase. +- Staging - State the files that are to be added, those that have changed or those that have been deleted from repository for a commit. +- Commit - A saved snapshot of the codebase that has an associated hash. +- Branch - A separate history chain that can later be merged into other branches. +- Clone - A machine local copy of a repository, usually obtained from a remote repository hosting service (GitHub, GitLab). +- HEAD - The top (most recent) commit of a branch or repository. +- Checkout - The means to switch to a branch (HEAD) or commit. +- Pull/Push - Sync local repository with remote repository by pushing your changes your pulling the remote ones. +- Fetch - Pull metadata about for remote changes without integrating remote changes. +- Merge - Combine the history of another branch into the current branch. +- Stash - Save changes in a temporary save commit as a Work-In-Progress (WIP). +- Tags - A named commit in a repository's history. +- Rebase - A technique for reapplying commits on top of a base branch HEAD. +- Diff - The difference between a file, folder, commit or branch across commits and branches. +- Remote - A copy of a repository that lives off machine. + +### Git Workflow + +The basic workflow for getting started with are as follows: + +1. Initialise a repository [Create] +2. Add/write file contents +3. Stage changes +4. Commit changes +5. Create branches for different features, usually branched from the `main` branch (or equivalent) +6. Add/make changes +7. Stage new changes +8. Commit changes +9. Repeat 6-8 until feature is done +10. Create a 'Pull Request'. This is a request for the owner of the `main` branch to merge your branches changes into `main` ie. pull them into main. +11. Code owner merges feature branch into `main` +12. Deploy changes +13. Repeat 5-12 for projects lifetime. diff --git a/src/git/install.md b/src/git/install.md new file mode 100644 index 0000000..3edc7cf --- /dev/null +++ b/src/git/install.md @@ -0,0 +1 @@ +# Install Git diff --git a/src/git/merging.md b/src/git/merging.md new file mode 100644 index 0000000..696920d --- /dev/null +++ b/src/git/merging.md @@ -0,0 +1 @@ +# Merging diff --git a/src/git/rebasing.md b/src/git/rebasing.md new file mode 100644 index 0000000..8ab06c8 --- /dev/null +++ b/src/git/rebasing.md @@ -0,0 +1 @@ +# Rebasing diff --git a/src/github/cloning.md b/src/github/cloning.md new file mode 100644 index 0000000..183dfb1 --- /dev/null +++ b/src/github/cloning.md @@ -0,0 +1 @@ +# Cloning diff --git a/src/github/collaboration.md b/src/github/collaboration.md new file mode 100644 index 0000000..38cbb82 --- /dev/null +++ b/src/github/collaboration.md @@ -0,0 +1,3 @@ +# Collaborating + + diff --git a/src/github/create.md b/src/github/create.md new file mode 100644 index 0000000..c0df5d5 --- /dev/null +++ b/src/github/create.md @@ -0,0 +1 @@ +# Creating a remote repository diff --git a/src/github/about.md b/src/github/github.md similarity index 100% rename from src/github/about.md rename to src/github/github.md diff --git a/src/github/issues.md b/src/github/issues.md new file mode 100644 index 0000000..0ec509b --- /dev/null +++ b/src/github/issues.md @@ -0,0 +1 @@ +# Issues diff --git a/src/github/milestones.md b/src/github/milestones.md new file mode 100644 index 0000000..6fe4216 --- /dev/null +++ b/src/github/milestones.md @@ -0,0 +1 @@ +# Milestones diff --git a/src/github/pr.md b/src/github/pr.md new file mode 100644 index 0000000..5ecc75a --- /dev/null +++ b/src/github/pr.md @@ -0,0 +1 @@ +# Pull Requests diff --git a/src/github/push-pull-fetch.md b/src/github/push-pull-fetch.md new file mode 100644 index 0000000..f94f901 --- /dev/null +++ b/src/github/push-pull-fetch.md @@ -0,0 +1 @@ +# Push, Pull, Fetch diff --git a/src/github/releases.md b/src/github/releases.md new file mode 100644 index 0000000..cd7ba34 --- /dev/null +++ b/src/github/releases.md @@ -0,0 +1 @@ +# Tags and Releases diff --git a/src/github/upload.md b/src/github/upload.md new file mode 100644 index 0000000..0332c45 --- /dev/null +++ b/src/github/upload.md @@ -0,0 +1 @@ +# Upload Existing Repository diff --git a/src/github/workflow.md b/src/github/workflow.md new file mode 100644 index 0000000..dd049b1 --- /dev/null +++ b/src/github/workflow.md @@ -0,0 +1 @@ +# Workflow From 4eec0847fcfb3c0b88a50ce907e003fff26b8d18 Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sat, 12 Aug 2023 17:19:27 +1000 Subject: [PATCH 02/14] Added install, command commands and repo creating content. Updated `SUMMARY.md`. --- src/SUMMARY.md | 5 ++++- src/git/commands.md | 22 +++++++++++++++++++++- src/git/config.md | 3 +++ src/git/create.md | 9 +++++++++ src/git/git.md | 7 ++++--- src/git/install.md | 8 +++++++- src/github/licenses-oss.md | 1 + src/github/setup.md | 1 + 8 files changed, 50 insertions(+), 6 deletions(-) create mode 100644 src/git/config.md create mode 100644 src/github/licenses-oss.md create mode 100644 src/github/setup.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 4cd58e5..d89c616 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,16 +4,18 @@ - [TL;DR](tlrd.md) - [Git](git/git.md) + - [Installing Git](git/install.md) - [Common Commands](git/commands.md) - - [Install Git](git/install.md) - [Creating a repository](git/create.md) - [Changes, Staging and Commits](git/changes-staging-commits.md) - [Branches, Stashes and Tags](git/branches.md) - [Merging](git/merging.md) - [Rebasing](git/rebasing.md) - [Dealing with Conflicts](git/conflicts.md) + - [Configuring Git](git/config.md) - [GitHub](github/github.md) + - [Setup](github/setup.md) - [Creating a remote repository](github/create.md) - [Cloning](github/cloning.md) - [Push, Pull, Fetch](github/push-pull-fetch.md) @@ -23,6 +25,7 @@ - [Pull Requests](github/pr.md) - [Milestones](github/milestones.md) - [Tags and Releases](github/releases.md) + - [Licensing and OSS](github/licenses-oss.md) - [Workflow](github/workflow.md) - [Acknowledgements](acknowledgements.md) diff --git a/src/git/commands.md b/src/git/commands.md index 34b35a9..f9b51cf 100644 --- a/src/git/commands.md +++ b/src/git/commands.md @@ -1,3 +1,23 @@ # Common Git Commands -~ +Git is predominately used through its command line interface (CLI). This means Git operates using a variety of different commands (and even sub-commands, commands options for commands). Some of the most commonly used commands and their purpose: + +| Command | Description | +|:----------:|:---------------------------------------------------------------:| +| `init` | Initialise a repository | +| `clone` | Clone repository from remote host at URL | +| `checkout` | Checkout to branch or commit | +| `branch` | Create branch | +| `add` | Add files to commit stage | +| `commit` | Commit staged changes | +| `merge` | Merge changes from another branch into current branch | +| `push` | Push changes to remote repository | +| `pull` | Pull changes from remote repository | +| `fetch` | Pull changes from remote repository without integrating changes | +| `rebase` | Reapply commits on top of new branch `HEAD` | + +There are many more commands within Git's CLI. You can view them and their functionality using Git's Manpage. To access the Manpage run the following commands. + +```sh +man git +``` diff --git a/src/git/config.md b/src/git/config.md new file mode 100644 index 0000000..1bfcbc7 --- /dev/null +++ b/src/git/config.md @@ -0,0 +1,3 @@ +# Configuring Git + + diff --git a/src/git/create.md b/src/git/create.md index e69de29..a914eb1 100644 --- a/src/git/create.md +++ b/src/git/create.md @@ -0,0 +1,9 @@ +# Creating a Repository + +To create a repository you first want to create a new directory. Then you can initialise this directory as the root of your new repo. + +```sh +mkdir project +cd project +git init +``` diff --git a/src/git/git.md b/src/git/git.md index 80905e5..ed4efe9 100644 --- a/src/git/git.md +++ b/src/git/git.md @@ -10,14 +10,14 @@ Git is a Source Control Management tool (SCM). It keeps a history of multiple fi ### Common Terms in Git -- Repository - A project, workspace or folder containing your codebase. +- Repository (or repo) - A project, workspace or folder containing your codebase. - Staging - State the files that are to be added, those that have changed or those that have been deleted from repository for a commit. - Commit - A saved snapshot of the codebase that has an associated hash. - Branch - A separate history chain that can later be merged into other branches. - Clone - A machine local copy of a repository, usually obtained from a remote repository hosting service (GitHub, GitLab). - HEAD - The top (most recent) commit of a branch or repository. - Checkout - The means to switch to a branch (HEAD) or commit. -- Pull/Push - Sync local repository with remote repository by pushing your changes your pulling the remote ones. +- Pull/Push - Sync local repository with remote repository by pushing up your changes or pulling in the remote ones. - Fetch - Pull metadata about for remote changes without integrating remote changes. - Merge - Combine the history of another branch into the current branch. - Stash - Save changes in a temporary save commit as a Work-In-Progress (WIP). @@ -25,12 +25,13 @@ Git is a Source Control Management tool (SCM). It keeps a history of multiple fi - Rebase - A technique for reapplying commits on top of a base branch HEAD. - Diff - The difference between a file, folder, commit or branch across commits and branches. - Remote - A copy of a repository that lives off machine. +- Pull Request - A request to merge a branches changes into your branch (usually a feature branch into `main`). ### Git Workflow The basic workflow for getting started with are as follows: -1. Initialise a repository [Create] +1. Initialise a repository [ie. create the repository] 2. Add/write file contents 3. Stage changes 4. Commit changes diff --git a/src/git/install.md b/src/git/install.md index 3edc7cf..b5a08f7 100644 --- a/src/git/install.md +++ b/src/git/install.md @@ -1 +1,7 @@ -# Install Git +# Installing Git + +It is really simple to install, instructions and binaries can be obtained from its [official download](https://git-scm.com/download) page. Select your target platform (Windows, macOS, Linux) to see the various options for install Git. + +> Note: On Windows, you will have to got through an install Wizard. Customize the installation to whatever you see fit but you must tick the option for added Git to your system `%PATH%` or 'PATH'. + +For the purposes of the this book, we will assume you are using a Bash-based terminal. This is just the regular shell on Linux and macOS. You can use the Git Bash Shell that installs with Git on Windows. diff --git a/src/github/licenses-oss.md b/src/github/licenses-oss.md new file mode 100644 index 0000000..3c07014 --- /dev/null +++ b/src/github/licenses-oss.md @@ -0,0 +1 @@ +# Licensing and OSS diff --git a/src/github/setup.md b/src/github/setup.md new file mode 100644 index 0000000..feae8cb --- /dev/null +++ b/src/github/setup.md @@ -0,0 +1 @@ +# Setup From 1d334e1c9d9b1741578ffd09aeb2decceba1a9ef Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sat, 12 Aug 2023 19:11:43 +1000 Subject: [PATCH 03/14] Added content on changes, staging and commits. Added content on branches, stashes and tags. Updated Git and Commands pages. --- src/git/branches.md | 88 +++++++++++++++++++++++++++++- src/git/changes-staging-commits.md | 10 ++++ src/git/commands.md | 2 + src/git/git.md | 1 + 4 files changed, 100 insertions(+), 1 deletion(-) diff --git a/src/git/branches.md b/src/git/branches.md index 3439bbb..131e43b 100644 --- a/src/git/branches.md +++ b/src/git/branches.md @@ -1 +1,87 @@ -# Branches +# Branches, Stashes and Tags + +Git has various ways of storing and marking the different states and histories of a repo. The most common is a branch, which serves as a logically separate history for a repository. This allows various changes from multiple people to not conflict with each other. Stashes are temporary stores of changes that can be pushed to or popped from, kinda like a stack of changes. Tags are named markers for commits in a repo's history. + +## Branches + +To create a new branch, you simply use the `git branch` with the name of the branch as the argument. This will create a new branch `HEAD` a the commit you are currently at. You can also pass a commit hash as a second argument to create the branch at the associated commit. Renaming a branch can be achieve by using the `-m` or `-M` (forced) flags and passing the old name (optional) and new name as arguments respectively. You can also delete branches using the `-d` flag. To switch to a branch we use the `checkout` command, supplying the branch name as an argument. + +```sh +# Create a new branch +git branch new-branch + +# Switch to the new branch +git checkout new-branch + +# Rename the current branch +git branch -M new-branch-2 + +# Switch back to the main branch +git checkout main + +# Delete the previously created branch +git branch -d new-branch-2 +``` + +> Note: You can create a new branch and switch to it using the `-b` flag with the `checkout` command. +> +> ```sh +> git checkout -b new-branch +> ``` + +## Stashes + +Stashes store WIP changes that can be reapplied on to the currently checked out commit. Stashes are labelled by a number value starting at 0, indicating the most recent stash. You can pop or drop (delete) a stash from a particular index by providing it as an argument, with the default being the most recent stash. You can also list a repos stashes using the `list` sub-command. + +```sh +# Create a stash +git stash + +# Pop the most recent stash +git stash pop + +git stash + +# Stash with a message +git stash -m "Stash 1" +# Some changes +git stash -m "Stash 2" +# Some changes +git stash -m "Stash 3" + +# List stashes +git stash list +stash@{0}: On main: Stash 3 +stash@{1}: On main: Stash 2 +stash@{2}: On main: Stash 1 +stash@{3}: WIP on main: cea4a92 current HEAD commit message + +git stash pop 1 + +git stash list +stash@{0}: On main: Stash 3 +stash@{1}: On main: Stash 1 +stash@{2}: WIP on main: cea4a92 current HEAD commit message + +git stash drop 1 + +git stash list +stash@{0}: On main: Stash 3 +stash@{1}: WIP on main: cea4a92 current HEAD commit message +``` + +## Tags + +Tags allow us to name a particular commit such that it can be reference and changed to it. Tagging is mostly used to mark certain versions of a codebase. Tags can be created using the `tag` command and providing a label for the tag. Like most of Git, the `-d` flag can be used to delete a tag as well. + +```sh +# Create tag +git tag v1.0.0 + +# List tags +git tag +v1.0.0 + +# Delete tag +git tag -d v1.0.0 +``` diff --git a/src/git/changes-staging-commits.md b/src/git/changes-staging-commits.md index 8308a3b..1693f18 100644 --- a/src/git/changes-staging-commits.md +++ b/src/git/changes-staging-commits.md @@ -1 +1,11 @@ # Changes, Staging and Commits + +Whenever you make changes to the contents of a repository, this changes will be compared as a diff between the working tree and the `HEAD` of the repositories history. To view which files have changed you can run the `git status` command. Once you are happy with your changes, you can add them to the file index for staging. You can specify certain files you want to keep or using `.` to stage all new changes. Finally you can then commit your changes. Commits are saved snapshots of a repo's state. When you create a commit, a hash value is generated for it, this is used to jump back to the commit using `switch` or `checkout`. Commits also have a short message associated with it to describe the changes made in the commit. + +```sh +# Stage all changes in repo +git add . + +# Commit changes +git commit -m "Commit message" +``` diff --git a/src/git/commands.md b/src/git/commands.md index f9b51cf..dc05302 100644 --- a/src/git/commands.md +++ b/src/git/commands.md @@ -15,6 +15,8 @@ Git is predominately used through its command line interface (CLI). This means G | `pull` | Pull changes from remote repository | | `fetch` | Pull changes from remote repository without integrating changes | | `rebase` | Reapply commits on top of new branch `HEAD` | +| `status` | List the currently modified files and status of remotes | +| `tag` | Create or list a tag at the current `HEAD` | There are many more commands within Git's CLI. You can view them and their functionality using Git's Manpage. To access the Manpage run the following commands. diff --git a/src/git/git.md b/src/git/git.md index ed4efe9..2c78b4a 100644 --- a/src/git/git.md +++ b/src/git/git.md @@ -26,6 +26,7 @@ Git is a Source Control Management tool (SCM). It keeps a history of multiple fi - Diff - The difference between a file, folder, commit or branch across commits and branches. - Remote - A copy of a repository that lives off machine. - Pull Request - A request to merge a branches changes into your branch (usually a feature branch into `main`). +- Fork - A fork is a clone of a repository that shares its history and acts similar to a branch but is logically separated from the original with the forkee as the owner of the fork. ### Git Workflow From 536a44ea4cd63a2f748d2e119572c6e567e897b0 Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sun, 13 Aug 2023 20:03:51 +1000 Subject: [PATCH 04/14] Added content on merging & dealing with conflicts. Added content on configuring Git. Commented out rebase page. --- src/SUMMARY.md | 3 +-- src/git/config.md | 46 +++++++++++++++++++++++++++++++++++++++++++- src/git/conflicts.md | 1 - src/git/merging.md | 19 ++++++++++++++++++ 4 files changed, 65 insertions(+), 4 deletions(-) delete mode 100644 src/git/conflicts.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d89c616..9f03ad6 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -10,9 +10,8 @@ - [Changes, Staging and Commits](git/changes-staging-commits.md) - [Branches, Stashes and Tags](git/branches.md) - [Merging](git/merging.md) - - [Rebasing](git/rebasing.md) - - [Dealing with Conflicts](git/conflicts.md) - [Configuring Git](git/config.md) + - [GitHub](github/github.md) - [Setup](github/setup.md) diff --git a/src/git/config.md b/src/git/config.md index 1bfcbc7..73e5360 100644 --- a/src/git/config.md +++ b/src/git/config.md @@ -1,3 +1,47 @@ # Configuring Git - +The properties and behaviour of Git can be customized using special files within your repo. These can control which files Git tracks as well as give certain properties to certain files within a Git repo. + +## `.gitignore` + +The `.gitignore` file is used to specify files or file patterns you wish for Git to ignore. File patterns are specified using Unix based globbing (ie. the use of wildcard patterns). + +## `.gitattributes` + +The `.gitattributes` file is used to specify the attributes of files or file patterns. One particular useful case of the `.gitattributes` file is to ensure the correct End-of-Line (EOL) characters are used in certain files as the default choice between Unix-like systems and Windows is different which can lead to some unique bugs and inconsistencies when collaborating with people using different systems. It also allows you to control exactly which files these attributes apply to ensuring only the right files are affected. + +| Pattern | Examples | Explanation | +|:------------------------------------:|:-----------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| +| `**/logs` | `logs/debug.log` `logs/monday/foo.bar` `build/logs/debug.log` | You can prepend a pattern with a double asterisk to match directories anywhere in the repository. | +| `**/logs/debug.log` | `logs/debug.log` `build/logs/debug.log` but not `logs/build/debug.log` | You can also use a double asterisk to match files based on their name and the name of their parent directory. | +| `*.log` | `debug.log` `foo.log` `.log` `logs/debug.log` | An asterisk is a wildcard that matches zero or more characters. | +| `*.log` `!important.log` | `debug.log` `trace.log` but not `important.log` `logs/important.log` | Prepending an exclamation mark to a pattern negates it. If a file matches a pattern, but also matches a negating pattern defined later in the file, it will not be ignored. | +| `*.log` `!important/*.log` `trace.*` | `debug.log` `important/trace.log` but not `important/debug.log` | Patterns defined after a negating pattern will re-ignore any previously negated files. | +| `/debug.log` | `debug.log` but not `logs/debug.log` | Prepending a slash matches files only in the repository root. | +| `debug.log` | `debug.log` `logs/debug.log` | By default, patterns match files in any directory | +| `debug?.log` | `debug0.log` `debugg.log` but not `debug10.log` | A question mark matches exactly one character. | +| `debug[0-9].log` | `debug0.log` `debug1.log` but not `debug10.log` | Square brackets can also be used to match a single character from a specified range. | +| `debug[01].log` | `debug0.log` `debug1.log` but not `debug2.log` `debug01.log` | Square brackets match a single character form the specified set. | +| `debug[!01].log` | `debug2.log` but not `debug0.log` `debug1.log` `debug01.log` | An exclamation mark can be used to match any character except one from the specified set. | +| `debug[a-z].log` | `debuga.log` `debugb.log` but not `debug1.log` | Ranges can be numeric or alphabetic. | +| `logs` | `logs` `logs/debug.log` `logs/latest/foo.bar` `build/logs` `build/logs/debug.log` | If you don't append a slash, the pattern will match both files and the contents of directories with that name. In the example matches on the left, both directories and files named logs are ignored | +| `logs/` | `logs/debug.log` `logs/latest/foo.bar` `build/logs/foo.bar` `build/logs/latest/debug.log` | Appending a slash indicates the pattern is a directory. The entire contents of any directory in the repository matching that name – including all of its files and subdirectories – will be ignored | +| `logs/` `!logs/important.log` | `logs/debug.log` `logs/important.log` | Wait a minute! Shouldn't `logs/important.log` be negated in the example on the left Nope! Due to a performance-related quirk in Git, you can not negate a file that is ignored due to a pattern matching a directory | +| `logs/**/debug.log` | `logs/debug.log` `logs/monday/debug.log` `logs/monday/pm/debug.log` | A double asterisk matches zero or more directories. | +| `logs/*day/debug.log` | `logs/monday/debug.log` `logs/tuesday/debug.log` but not `logs/latest/debug.log` | Wildcards can be used in directory names as well. | +| logs/debug.log | `logs/debug.log` but not `debug.log` `build/logs/debug.log` | Patterns specifying a file in a particular directory are relative to the repository root. (You can prepend a slash if you like, but it doesn't do anything special.) | + +> Note: +> +> - These explanations assume your .gitignore file is in the top level directory of your repository, as is the convention. If your repository has multiple .gitignore files, simply mentally replace "repository root" with "directory containing the `.gitignore` file" (and consider unifying them, for the sanity of your team). +> - Additionally, lines starting `#` are treated as comments and a `\` character can be prepended to a character that usually has a special meaning to escape it (ie. match the literal character `[` (using `\[` in the `.gitignore`) that is in a file name instead of start a match group). + +### Example `.gitattributes` + +```.gitattributes +# Use the 'line feed' EOL character for all files +* eol=lf + +# Use the 'carriage return & line feed' EOL character for text files +*.txt eol=crlf +``` diff --git a/src/git/conflicts.md b/src/git/conflicts.md deleted file mode 100644 index 3d54f30..0000000 --- a/src/git/conflicts.md +++ /dev/null @@ -1 +0,0 @@ -# Dealing with Conflicts diff --git a/src/git/merging.md b/src/git/merging.md index 696920d..74bdeb9 100644 --- a/src/git/merging.md +++ b/src/git/merging.md @@ -1 +1,20 @@ # Merging + +Merging is the process of combining two (or more) histories together. The commits of the branch being merged into another are 'replayed' onto the 'base' branch synchronizing the histories and finally combining the result into a single commit. Merging two branches requires the branches have a common ancestor commit that can be used as the base of the combined histories. To merge branches we use the `merge` command, supplying the name of the branch we want to merge, which will be merged into the the current branch. + +```sh +# Merge branch 'feature' into this branch +git merge feature +``` + +## Dealing with Merge Conflicts + +Conflicts occur when Git cannot automatically merge two branches together. When this occurs, you will have to manually intervene and decide which changes you want to keep. When you have resolved the conflicts you then stage and commit them in a new commit as you would any other set of changes. + +### Conflict Makers + +Git uses conflict markers in your source to indicate the difference between your local changes and the changes you are integrating in. These markers are: + +- `<<<<<<<` - Indicates the start of your local difference. +- `=======` - The separator (ie. start) between the local and external difference. +- `>>>>>>>` - Indicates the end of the external difference. From 4b2f5f2b4c20f03ed6b1bad566d2cc858a78aded Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sun, 13 Aug 2023 21:31:34 +1000 Subject: [PATCH 05/14] Added content on setup Git and SSH. --- src/git/config.md | 2 +- src/github/github.md | 8 +++++ src/github/setup.md | 79 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 1 deletion(-) diff --git a/src/git/config.md b/src/git/config.md index 73e5360..415ee09 100644 --- a/src/git/config.md +++ b/src/git/config.md @@ -4,7 +4,7 @@ The properties and behaviour of Git can be customized using special files within ## `.gitignore` -The `.gitignore` file is used to specify files or file patterns you wish for Git to ignore. File patterns are specified using Unix based globbing (ie. the use of wildcard patterns). +The `.gitignore` file is used to specify files or file patterns you wish for Git to ignore. File patterns are specified using Unix based [globbing](https://linux.die.net/man/7/glob) (ie. the use of wildcard patterns). ## `.gitattributes` diff --git a/src/github/github.md b/src/github/github.md index c27f953..f4addaf 100644 --- a/src/github/github.md +++ b/src/github/github.md @@ -1 +1,9 @@ # GitHub + +GitHub is a remote Git service. This allows you to store Git repositories online so that individuals and teams can access and work on Git repositories and projects remotely. It offers many features on top of basic version control such as branch, issue and feature tracking, releases, CI/CD pipelines, project management and more. Its predominately used through its website which offers control of these features through a simple GUI. Throughout your time at Monash DeepNeuron, university and probably for the rest of your career (if in a software based role), you will use service like GitHub to help management the development of projects. + +Your first task is to sign up for a GitHub account, if you haven't already. I would highly recommend using a personal email address (not a university one) as you will most likely want access to your account after university. + +[GitHub - Join](https://github.com/join) + +It is also a good idea to install the GitHub mobile app. This allows you track and manage projects and reply to messages and issues from your phone. diff --git a/src/github/setup.md b/src/github/setup.md index feae8cb..cf6d7e4 100644 --- a/src/github/setup.md +++ b/src/github/setup.md @@ -1 +1,80 @@ # Setup + +Once you have a GitHub account setup, it is a good idea to link it with you local Git configuration for your system. Open a new shell and run the following commands, filling in your own details. + +```sh +git config --global user.name "github-username" +git config --global user.email "github-email" +``` + +## GitHub Personal Access Tokens + +To access private repos from GitHub you will need to either setup SSH ([below](#ssh--git)) or generate a personal access token to use as a password for HTTP login. Follow [this](https://github.com/settings/tokens) link and click the 'Generate new token' (select the 'classic' token option). Tick every box and name the token something like 'Full Access Token'. This will act as a universal password for accessing your GitHub recourses. Make sure to also set it to have now expiration date so it never becomes invalid. Once you generate the token make sure to copy and store it in a secure location as you will never be able to after this. + +> Note: It should be noted that this is not a best practice as losing this token or leaking will completely expose your account. This is method for convenience not safety. You should read the options and tick only whats necessary for a token to control in future. + +## SSH + Git + +Typically you can just use the HTTP protocol to clone or upload repos however this is not as secure and cloning private repos requires a Personal Access Token. Using SSH is generally far more secure and far more convenient. First we must install OpenSSH however, this is different for every platform. + +### Install OpenSSH + +#### Windows + +Open PowerShell as Administrator and run the following commands. + +```powershell +# Check if OpenSSH Client and Server packages are already installed +Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*' + +# Install the OpenSSH Client +Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0 + +# Install the OpenSSH Server +Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 +``` + +#### Linux (Ubuntu) + +```sh +sudo apt install openssh-client openssh-server +``` + +#### macOS + +```sh +# Install OpenSSH with Homebrew +brew install openssh +``` + +### SSH Keygen and Setup w/ GitHub + +Next we generate a key using the `ssh-keygen`. Running the command below will begin the process for generating an SSH key. It will then prompt you to enter a file location. Just press enter to use the default location. It will then ask you to enter a passphrase. This is optional, but recommended. + +```sh +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +> Note: It is best to you the ed255519 algorithm however, on legacy systems this may not be available so the RSA-4096 algorithm should be used instead. +> +> ```sh +> ssh-keygen -t rsa -b 4096 -C "your_email@example.com" +> ``` + +Once you have generated your key, you need to start an SSH agent and add the key. + +```sh +# Start new SSH agent +eval "$(ssh-agent -s)" + +# Point agent to key location key +ssh-add ~/.ssh/id_ed25519 +``` + +You will then need to copy the public key to your clipboard. You can print the key using the `cat` command. + +```sh +cat ~/.ssh/id_ed25519.pub +``` + +Then, go to your GitHub account, go to settings, and click on the SSH and GPG keys tab (or click [this](https://github.com/settings/keys) link). Click on New SSH key, and paste the key into the box. Give it a name, and click Add SSH key. You should now be able to clone repos using SSH. To do this, go to the repo you want to clone, but instead of copying the HTTP link, copy the SSH link, and then its regular Git cloning. From 907c7ec2ebbc0db18023429dc8f9873257b99f0e Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Tue, 15 Aug 2023 23:13:32 +1000 Subject: [PATCH 06/14] Added creating remote repo page. Fixed some meta-details about the project. --- LICENSE | 2 +- README.md | 4 ++-- src/SUMMARY.md | 4 +++- src/github/create.md | 53 +++++++++++++++++++++++++++++++++++++++++ src/github/forks.md | 1 + src/github/templates.md | 1 + src/home.md | 2 +- 7 files changed, 62 insertions(+), 5 deletions(-) create mode 100644 src/github/forks.md create mode 100644 src/github/templates.md diff --git a/LICENSE b/LICENSE index 261eeb9..b69fe84 100644 --- a/LICENSE +++ b/LICENSE @@ -186,7 +186,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright [yyyy] [name of copyright owner] + Copyright 2023 Tyler Swann and Monash DeepNeuron Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index cca1711..a43f716 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Monash DeepNeuron's Git and GitHub Training Book -[![Deploy mdBook site to Pages](https://github.com/MonashDeepNeuron/Git-Gut/actions/workflows/mdbook.yml/badge.svg)](https://github.com/MonashDeepNeuron/Git-Gut/actions/workflows/mdbook.yml) +[![Deploy mdBook site to Pages](https://github.com/MonashDeepNeuron/Git-Gud/actions/workflows/mdbook.yml/badge.svg)](https://github.com/MonashDeepNeuron/Git-Gut/actions/workflows/mdbook.yml) This repository contains the source code for the HPC Training content and challenges for new HPC recruits. This book is available online or can be built locally. @@ -17,7 +17,7 @@ cargo install mdbook You can build this book you must clone this repository using Git. You can then build it and even serve it to localhost to view in your browser. The serve command will produce a localhost you can view. ```sh -$ git clone https://github.com/MonashDeepNeuron/HPC-Training.git +$ git clone https://github.com/MonashDeepNeuron/Git-Gud.git $ cd Git-Gud # Build ... diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9f03ad6..40dc018 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -11,13 +11,14 @@ - [Branches, Stashes and Tags](git/branches.md) - [Merging](git/merging.md) - [Configuring Git](git/config.md) - + - [GitHub](github/github.md) - [Setup](github/setup.md) - [Creating a remote repository](github/create.md) - [Cloning](github/cloning.md) - [Push, Pull, Fetch](github/push-pull-fetch.md) + - [Forks](github/forks.md) - [Upload Existing Repository](github/upload.md) - [Collaborating](github/collaboration.md) - [Issues](github/issues.md) @@ -26,5 +27,6 @@ - [Tags and Releases](github/releases.md) - [Licensing and OSS](github/licenses-oss.md) - [Workflow](github/workflow.md) + - [Template Repositories](github/templates.md) - [Acknowledgements](acknowledgements.md) diff --git a/src/github/create.md b/src/github/create.md index c0df5d5..c47c165 100644 --- a/src/github/create.md +++ b/src/github/create.md @@ -1 +1,54 @@ # Creating a remote repository + +Creating a repository on GitHub is super simple. Simply go to [github.com](https://github.com) and click the green 'New' button on the left panel. This will instruct you on how to create a repository. You will have to give your repo a name, possibly a description and attach a software license and `README.md`. Additionally you can have it generate a `.gitignore` for the programming language the source code of the repo will written in to prevent commonly ignore files (eg. executables and binaries) to be committed. This will then generate a very boilerplate repo which you can then clone using the `clone` command via SSH or HTTP. + +```sh +# Clone with SSH +git clone git@github.com:/.git + +# Clone with HTTP +git clone https://github.com//.git +``` + +## Uploading a Repository + +Alternatively you can create a repository locally and upload it to GitHub at a later date. + +### Upload Empty Repository + +If you want to upload a new empty repo you can do so by first creating the empty repo on GitHub followed by these commands to upload it to the new empty remote, replacing the content between the angle brackets (`<>`). + +```sh +mkdir my-awesome-project +cd my-awesome-project +echo "# test" >> README.md +git init +git add README.md +git commit -m "first commit" +git branch -M main + +# SSH +git remote add origin git@github.com:/.git +# HTTP +git remote add origin https://github.com//.git + +git push -u origin main +``` + +### Upload Existing Repository + +You can also upload an existing and well established project to GitHub by simply adding the new GitHub repo as a new remote location. + +```sh +cd my-awesome-project + +# SSH +git remote add origin git@github.com:/.git +# HTTP +git remote add origin https://github.com//.git + +git branch -M main +git push -u origin main +``` + +> Note: A repository can have many remotes. The term `origin` isn't a special command or 'keyword' in Git but rather just the conventional name for the default remote host location for repository. You can replace `origin` with whatever name you like. diff --git a/src/github/forks.md b/src/github/forks.md new file mode 100644 index 0000000..3e5297d --- /dev/null +++ b/src/github/forks.md @@ -0,0 +1 @@ +# Forks diff --git a/src/github/templates.md b/src/github/templates.md new file mode 100644 index 0000000..1f37f96 --- /dev/null +++ b/src/github/templates.md @@ -0,0 +1 @@ +# Template Repositories diff --git a/src/home.md b/src/home.md index c3e91ea..41e82af 100644 --- a/src/home.md +++ b/src/home.md @@ -14,6 +14,6 @@ You can contribute to the book by accessing its GitHub repository (GitHub log in
- Current Release + Current Release
From 8882b89b01eea91c4261886cd7d4e92b99933b3a Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Thu, 17 Aug 2023 23:56:30 +1000 Subject: [PATCH 07/14] Added content on Push, Pull and Fetching changes. Added content on forks. Added content on OSS licenses. Updated definitions in general Git page. Updated `SUMMARY.md`. --- src/SUMMARY.md | 4 +-- src/git/git.md | 2 ++ src/github/cloning.md | 1 - .../{create.md => create-cloning-upload.md} | 4 +-- src/github/forks.md | 6 +++++ src/github/licenses-oss.md | 15 +++++++++++ src/github/push-pull-fetch.md | 27 +++++++++++++++++++ 7 files changed, 53 insertions(+), 6 deletions(-) delete mode 100644 src/github/cloning.md rename src/github/{create.md => create-cloning-upload.md} (69%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 40dc018..3602499 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -15,11 +15,9 @@ - [GitHub](github/github.md) - [Setup](github/setup.md) - - [Creating a remote repository](github/create.md) - - [Cloning](github/cloning.md) + - [Creating, Cloning and Uploading Remote Repositories](github/create-cloning-upload.md) - [Push, Pull, Fetch](github/push-pull-fetch.md) - [Forks](github/forks.md) - - [Upload Existing Repository](github/upload.md) - [Collaborating](github/collaboration.md) - [Issues](github/issues.md) - [Pull Requests](github/pr.md) diff --git a/src/git/git.md b/src/git/git.md index 2c78b4a..abae618 100644 --- a/src/git/git.md +++ b/src/git/git.md @@ -27,6 +27,8 @@ Git is a Source Control Management tool (SCM). It keeps a history of multiple fi - Remote - A copy of a repository that lives off machine. - Pull Request - A request to merge a branches changes into your branch (usually a feature branch into `main`). - Fork - A fork is a clone of a repository that shares its history and acts similar to a branch but is logically separated from the original with the forkee as the owner of the fork. +- Upstream - The source location of a repository. +- OSS - Acronym for Open Source Software. ### Git Workflow diff --git a/src/github/cloning.md b/src/github/cloning.md deleted file mode 100644 index 183dfb1..0000000 --- a/src/github/cloning.md +++ /dev/null @@ -1 +0,0 @@ -# Cloning diff --git a/src/github/create.md b/src/github/create-cloning-upload.md similarity index 69% rename from src/github/create.md rename to src/github/create-cloning-upload.md index c47c165..fb19b72 100644 --- a/src/github/create.md +++ b/src/github/create-cloning-upload.md @@ -1,6 +1,6 @@ -# Creating a remote repository +# Creating and Cloning a Remote Repository -Creating a repository on GitHub is super simple. Simply go to [github.com](https://github.com) and click the green 'New' button on the left panel. This will instruct you on how to create a repository. You will have to give your repo a name, possibly a description and attach a software license and `README.md`. Additionally you can have it generate a `.gitignore` for the programming language the source code of the repo will written in to prevent commonly ignore files (eg. executables and binaries) to be committed. This will then generate a very boilerplate repo which you can then clone using the `clone` command via SSH or HTTP. +Creating and cloning a repository on GitHub is super simple. Simply go to [github.com](https://github.com) and click the green 'New' button on the left panel. This will instruct you on how to create a repository. You will have to give your repo a name, possibly a description and attach a software license and `README.md`. Additionally you can have it generate a `.gitignore` for the programming language the source code of the repo will written in to prevent commonly ignore files (eg. executables and binaries) to be committed. This will then generate a very boilerplate repo which you can then clone using the `clone` command via SSH or HTTP. ```sh # Clone with SSH diff --git a/src/github/forks.md b/src/github/forks.md index 3e5297d..3f1a92b 100644 --- a/src/github/forks.md +++ b/src/github/forks.md @@ -1 +1,7 @@ # Forks + +Forks are a combination of branches and clones of a repo. They allow you to copy a remote repo to another (usually remote) location that is independent of the 'upstream' but still retains a connection to its upstream source. Forks can exist for many reasons. A common one is you wish to extend the functionality of a codebase for your own or your organisations/companies uses. You may also want to make and test an improvement or extension of the codebase and request the changes be integrated into the upstream source for other users to benefit from the change. + +To fork a repository you can simply clone a repository and rename the remote name from `origin` to `upstream` and setup the repo to track a different remote location as `origin`. This allows you to sync with the `upstream` remote but collaborate at `origin`. Alternatively you can use GitHub and select the fork button on a repos '<> Code' page and have GitHub setup the remote fork for you which can then allow you to simply clone the fork to your local machine to start developing on the fork. + +When forking a repository you have to be weary of the software license the original source operates on as this restricts what you are able to do with the forked software and how you are allowed to publish and distribute it. diff --git a/src/github/licenses-oss.md b/src/github/licenses-oss.md index 3c07014..443f36b 100644 --- a/src/github/licenses-oss.md +++ b/src/github/licenses-oss.md @@ -1 +1,16 @@ # Licensing and OSS + +When developing any software, the code and resulting binaries that you distribute will have to have some software license governing how the software can be used and redistributed. This is especially important for OSS as your source code, not just built binaries are available for all to see and use and being able to control how it is used and limit the amount of liability you hold as the creator from other peoples/companies/organisations use can become very important. + +There are many existing OSS licenses, each with their own benefits, downfalls and use cases. Each allow for the software licensed under them to be used for different things and can also control how derivative work can be distributed and used. Here are a few of the most common OSS license with links to copies of them. + +- [AGPL-3.0](licenses/AGPL-3.0) - GNU Affero General Public License, a free copy left license similar to GPL-3.0 but has an addition term to allow users who interact with the licensed software over a network to receive the source for that program. +- [Apache-2.0](licenses/Apache-2.0) - A copyright license allow anyone modify the original source as long as the source retains its original Apache-2.0 license and as the modifications are listed in the distribution of the modified source. Authors of Apache-2.0 licensed source cannot be help liable under this license. +- [BSD-3-Clause](licenses/BSD-3-Clause) - Simple copyright license allow anyone to do whatever they want with BSD 3-Clause license software as long as the software retains it original BSD 3-Clause license. It also states that contributors of the original source cannot be used to endorse derivative works without explicit prior permission. +- [BSL-1.0](licenses/BSL-1.0) - Simple copyright license allow anyone to do whatever they want with BSL-1.0 license software as long as the software retains it original BSL-1.0 license unless distributed as a compiled binary. +- [GPL-2.0](licenses/GPL-2.0) - GNU General Public License Version 2, a free copy left license. +- [GPL-3.0](licenses/GPL-3.0) - GNU General Public License Version 3, a free copy left license similar to GPL-2.0 but with stricter copyleft requirements. +- [LGPL-3.0](licenses/LGPL-3.0) - GNU Lesser General Public License Version 3, a free copy left license similar to GPL-3.0 but LGPL-3.0 software is able to be used and modified with non-GPL-3.0 license source as longe as th originally LGPL-3.0 licensed source retains its original license and the LGPL-3.0 source cna be replaced with other source with no effect on the end users usage of the compiled program. +- [MIT](licenses/MIT) - Simple copyright license allow anyone to do whatever they want with MIT license software as long as the software retains it original MIT license. Authors of MIT licensed source cannot be help liable under this license. +- [MPL-2.0](licenses/MPL-2.0) - Mozilla Public License Version 2.0, is a middle ground license that aims to balance the benefits of permissive licenses like MIT and copyleft licenses like GPL-3.0. +- [Unlicense](licenses/Unlicense) - A license that releases the software into the public domain. diff --git a/src/github/push-pull-fetch.md b/src/github/push-pull-fetch.md index f94f901..2abaa11 100644 --- a/src/github/push-pull-fetch.md +++ b/src/github/push-pull-fetch.md @@ -1 +1,28 @@ # Push, Pull, Fetch + +When interacting with remote repos, there are three key operations you will perform frequently. These are pushing your local changes to a remote, pulling and integrating new changes from a remote and fetching the metadata of available changes. All these changes + +## Push + +Pushing is the process of uploading our local changes to a remote location. You can also use the `-u` flag to setup a new remote reference if the local branch does not exist on the remote yet. + +```sh +git push +git push -u +``` + +## Pull + +Pulling is the process of integrating remote changes into the current branch. Under the hood, `git pull` calls `git fetch`, forwarding all command line arguments from `git pull` to `git fetch`. If the current local branch is simply behind the remote's history the local branch will be fast-forwarded by default. If the branch's histories diverge then either `git rebase` or `git merge` will be run depending on the configuration of Git. This allows you to remain up to date with the remote as you develop locally if multiple other people are working on the same branch. + +```sh +git pull +``` + +## Fetch + +Fetching is a very powerful tool. It allows us to pull the updated refs from a remote location with integrating the changes meaning we can view what has changed before our local history is fast-forwarded or merged with the corresponding remote branch. + +```sh +git fetch +``` From 6471b6d24cb8db27cd31cc27f7e466781b531359 Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Sat, 19 Aug 2023 17:18:15 +1000 Subject: [PATCH 08/14] Added content on collaborating. Added content on Issues. Added content on PRs. Added content on Milestones. Updated `SUMMARY.md`. --- src/SUMMARY.md | 16 ++++++---- src/github/collaboration.md | 45 +++++++++++++++++++++++++++- src/github/discussions.md | 1 + src/github/issues.md | 58 +++++++++++++++++++++++++++++++++++++ src/github/milestones.md | 2 ++ src/github/orgs.md | 1 + src/github/pages.md | 1 + src/github/pr.md | 48 ++++++++++++++++++++++++++++++ src/github/wikis.md | 1 + 9 files changed, 166 insertions(+), 7 deletions(-) create mode 100644 src/github/discussions.md create mode 100644 src/github/orgs.md create mode 100644 src/github/pages.md create mode 100644 src/github/wikis.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3602499..ae2bdcf 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -19,12 +19,16 @@ - [Push, Pull, Fetch](github/push-pull-fetch.md) - [Forks](github/forks.md) - [Collaborating](github/collaboration.md) - - [Issues](github/issues.md) - - [Pull Requests](github/pr.md) - - [Milestones](github/milestones.md) - - [Tags and Releases](github/releases.md) - - [Licensing and OSS](github/licenses-oss.md) - - [Workflow](github/workflow.md) + - [Issues](github/issues.md) + - [Pull Requests](github/pr.md) + - [Milestones](github/milestones.md) + - [Tags and Releases](github/releases.md) + - [Wikis](github/wikis.md) + - [Discussions](github/discussions.md) + - [Licensing and OSS](github/licenses-oss.md) + - [A Sample Workflow](github/workflow.md) - [Template Repositories](github/templates.md) + - [GitHub Pages](github/pages.md) + - [GitHub Organisations](github/orgs.md) - [Acknowledgements](acknowledgements.md) diff --git a/src/github/collaboration.md b/src/github/collaboration.md index 38cbb82..be12016 100644 --- a/src/github/collaboration.md +++ b/src/github/collaboration.md @@ -1,3 +1,46 @@ # Collaborating - +While GitHub can simply be used as a remote host for repos, allowing you to push and pull to and from a central location, the platform has many more features for allowing teams of people to collaborate on many different kinds of codebases and coordinate development with people from across the world. + +## GitHub flavoured Markdown + +A large proportion of text written on GitHub is written in Markdown (like this books source). Markdown is a markup language which can be used to describe the format and structure of written text, similar to HTML or LaTeX. There are many variations of Markdown which add various functionality to the language. GitHub uses its own version which extends the capabilities expressed in the CommonMark (standard) Markdown specification. + +- [CommonMark](https://commonmark.org/) +- [Markdown Basic Syntax Guide](https://www.markdownguide.org/basic-syntax/) +- [Markdown Extended Syntax Guide](https://www.markdownguide.org/extended-syntax/) +- [GitHub Flavoured Markdown (GFM) Specification](https://github.github.com/gfm/) + +GitHub's extensions to Markdown include some common extensions found across many Markdown parsers including support for Strikethrough text, tables and task list items (checklist). These allow you to express more complex structures with Markdown however are not that interesting and specific to GitHub. You can see the syntax for most of Markdown in the second and third links above including these common extensions. + +More interesting are the collaboration based extensions to Markdown that are specific to GitHub. Within any Markdown text on GitHub you are able to link and refer to issues, discussions, Pull Requests (PR), commits, people and even organisation teams from any repo/org. This is done by using the characters `#` and `@` as prefixes. + +### Prefix - `#` + +You may notice that issues, PRs and discussions have an associated #-number. This is used to reference the item within other items of the same or other repos. The `#` prefix can be used to create a link to the item in the Markdown of the current item. The Markdown editors on GitHub will even render a scrollable UI component you can use to search by name for the item you want to link when you type start typing `#`. You can even reference items from different repos (as long as they are public) by prefixing the `#` with the name of the owner (GitHub username) and the repos name eg. `MonashDeepNeuron\HPC-Training#1`. You can also create a pretty link if you put the link somewhere in a list item. + +### Prefix - `@` + +Like many social media platforms, the `@` prefix is used to mention users and teams with a users handle being their username. Like `#`, typing `@` will bring up a list of users and teams you can mention, autocompleting the text if you select an option manually. Teams from organisation are prefixed with the orgs name (like cross repo item links) followed by the team name. eg. The Monash DeepNeuron GitHub organisation has a GitHub team called 'HPC Training' which can be mentioned like so `@MonashDeepNeuron/hpc-training`. Mentioning a GitHub team notify the whole team. You can also use the `@` prefix to link specific commits however, no matter which repo it is from you must prefix the whole thing with the repo owner and name eg. `MonashDeepNeuron/HPC-Training@767c7f0`. + +> Note: Team names can have spaces but in links the spaces are replaced with dashes/hyphens (`-`). + +## Collaboration Guidelines and Documents + +Within a repo there are often many common documents that are used to describe the collaboration process and guidelines for an OSS. These documents are used to outline the behaviour expected by contributors, how to make contributions, often the codes styling guidelines etc.. Here are some common documents you may find in a repo and the overarching purpose they serve to contributors and users. + +> Note: +> +> - Really any kind of file can be used to store this as long as the text is accessible by users and contributors so often plain text files (`*.txt`) or Markdown files (`*.md`) are used. Markdown is often favoured as it has better facilities to describes the structure of the document and can then be rendered on GitHub or externally. +> - It is a convention that this contributor documentation files be capitialised however, it is not required. +> - None of these documents are strictly necessary for a repo to function however, they can make it easier for peopel to start contributing to one. + +- README - This is the front page of your codebase. Often containing a summary of the project, a 'quickstart' tutorial and may some examples (all optional). +- CONTRIBUTING - Describes the steps potential contributors should take to make contributions to the project. +- CODE_OF_CONDUCT - The expected behaviour of contributors when interacting with each other and users. +- GUIDELINES - Similar and like a combination of the CODE_OF_CONDUCT and the CONTRIBUTING documents. +- LICENSE - Details the license the code operate under and +- INSTALL - Instructions on how to install, setup and use a project either for development or end-user usage. +- CITATION - If your work is academic in nature you can use this file to hold the appropriate citation so users of the project or people that took inspiration of the project can properly cite your work (often uses the `*.cff` extension). +- ACKNOWLEDGMENTS / AUTHORS - A file listing the contributors, authors, co-authors, owners and/or co-owners of a repository. Can also be used to pay tribute to people who've helped with the project, particularly if the contributions were indirect or undocumented (advice etc.). +- CHANGELOG - Used to describe the changes between one version to another. Many of these files could be littered throughout your project if it has many independent parts or has had a long lifetime. diff --git a/src/github/discussions.md b/src/github/discussions.md new file mode 100644 index 0000000..ed5ecf9 --- /dev/null +++ b/src/github/discussions.md @@ -0,0 +1 @@ +# Discussions diff --git a/src/github/issues.md b/src/github/issues.md index 0ec509b..1604163 100644 --- a/src/github/issues.md +++ b/src/github/issues.md @@ -1 +1,59 @@ # Issues + +Issues are a fundamental tool for users and collaborators to express faults in a codebase and track the progression to fixing those faults. Issues are like tickets on many general purpose project management tools. A new Issue can be raised by anyone on GitHub (provided the repo is public) to indicate a problem with the current codebase. This can be security bugs, incorrect documentation and source code alignment, unexpected behaviour or even new features users want to request from the project. Issues on GitHub have many additional features for contributors to be able to easily link development with Issue tracking. Additional features and controls for Issues can be found on the UI panel component to the right (except the discussion thread). + +## Discussion Thread + +Following the original creation of an Issue and its description, collaborators can reply to Issue using the discussion thread. This is a history of all actions and comments made on an Issue and can be used to focus discussions about the Issue at the Issues location. You can also add reactions to an Issues or comment. + +## Closing an Issue + +In the dialog box that is used to craft a comment, there is an option to close the Issues which marks the Issue as resolved or alternatively, you can close an Issue as "Won't Fix" meaning the Issue will not be resolved or considered. You can also reopen the Issue if it persists or becomes an Issue again. + +## Todos + +Using a Markdown checklist in the description of an Issue will at a todo meter and item count to the top of the Issues page as well as to the Issues row on the 'Issues' tab. List can be treated like a regular todo/checklist list for anything that needs to be down to complete the Issue where you can tick/untick items as you go and it will be reflected in the UI. + +## Assignees + +Assignees allow you to add a person you want to work on a particular Issue. You can assign individual users or teams if within an organisation. + +## Labels + +Labels are descriptor tags that can make it easier to categories Issues which can make it easier to find or group common Issues together. + +## Projects + +This section allows you to add your Issue to a project board and have it tracked by GitHub automatically allowing better integration between a repos Issues and the general management of the team or organisation. + +## Milestones + +You can make an Issue a part of a milestones progress. + +## Development + +This section allows you to easily create and track branches linked to the progression of the Issue. + +## Notifications + +Change your notification settings for the Issue + +## Participants + +View who is/has been involved in an Issue. + +## Lock conversations + +Lock the conversation from further modifications (usually for archival purposes) + +## Pin Issues + +Pin the Issue on the repos main 'Issues' tab putting it at the forefront of all collaborators view. + +## Convert to Discussion + +Convert the Issue, its discussion thread and tags to a dedicated discussion. + +## Deleting an Issue + +Delete the Issue from existence. diff --git a/src/github/milestones.md b/src/github/milestones.md index 6fe4216..1487a3d 100644 --- a/src/github/milestones.md +++ b/src/github/milestones.md @@ -1 +1,3 @@ # Milestones + +Milestones are a easy progression trackers that can be used to, well mark important Milestones for a project and link this progress to the resolution of issues or merging of PRs. Milestones also have an end date associated with them to help keep you on track. To create a Milestone, go to either the 'Issues' or 'Pull requests' tab of the repo and to the top right of the list views you will see a button called 'Milestones'. From this page you can create a Milestone. Issues and PRs are added to the Milestone from the page of the particular time you want to add. Milestones are good for tracking large goals that span many issues and PRs. You must go back to the Milestones page and close it manually to meat the Milestones deadline. diff --git a/src/github/orgs.md b/src/github/orgs.md new file mode 100644 index 0000000..6a62ac2 --- /dev/null +++ b/src/github/orgs.md @@ -0,0 +1 @@ +# GitHub Organisations diff --git a/src/github/pages.md b/src/github/pages.md new file mode 100644 index 0000000..a86f4d7 --- /dev/null +++ b/src/github/pages.md @@ -0,0 +1 @@ +# GitHub Pages diff --git a/src/github/pr.md b/src/github/pr.md index 5ecc75a..c9b3d01 100644 --- a/src/github/pr.md +++ b/src/github/pr.md @@ -1 +1,49 @@ # Pull Requests + +Pull Requests (PRs) are request from collaborators to pull in their new changes from a feature branch into one of the main development, testing or deployment branches. This allows the maintainers of a project to more carefully view the changes made and consider how they want the changes to be integrated. Maintainers and reviewers can also request the contributor to make changes to their contribution to make it fit better with the existing codebase. PRs are essential to quality assurance (QA) and that breaking changes are not introduced to a codebase unless explicitly allowed. A PR is really just a call to `git merge` with extra steps and oversight of the merge although a squash merge or rebase can be chosen instead. PRs can also be created as drafts, allowing you to continue to commit changes to the incoming branch without the risk of maintainers or other contributors completing the PR before it is ready. + +> Note: A squash merge will combine the history of all commits on the incoming branch into a single commit that is then added to the base branch. + +## Discussion Thread + +Just like issues, PRs also have a discussion thread that allow conversations about the PR to be in the same place as the PR. + +## Closing a PR + +Again, like issues you can close a PR meaning it cannot be merged without reopening the PR. + +## Reviewers + +This section allows for you to assign people you wish to review the changes. Many PRs are required to have at least one approved review for a PR to go through. Reviews look at the diff of the changes and can add comments as specific to a line or to an entire file or for the whole PR. Reviews can request that changes be made, blocking the PR until it has been resolved. + +## Assignees + +Assignees allow you to add a person you want to work on merging a particular PR. + +## Labels + +Labels are descriptor tags that can make it easier to categories PRs which can make it easier to find or group common PRs together. + +## Projects + +This section allows you to add your PR to a project board and have it tracked by GitHub automatically allowing better integration between a repos PRs and the general management of the team or organisation. + +## Milestones + +You can make an PR a part of a milestones progress. + +## Development + +This section shows the issues that are linked to the PR. Issues can be linked by creating the branch from the issue or by using ['Closing Keywords'](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) in the description of the PR. + +## Notifications + +Change your notification settings for the PR. + +## Participants + +View who is/has been involved in an PR. + +## Lock conversations + +Lock the conversation from further modifications (usually for archival purposes). diff --git a/src/github/wikis.md b/src/github/wikis.md new file mode 100644 index 0000000..2247f09 --- /dev/null +++ b/src/github/wikis.md @@ -0,0 +1 @@ +# Wikis From faf17354a46756bdc9dfbe6ac82f4909f972db5a Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Mon, 21 Aug 2023 12:50:15 +1000 Subject: [PATCH 09/14] Added content on Workflow. Added 'In Construction' notice for unfinished pages. issues => Issues when referencing GitHub Issues. Updated `SUMMARY.md`. --- src/SUMMARY.md | 6 +++--- src/git/rebasing.md | 4 ++++ src/github/collaboration.md | 4 ++-- src/github/discussions.md | 6 ++++++ src/github/github.md | 2 +- src/github/milestones.md | 2 +- src/github/pages.md | 4 ++++ src/github/pr.md | 6 +++--- src/github/releases.md | 2 ++ src/github/templates.md | 2 ++ src/github/wikis.md | 4 ++++ src/github/workflow.md | 26 ++++++++++++++++++++++++++ src/tlrd.md | 6 +++++- 13 files changed, 63 insertions(+), 11 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ae2bdcf..c8d3a9d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -10,14 +10,15 @@ - [Changes, Staging and Commits](git/changes-staging-commits.md) - [Branches, Stashes and Tags](git/branches.md) - [Merging](git/merging.md) + - [Rebasing](git/rebasing.md) - [Configuring Git](git/config.md) - - [GitHub](github/github.md) - [Setup](github/setup.md) - [Creating, Cloning and Uploading Remote Repositories](github/create-cloning-upload.md) - [Push, Pull, Fetch](github/push-pull-fetch.md) - [Forks](github/forks.md) + - [Template Repositories](github/templates.md) - [Collaborating](github/collaboration.md) - [Issues](github/issues.md) - [Pull Requests](github/pr.md) @@ -27,8 +28,7 @@ - [Discussions](github/discussions.md) - [Licensing and OSS](github/licenses-oss.md) - [A Sample Workflow](github/workflow.md) - - [Template Repositories](github/templates.md) - [GitHub Pages](github/pages.md) - - [GitHub Organisations](github/orgs.md) + - [Acknowledgements](acknowledgements.md) diff --git a/src/git/rebasing.md b/src/git/rebasing.md index 8ab06c8..8c0f5a1 100644 --- a/src/git/rebasing.md +++ b/src/git/rebasing.md @@ -1 +1,5 @@ # Rebasing + +🚧 Under Construction 🚧 + +⚠️ Coming soon! 🏗️ diff --git a/src/github/collaboration.md b/src/github/collaboration.md index be12016..f3f2b94 100644 --- a/src/github/collaboration.md +++ b/src/github/collaboration.md @@ -13,11 +13,11 @@ A large proportion of text written on GitHub is written in Markdown (like this b GitHub's extensions to Markdown include some common extensions found across many Markdown parsers including support for Strikethrough text, tables and task list items (checklist). These allow you to express more complex structures with Markdown however are not that interesting and specific to GitHub. You can see the syntax for most of Markdown in the second and third links above including these common extensions. -More interesting are the collaboration based extensions to Markdown that are specific to GitHub. Within any Markdown text on GitHub you are able to link and refer to issues, discussions, Pull Requests (PR), commits, people and even organisation teams from any repo/org. This is done by using the characters `#` and `@` as prefixes. +More interesting are the collaboration based extensions to Markdown that are specific to GitHub. Within any Markdown text on GitHub you are able to link and refer to Issues, discussions, Pull Requests (PR), commits, people and even organisation teams from any repo/org. This is done by using the characters `#` and `@` as prefixes. ### Prefix - `#` -You may notice that issues, PRs and discussions have an associated #-number. This is used to reference the item within other items of the same or other repos. The `#` prefix can be used to create a link to the item in the Markdown of the current item. The Markdown editors on GitHub will even render a scrollable UI component you can use to search by name for the item you want to link when you type start typing `#`. You can even reference items from different repos (as long as they are public) by prefixing the `#` with the name of the owner (GitHub username) and the repos name eg. `MonashDeepNeuron\HPC-Training#1`. You can also create a pretty link if you put the link somewhere in a list item. +You may notice that Issues, PRs and discussions have an associated #-number. This is used to reference the item within other items of the same or other repos. The `#` prefix can be used to create a link to the item in the Markdown of the current item. The Markdown editors on GitHub will even render a scrollable UI component you can use to search by name for the item you want to link when you type start typing `#`. You can even reference items from different repos (as long as they are public) by prefixing the `#` with the name of the owner (GitHub username) and the repos name eg. `MonashDeepNeuron\HPC-Training#1`. You can also create a pretty link if you put the link somewhere in a list item. ### Prefix - `@` diff --git a/src/github/discussions.md b/src/github/discussions.md index ed5ecf9..71ca5b6 100644 --- a/src/github/discussions.md +++ b/src/github/discussions.md @@ -1 +1,7 @@ # Discussions + +Discussions are places where you can ask questions, share ideas or have general conversations that aren't necessarily Issues. This can be a great place to discuss ideas or get further information on how to use a project or even collaborate on it. It is also beneficial to the maintainers as it can help surface things missing in th projects official documentation. + +Discussions are very much like the Discussion Threads from Issues and PRs. You can comment, react with emojis and even upvote posts and comments. Top level comments are also individual items which can be replied to directly making it easier to focus on sub topics generated by comments. On Q&A discussions you can also mark particular comments as the answer like a mini StackOverflow. + + diff --git a/src/github/github.md b/src/github/github.md index f4addaf..bcf63b1 100644 --- a/src/github/github.md +++ b/src/github/github.md @@ -6,4 +6,4 @@ Your first task is to sign up for a GitHub account, if you haven't already. I wo [GitHub - Join](https://github.com/join) -It is also a good idea to install the GitHub mobile app. This allows you track and manage projects and reply to messages and issues from your phone. +It is also a good idea to install the GitHub mobile app. This allows you track and manage projects and reply to messages and Issues from your phone. diff --git a/src/github/milestones.md b/src/github/milestones.md index 1487a3d..7b08fb3 100644 --- a/src/github/milestones.md +++ b/src/github/milestones.md @@ -1,3 +1,3 @@ # Milestones -Milestones are a easy progression trackers that can be used to, well mark important Milestones for a project and link this progress to the resolution of issues or merging of PRs. Milestones also have an end date associated with them to help keep you on track. To create a Milestone, go to either the 'Issues' or 'Pull requests' tab of the repo and to the top right of the list views you will see a button called 'Milestones'. From this page you can create a Milestone. Issues and PRs are added to the Milestone from the page of the particular time you want to add. Milestones are good for tracking large goals that span many issues and PRs. You must go back to the Milestones page and close it manually to meat the Milestones deadline. +Milestones are a easy progression trackers that can be used to, well mark important Milestones for a project and link this progress to the resolution of Issues or merging of PRs. Milestones also have an end date associated with them to help keep you on track. To create a Milestone, go to either the 'Issues' or 'Pull requests' tab of the repo and to the top right of the list views you will see a button called 'Milestones'. From this page you can create a Milestone. Issues and PRs are added to the Milestone from the page of the particular time you want to add. Milestones are good for tracking large goals that span many Issues and PRs. You must go back to the Milestones page and close it manually to meat the Milestones deadline. diff --git a/src/github/pages.md b/src/github/pages.md index a86f4d7..68ed806 100644 --- a/src/github/pages.md +++ b/src/github/pages.md @@ -1 +1,5 @@ # GitHub Pages + +🚧 Under Construction 🚧 + +⚠️ Coming soon! 🏗️ diff --git a/src/github/pr.md b/src/github/pr.md index c9b3d01..6b05e3d 100644 --- a/src/github/pr.md +++ b/src/github/pr.md @@ -6,11 +6,11 @@ Pull Requests (PRs) are request from collaborators to pull in their new changes ## Discussion Thread -Just like issues, PRs also have a discussion thread that allow conversations about the PR to be in the same place as the PR. +Just like Issues, PRs also have a discussion thread that allow conversations about the PR to be in the same place as the PR. ## Closing a PR -Again, like issues you can close a PR meaning it cannot be merged without reopening the PR. +Again, like Issues you can close a PR meaning it cannot be merged without reopening the PR. ## Reviewers @@ -34,7 +34,7 @@ You can make an PR a part of a milestones progress. ## Development -This section shows the issues that are linked to the PR. Issues can be linked by creating the branch from the issue or by using ['Closing Keywords'](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) in the description of the PR. +This section shows the Issues that are linked to the PR. Issues can be linked by creating the branch from the Issue or by using ['Closing Keywords'](https://docs.github.com/en/Issues/tracking-your-work-with-Issues/linking-a-pull-request-to-an-Issue) in the description of the PR. ## Notifications diff --git a/src/github/releases.md b/src/github/releases.md index cd7ba34..3f0b8de 100644 --- a/src/github/releases.md +++ b/src/github/releases.md @@ -1 +1,3 @@ # Tags and Releases + +We saw Git chapter tags and how they can be used to create named commit points, often for marking versions of the codebase. GitHub takes this to the next step by allowing you to use tags to create GitHub releases where you can store your packaged versions of the codebase and share what has changed to your users. It can even generate crude changelogs for you based on commit message (a good reason to create good commit messages). diff --git a/src/github/templates.md b/src/github/templates.md index 1f37f96..aa40b09 100644 --- a/src/github/templates.md +++ b/src/github/templates.md @@ -1 +1,3 @@ # Template Repositories + +When creating repositories, you have the option of creating the repository as a template repository. This can be useful for creating a skeleton for a project that you wish to distribute but be disconnected from the upstream source. This option is a checkbox located above the text field where you enter the repos name. You can then either clone the template to update the template itself or copy the template to use it as the starting point for your new project. diff --git a/src/github/wikis.md b/src/github/wikis.md index 2247f09..caa0f96 100644 --- a/src/github/wikis.md +++ b/src/github/wikis.md @@ -1 +1,5 @@ # Wikis + +🚧 Under Construction 🚧 + +⚠️ Coming soon! 🏗️ diff --git a/src/github/workflow.md b/src/github/workflow.md index dd049b1..cf27104 100644 --- a/src/github/workflow.md +++ b/src/github/workflow.md @@ -1 +1,27 @@ # Workflow + +In this page we are going to explore a potential workflow you can use with Git and GitHub when collaborating with multiple people. No it doesn't have a name, I'm not a marketing guy and it doesn't need one. The focus of this workflow is to allow as-easy-as-possible integration of many different features without breaking the entire system and its deployment by funneling changes down from feature (or patch) branches into staging branches and finally into the main deployment branch. + +## Main Deployment Branch + +In essence you have a single branch that is used as as the deployment branch. You can of course call ths whatever you want but we'll assume this is the `main` branch. From the `main` you make deployments and use tags to mark releases. + +## Development and Staging Branches + +You also have a mirroring branch that acts as the source of both new feature branches and the staging area to ensure integrating multiple features do not break each others new functionality or existing functionality. I typically call this `dev` but again, you are free to call it whatever you want. You can also have multiple staging levels if you want more rigorous filtering down of features. The `dev` branch is to be kept up to date with `main`. This should be easy to maintain if you only pull `dev` changes into `main` and don't update `main` directly but you can pull `main` back into `dev` if need be. + +## Creating Feature Branches + +From the `HEAD` of `dev` new branches are created for feature development. This will ensure that if a separate but new feature is created and pulled into `dev` your new feature can benefit or not have issues later on merging the two histories together. If need be features can obviously be created from any point in `dev` history if you do not want to include branch-base staged changes. When a feature is based off an Issue use the GitHub 'Create branch from Issue'. Ensure to change the base branch to the `dev` branch. You can name these branches whatever you want but the GitHub generated one is good enough. + +## Merging Features to Development or Staging Branches + +When a feature is ready to be integrated, create a PR from the feature branch into the `dev` branch (or appropriately levelled staging branch if applicable) and request reviews from the relevant people/maintainers. If you are not a maintainer then the reviews/maintainers will do the rest and should keep you updated on the PR's progress and may request clarification or revisions to make the changes fit into the existing/upcoming codebase. In the PR's description it is good to include a brief description/list of the changes you have made as well as link and related Issues, PR's, external resources or anything else relevant to the PR however, consult the CONTRIBUTING, CODE_OF_CONDUCT and GUIDELINES files for the repo to ensure you adhere to the specific repos contributing policies as every repo can be different, even if managed by the same people, company and/or organisation. + +## Merging Development or Staging Branches into the Main Deployment Branch + +If you are a maintainer of a repo you may have to setup a PR for merging upcoming changes into the `main` branch. If you are maintaining a bigger project then coordinating with other maintainers and contributors about which changes you want to integrate into each release can make it easier to create the PRs and stage as many new changes in `dev` that is feasible so you can thoroughly test how the changes play together. You can make a single release for each PR into `main` or you can do multiple PR's if you have a more structured release schedule. Ensure you also have this PR reviewed by others as it can help catch problems before they hit you main branch. You can also branch the `HEAD` of `main` and merge a test PR into this new branch to do test deployments before pulling `dev` into `main`. + +## Notes + +This is not a very thorough workflow but is aimed to be as simple as possible while still be effective for teams to collaborate together. This workflow does not govern coding practices, commit conventions nor stop bad code from entering a codebase but can help setup a skeleton for collaboration between multiple people. Maintainers and collaborators should still make use of the Issues, Discussions, Projects etc. to help coordinate and track problems and changes for a repo. diff --git a/src/tlrd.md b/src/tlrd.md index ec1313c..8c104a8 100644 --- a/src/tlrd.md +++ b/src/tlrd.md @@ -2,4 +2,8 @@ The section of the book is designed to be a quick reference to some of the most common commands or actions for Git and GitHub. -~ + + +🚧 Under Construction 🚧 + +⚠️ Coming soon! 🏗️ From b35092d764686fbbfbb0e1673d7eb2283f6daedd Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Mon, 21 Aug 2023 13:52:17 +1000 Subject: [PATCH 10/14] Added content on Rebasing. Added TL;DR page. Updated GitHub setup page. Updated GitHub discussions page. --- src/git/rebasing.md | 25 ++++++- src/github/discussions.md | 2 +- src/github/setup.md | 6 ++ src/tlrd.md | 138 +++++++++++++++++++++++++++++++++++++- 4 files changed, 165 insertions(+), 6 deletions(-) diff --git a/src/git/rebasing.md b/src/git/rebasing.md index 8c0f5a1..778f8ad 100644 --- a/src/git/rebasing.md +++ b/src/git/rebasing.md @@ -1,5 +1,26 @@ # Rebasing -🚧 Under Construction 🚧 +Rebasing is a powerful feature of Git that allows you to rewrite the history of a branch. When you branch, the commit and branch from which you branched from becomes the base of *your* branch's history. However, if changes are made to the base branch then your branch and the base branch are said to have divergent histories. If you want to integrate the changes from the base into your branch you have two options: -⚠️ Coming soon! 🏗️ +1. Merge the changes into your branch +2. Rebase your branch + +Merging is the simplest and most obvious solutions. it involves simply pulling the changes from the base branch back into your branch as an new merge commit, tieing the histories together. This is often what you will want to do but it cna clutter the history of your branch if the base branch is very active as you will often have to merge the base back into your branch. + +Rebasing, as the name suggests allows you to rip up the base of your branch and root it to the `HEAD` of the same or even another branch. This allows you to take the changes and apply them into the **history** of your branch. + +```sh +git rebase +``` + +## Interactive Rebasing + +Git also offers interactive rebasing which allows you to control exactly how the history is rewritten for the branch. This feature can be enhanced by IDE (Integrated Developer Environments) allowing you to effectively rewrite your progress as you go. + +```sh +git rebase -i +``` + +## When not to rebase + +Rebasing is powerful but can make it difficult to track when upstream/divergent changes are integrated into a branch. In general it is best to ***not*** rebase when the branch is public (ie. rebase `main` onto a feature for... whatever reason) especially if the branch has an upstream remote as this will create divergent histories between your local rebased branch and the remote which can be extremely difficult to fix and track. diff --git a/src/github/discussions.md b/src/github/discussions.md index 71ca5b6..847c0c0 100644 --- a/src/github/discussions.md +++ b/src/github/discussions.md @@ -4,4 +4,4 @@ Discussions are places where you can ask questions, share ideas or have general Discussions are very much like the Discussion Threads from Issues and PRs. You can comment, react with emojis and even upvote posts and comments. Top level comments are also individual items which can be replied to directly making it easier to focus on sub topics generated by comments. On Q&A discussions you can also mark particular comments as the answer like a mini StackOverflow. - +Discussions can also be converted into an Issue making it easier to transfer a conversation that was once a Discussion into an Issue if the discussion resulting in an Issue being found or surfaced a desired feature from the community. diff --git a/src/github/setup.md b/src/github/setup.md index cf6d7e4..40dadd0 100644 --- a/src/github/setup.md +++ b/src/github/setup.md @@ -3,8 +3,14 @@ Once you have a GitHub account setup, it is a good idea to link it with you local Git configuration for your system. Open a new shell and run the following commands, filling in your own details. ```sh +# Set the name that is identifiable for credit when review version history git config --global user.name "github-username" + +# Set an Email address that will be associated with each history marker git config --global user.email "github-email" + +# Set automatic command line coloring for Git for easy reviewing +git config --global color.ui auto ``` ## GitHub Personal Access Tokens diff --git a/src/tlrd.md b/src/tlrd.md index 8c104a8..8cfcbe7 100644 --- a/src/tlrd.md +++ b/src/tlrd.md @@ -2,8 +2,140 @@ The section of the book is designed to be a quick reference to some of the most common commands or actions for Git and GitHub. - +## Installation -🚧 Under Construction 🚧 +[Download](http://git-scm.com) -⚠️ Coming soon! 🏗️ +## Setup + +```sh +# Set the name that is identifiable for credit when review version history +git config --global user.name "github-username" + +# Set an Email address that will be associated with each history marker +git config --global user.email "github-email" + +# Set automatic command line coloring for Git for easy reviewing +git config --global color.ui auto +``` + +## Initialisation + +```sh +# Initialise a directory as a Git repo +git init + +# Clone a repo from the URL +git clone +``` + +## Staging and Commits + +```sh +# Show which files are staged +git status + +# Stage file or pattern +git add + +# Remove all changes +git reset + +# Show diff of changed files +git diff + +# Show diff of staged files +git diff --staged + +# Commit staged changes w/ message +git commit -m "Commit Message" +``` + +## Branches + +```sh +# List branches (* indicates current branch) +git branch + +# Checkout to branch +git checkout + +# Create a new branch +git branch + +# Create new branch and checkout to it +git checkout -b + +# Merge incoming branch into current branch +git merge +``` + +## Inspecting and Compare + +```sh +# Show commits from current branch's history +git log + +# Show commits on branch-A not on branch-B +git log .. + +# Show commits that modified file, even across renames +git log --follow + +# Show diff of what is in branch-A that is not on branch-B +git diff .. + +# Display any Git object in human-readable format +git diff +``` + +## Remotes and Sharing + +```sh +# Add Git URL as remote +git remote add + +# Retrieve changes from remote without integrating changes +git fetch + +# Fetch and merge changes from remote from the tracked remote branch +git pull + +# Transmit changes from local branch to remote onto branch +git push + +# Set current branch to track branch at remote +git push -u + +# Merge a remote branch into local branch +git merge / +``` + +## Rebasing + +```sh +# Apply commits from the current branch on top of the new-base-branch. +git rebase + +# Interactively apply commits from the current branch on top of the new-base-branch. +git rebase -i + +# Clear all staged changes and rewrite working tree from the specified commit-hash +git reset --hard +``` + +## Stashes + +```sh +# Save modified and staged changes in stash +git stash + +# Show all stashes in stack-order +git stash list + +# Pop stash from top of stash-stack +git stash pop + +# Drop stash from top of stash-stack +git stash drop +``` From 55b2c88e262b17772e56290398bf7cb4b27a114e Mon Sep 17 00:00:00 2001 From: oraqlle <41113853+oraqlle@users.noreply.github.com> Date: Tue, 22 Aug 2023 16:27:27 +1000 Subject: [PATCH 11/14] Updated `SUMMARY.md`. --- src/SUMMARY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c8d3a9d..fb63dfc 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -24,11 +24,11 @@ - [Pull Requests](github/pr.md) - [Milestones](github/milestones.md) - [Tags and Releases](github/releases.md) - - [Wikis](github/wikis.md) + - [Wikis]() - [Discussions](github/discussions.md) - [Licensing and OSS](github/licenses-oss.md) - [A Sample Workflow](github/workflow.md) - [GitHub Pages](github/pages.md) - + - [GitHub Organisations]() - [Acknowledgements](acknowledgements.md) From 26a0d80f6ba7244e7248a9ff2533ff2419ce5836 Mon Sep 17 00:00:00 2001 From: Nyan Kyaw Date: Sun, 1 Oct 2023 11:17:12 +1100 Subject: [PATCH 12/14] Fixing up grammar/spelling mistakes, and performing a general review of the material. Looks good --- .gitignore | 1 + src/git/branches.md | 11 +++--- src/git/changes-staging-commits.md | 4 ++- src/git/commands.md | 32 +++++++++--------- src/git/config.md | 44 ++++++++++++------------ src/git/create.md | 5 +++ src/git/git.md | 52 ++++++++++++++--------------- src/git/install.md | 4 +-- src/git/merging.md | 2 +- src/git/rebasing.md | 10 +++--- src/github/collaboration.md | 26 +++++++-------- src/github/create-cloning-upload.md | 2 +- src/github/discussions.md | 6 ++-- src/github/forks.md | 6 ++-- src/github/github.md | 4 +-- src/github/issues.md | 16 ++++----- src/github/licenses-oss.md | 22 ++++++------ src/github/milestones.md | 2 +- src/github/pr.md | 14 ++++---- src/github/push-pull-fetch.md | 6 ++-- src/github/releases.md | 2 +- src/github/setup.md | 12 +++---- src/github/workflow.md | 14 ++++---- src/home.md | 6 ++-- src/tlrd.md | 16 ++++----- 25 files changed, 164 insertions(+), 155 deletions(-) diff --git a/.gitignore b/.gitignore index 7585238..8afc88e 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ book +*.DS_Store \ No newline at end of file diff --git a/src/git/branches.md b/src/git/branches.md index 131e43b..dcaabfc 100644 --- a/src/git/branches.md +++ b/src/git/branches.md @@ -1,10 +1,10 @@ # Branches, Stashes and Tags -Git has various ways of storing and marking the different states and histories of a repo. The most common is a branch, which serves as a logically separate history for a repository. This allows various changes from multiple people to not conflict with each other. Stashes are temporary stores of changes that can be pushed to or popped from, kinda like a stack of changes. Tags are named markers for commits in a repo's history. +Git has various ways of storing and marking the different states and histories of a repo. The most common is a _branch_, which serves as a logically separate history for a repository. This allows various changes from multiple people to not conflict with each other. _Stashes_ are temporary stores of changes that can be pushed to or popped from, kind of like a stack of changes. _Tags_ are named markers for commits in a repo's history. ## Branches -To create a new branch, you simply use the `git branch` with the name of the branch as the argument. This will create a new branch `HEAD` a the commit you are currently at. You can also pass a commit hash as a second argument to create the branch at the associated commit. Renaming a branch can be achieve by using the `-m` or `-M` (forced) flags and passing the old name (optional) and new name as arguments respectively. You can also delete branches using the `-d` flag. To switch to a branch we use the `checkout` command, supplying the branch name as an argument. +To create a new branch, you simply use the `git branch` with the name of the branch as the argument. This will create a new branch `HEAD` at the commit you are currently at. You can also pass a commit hash as a second argument to create the branch at that associated commit. Renaming a branch can be achieved by using the `-m` or `-M` (forced) flags and passing the old name (optional) and new name as arguments respectively. You can also delete branches using the `-d` flag. To switch to a branch we use the `checkout` command, supplying the branch name as an argument. ```sh # Create a new branch @@ -31,7 +31,7 @@ git branch -d new-branch-2 ## Stashes -Stashes store WIP changes that can be reapplied on to the currently checked out commit. Stashes are labelled by a number value starting at 0, indicating the most recent stash. You can pop or drop (delete) a stash from a particular index by providing it as an argument, with the default being the most recent stash. You can also list a repos stashes using the `list` sub-command. +Stashes store WIP changes that can be reapplied on to the currently checked out commit. Stashes are labelled by a number value starting at 0, indicating the most recent stash. You can `pop` or `drop` (delete) a stash from a particular index by providing it as an argument, with the default being the most recent stash. You can also list a repo's stashes using the `list` sub-command. ```sh # Create a stash @@ -40,7 +40,8 @@ git stash # Pop the most recent stash git stash pop -git stash +# Drop (delete) the most recent stash +git stash drop # Stash with a message git stash -m "Stash 1" @@ -72,7 +73,7 @@ stash@{1}: WIP on main: cea4a92 current HEAD commit message ## Tags -Tags allow us to name a particular commit such that it can be reference and changed to it. Tagging is mostly used to mark certain versions of a codebase. Tags can be created using the `tag` command and providing a label for the tag. Like most of Git, the `-d` flag can be used to delete a tag as well. +Tags allow us to name a particular commit such that it can be referenced and changed to it. Tagging is mostly used to mark certain versions of a codebase. Tags can be created using the `tag` command and providing a label for the tag. Like most of Git, the `-d` flag can be used to delete a tag as well. ```sh # Create tag diff --git a/src/git/changes-staging-commits.md b/src/git/changes-staging-commits.md index 1693f18..9849fdc 100644 --- a/src/git/changes-staging-commits.md +++ b/src/git/changes-staging-commits.md @@ -1,6 +1,8 @@ # Changes, Staging and Commits -Whenever you make changes to the contents of a repository, this changes will be compared as a diff between the working tree and the `HEAD` of the repositories history. To view which files have changed you can run the `git status` command. Once you are happy with your changes, you can add them to the file index for staging. You can specify certain files you want to keep or using `.` to stage all new changes. Finally you can then commit your changes. Commits are saved snapshots of a repo's state. When you create a commit, a hash value is generated for it, this is used to jump back to the commit using `switch` or `checkout`. Commits also have a short message associated with it to describe the changes made in the commit. +Whenever you make changes to the contents of a repository, these changes will be compared as a diff between the working tree and the `HEAD` of the repository's history. To view which files have changed you can run the `git status` command. Once you are happy with your changes, you can `git add ` them to the file index for staging. You can specify certain files you want to keep or use `.` to stage all new changes. + +Finally you can then commit your changes. Commits are saved snapshots of a repo's state. When you create a commit, a hash value is generated for it, this is used to jump back to the commit using `switch` or `checkout`. Commits also have a short message associated with it to describe the changes made in the commit. ```sh # Stage all changes in repo diff --git a/src/git/commands.md b/src/git/commands.md index dc05302..af960f1 100644 --- a/src/git/commands.md +++ b/src/git/commands.md @@ -1,22 +1,22 @@ # Common Git Commands -Git is predominately used through its command line interface (CLI). This means Git operates using a variety of different commands (and even sub-commands, commands options for commands). Some of the most commonly used commands and their purpose: +Git is predominately used through its command line interface (CLI). This means Git operates using a variety of different commands (and even sub-commands, command options for commands). Some of the most commonly used commands and their purpose: -| Command | Description | -|:----------:|:---------------------------------------------------------------:| -| `init` | Initialise a repository | -| `clone` | Clone repository from remote host at URL | -| `checkout` | Checkout to branch or commit | -| `branch` | Create branch | -| `add` | Add files to commit stage | -| `commit` | Commit staged changes | -| `merge` | Merge changes from another branch into current branch | -| `push` | Push changes to remote repository | -| `pull` | Pull changes from remote repository | -| `fetch` | Pull changes from remote repository without integrating changes | -| `rebase` | Reapply commits on top of new branch `HEAD` | -| `status` | List the currently modified files and status of remotes | -| `tag` | Create or list a tag at the current `HEAD` | +| Command | Description | +| :--------: | :-----------------------------------------------------------------------------------: | +| `init` | Initialise a repository | +| `clone` | Clone repository from remote host at URL | +| `checkout` | Checkout to branch or commit | +| `branch` | Create branch | +| `add` | Add files to commit stage | +| `commit` | Commit staged changes | +| `merge` | Merge changes from another branch into current branch | +| `push` | Push changes to remote repository | +| `pull` | Pull changes from remote repository | +| `fetch` | Pull changes from remote repository without integrating changes into local repository | +| `rebase` | Reapply commits on top of new branch `HEAD` | +| `status` | List the currently modified files and status of remotes | +| `tag` | Create or list a tag at the current `HEAD` | There are many more commands within Git's CLI. You can view them and their functionality using Git's Manpage. To access the Manpage run the following commands. diff --git a/src/git/config.md b/src/git/config.md index 415ee09..5af3d8b 100644 --- a/src/git/config.md +++ b/src/git/config.md @@ -4,36 +4,36 @@ The properties and behaviour of Git can be customized using special files within ## `.gitignore` -The `.gitignore` file is used to specify files or file patterns you wish for Git to ignore. File patterns are specified using Unix based [globbing](https://linux.die.net/man/7/glob) (ie. the use of wildcard patterns). +The `.gitignore` file is used to specify files or file patterns you wish for Git to ignore. File patterns are specified using Unix-based [globbing](https://linux.die.net/man/7/glob) (ie. the use of wildcard patterns). ## `.gitattributes` The `.gitattributes` file is used to specify the attributes of files or file patterns. One particular useful case of the `.gitattributes` file is to ensure the correct End-of-Line (EOL) characters are used in certain files as the default choice between Unix-like systems and Windows is different which can lead to some unique bugs and inconsistencies when collaborating with people using different systems. It also allows you to control exactly which files these attributes apply to ensuring only the right files are affected. -| Pattern | Examples | Explanation | -|:------------------------------------:|:-----------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| -| `**/logs` | `logs/debug.log` `logs/monday/foo.bar` `build/logs/debug.log` | You can prepend a pattern with a double asterisk to match directories anywhere in the repository. | -| `**/logs/debug.log` | `logs/debug.log` `build/logs/debug.log` but not `logs/build/debug.log` | You can also use a double asterisk to match files based on their name and the name of their parent directory. | -| `*.log` | `debug.log` `foo.log` `.log` `logs/debug.log` | An asterisk is a wildcard that matches zero or more characters. | -| `*.log` `!important.log` | `debug.log` `trace.log` but not `important.log` `logs/important.log` | Prepending an exclamation mark to a pattern negates it. If a file matches a pattern, but also matches a negating pattern defined later in the file, it will not be ignored. | -| `*.log` `!important/*.log` `trace.*` | `debug.log` `important/trace.log` but not `important/debug.log` | Patterns defined after a negating pattern will re-ignore any previously negated files. | -| `/debug.log` | `debug.log` but not `logs/debug.log` | Prepending a slash matches files only in the repository root. | -| `debug.log` | `debug.log` `logs/debug.log` | By default, patterns match files in any directory | -| `debug?.log` | `debug0.log` `debugg.log` but not `debug10.log` | A question mark matches exactly one character. | -| `debug[0-9].log` | `debug0.log` `debug1.log` but not `debug10.log` | Square brackets can also be used to match a single character from a specified range. | -| `debug[01].log` | `debug0.log` `debug1.log` but not `debug2.log` `debug01.log` | Square brackets match a single character form the specified set. | -| `debug[!01].log` | `debug2.log` but not `debug0.log` `debug1.log` `debug01.log` | An exclamation mark can be used to match any character except one from the specified set. | -| `debug[a-z].log` | `debuga.log` `debugb.log` but not `debug1.log` | Ranges can be numeric or alphabetic. | -| `logs` | `logs` `logs/debug.log` `logs/latest/foo.bar` `build/logs` `build/logs/debug.log` | If you don't append a slash, the pattern will match both files and the contents of directories with that name. In the example matches on the left, both directories and files named logs are ignored | -| `logs/` | `logs/debug.log` `logs/latest/foo.bar` `build/logs/foo.bar` `build/logs/latest/debug.log` | Appending a slash indicates the pattern is a directory. The entire contents of any directory in the repository matching that name – including all of its files and subdirectories – will be ignored | -| `logs/` `!logs/important.log` | `logs/debug.log` `logs/important.log` | Wait a minute! Shouldn't `logs/important.log` be negated in the example on the left Nope! Due to a performance-related quirk in Git, you can not negate a file that is ignored due to a pattern matching a directory | -| `logs/**/debug.log` | `logs/debug.log` `logs/monday/debug.log` `logs/monday/pm/debug.log` | A double asterisk matches zero or more directories. | -| `logs/*day/debug.log` | `logs/monday/debug.log` `logs/tuesday/debug.log` but not `logs/latest/debug.log` | Wildcards can be used in directory names as well. | -| logs/debug.log | `logs/debug.log` but not `debug.log` `build/logs/debug.log` | Patterns specifying a file in a particular directory are relative to the repository root. (You can prepend a slash if you like, but it doesn't do anything special.) | +| Pattern | Examples | Explanation | +| :----------------------------------: | :---------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `**/logs` | `logs/debug.log` `logs/monday/foo.bar` `build/logs/debug.log` | You can prepend a pattern with a double asterisk to match directories anywhere in the repository. | +| `**/logs/debug.log` | `logs/debug.log` `build/logs/debug.log` but not `logs/build/debug.log` | You can also use a double asterisk to match files based on their name and the name of their parent directory. | +| `*.log` | `debug.log` `foo.log` `.log` `logs/debug.log` | An asterisk is a wildcard that matches zero or more characters. | +| `*.log` `!important.log` | `debug.log` `trace.log` but not `important.log` `logs/important.log` | Prepending an exclamation mark to a pattern negates it. If a file matches a pattern, but also matches a negating pattern defined later in the file, it will not be ignored. | +| `*.log` `!important/*.log` `trace.*` | `debug.log` `important/trace.log` but not `important/debug.log` | Patterns defined after a negating pattern will re-ignore any previously negated files. | +| `/debug.log` | `debug.log` but not `logs/debug.log` | Prepending a slash matches files only in the repository root. | +| `debug.log` | `debug.log` `logs/debug.log` | By default, patterns match files in any directory | +| `debug?.log` | `debug0.log` `debugg.log` but not `debug10.log` | A question mark matches exactly one character. | +| `debug[0-9].log` | `debug0.log` `debug1.log` but not `debug10.log` | Square brackets can also be used to match a single character from a specified range. | +| `debug[01].log` | `debug0.log` `debug1.log` but not `debug2.log` `debug01.log` | Square brackets match a single character form the specified set. | +| `debug[!01].log` | `debug2.log` but not `debug0.log` `debug1.log` `debug01.log` | An exclamation mark can be used to match any character except one from the specified set. | +| `debug[a-z].log` | `debuga.log` `debugb.log` but not `debug1.log` | Ranges can be numeric or alphabetic. | +| `logs` | `logs` `logs/debug.log` `logs/latest/foo.bar` `build/logs` `build/logs/debug.log` | If you don't append a slash, the pattern will match both files and the contents of directories with that name. In the example matches on the left, both directories and files named logs are ignored | +| `logs/` | `logs/debug.log` `logs/latest/foo.bar` `build/logs/foo.bar` `build/logs/latest/debug.log` | Appending a slash indicates the pattern is a directory. The entire contents of any directory in the repository matching that name – including all of its files and subdirectories – will be ignored | +| `logs/` `!logs/important.log` | `logs/debug.log` `logs/important.log` | Wait a minute! Shouldn't `logs/important.log` be negated in the example on the left Nope! Due to a performance-related quirk in Git, you can not negate a file that is ignored due to a pattern matching a directory | +| `logs/**/debug.log` | `logs/debug.log` `logs/monday/debug.log` `logs/monday/pm/debug.log` | A double asterisk matches zero or more directories. | +| `logs/*day/debug.log` | `logs/monday/debug.log` `logs/tuesday/debug.log` but not `logs/latest/debug.log` | Wildcards can be used in directory names as well. | +| logs/debug.log | `logs/debug.log` but not `debug.log` `build/logs/debug.log` | Patterns specifying a file in a particular directory are relative to the repository root. (You can prepend a slash if you like, but it doesn't do anything special.) | > Note: > -> - These explanations assume your .gitignore file is in the top level directory of your repository, as is the convention. If your repository has multiple .gitignore files, simply mentally replace "repository root" with "directory containing the `.gitignore` file" (and consider unifying them, for the sanity of your team). +> - These explanations assume your `.gitignore` file is in the top level directory of your repository, as is the convention. If your repository has multiple `.gitignore` files, simply mentally replace "repository root" with "directory containing the `.gitignore` file" (and consider unifying them, for the sanity of your team). > - Additionally, lines starting `#` are treated as comments and a `\` character can be prepended to a character that usually has a special meaning to escape it (ie. match the literal character `[` (using `\[` in the `.gitignore`) that is in a file name instead of start a match group). ### Example `.gitattributes` diff --git a/src/git/create.md b/src/git/create.md index a914eb1..647a826 100644 --- a/src/git/create.md +++ b/src/git/create.md @@ -3,7 +3,12 @@ To create a repository you first want to create a new directory. Then you can initialise this directory as the root of your new repo. ```sh +# Make a new directory/folder to be the root of your new repo mkdir project + +# Navigate into the root directory cd project + +# Initialise your new repo git init ``` diff --git a/src/git/git.md b/src/git/git.md index abae618..a05451b 100644 --- a/src/git/git.md +++ b/src/git/git.md @@ -2,48 +2,48 @@ ## What is Version Control? -Version Control allows for changes within a repository to be tracked. This allows for you to retain a historical ledger of your source code. This allows you easier move between different points in your repository's history. It also allows you to develop features on separate branches so the changes do not affect the currently working codebase +Version Control allows for changes within a repository to be tracked. This allows you to retain a historical ledger of your source code. This allows you to easily move between different points in your repository's history. It also allows you to develop features on separate branches so the changes do not affect the currently working codebase. ## What is Git? -Git is a Source Control Management tool (SCM). It keeps a history of multiple files and directories in a bundle called a repository. Git tracks changes using save points called commits. Commits use .diff files to track the difference in files between commits. Repositories can have multiple branches allow many different developers to create new changes and fixes to a codebase that are separate from each other. You can also switch between branches to work on many different changes at once. These branches can then later be merged back together to a main branch, integrating the various changes. +Git is a Source Control Management tool (SCM). It keeps a history of multiple files and directories in a bundle called a repository. Git tracks changes using save points called commits. Commits use .diff files to track the difference in files between commits. Repositories can have multiple branches allowing many different developers to create new changes and fixes to a codebase that are separate from each other. You can also switch between branches to work on many different changes at once. These branches can then later be merged back together into a main branch, integrating the various changes. ### Common Terms in Git -- Repository (or repo) - A project, workspace or folder containing your codebase. -- Staging - State the files that are to be added, those that have changed or those that have been deleted from repository for a commit. -- Commit - A saved snapshot of the codebase that has an associated hash. -- Branch - A separate history chain that can later be merged into other branches. -- Clone - A machine local copy of a repository, usually obtained from a remote repository hosting service (GitHub, GitLab). -- HEAD - The top (most recent) commit of a branch or repository. -- Checkout - The means to switch to a branch (HEAD) or commit. -- Pull/Push - Sync local repository with remote repository by pushing up your changes or pulling in the remote ones. -- Fetch - Pull metadata about for remote changes without integrating remote changes. -- Merge - Combine the history of another branch into the current branch. -- Stash - Save changes in a temporary save commit as a Work-In-Progress (WIP). -- Tags - A named commit in a repository's history. -- Rebase - A technique for reapplying commits on top of a base branch HEAD. -- Diff - The difference between a file, folder, commit or branch across commits and branches. -- Remote - A copy of a repository that lives off machine. -- Pull Request - A request to merge a branches changes into your branch (usually a feature branch into `main`). -- Fork - A fork is a clone of a repository that shares its history and acts similar to a branch but is logically separated from the original with the forkee as the owner of the fork. -- Upstream - The source location of a repository. -- OSS - Acronym for Open Source Software. +- **Repository** (or repo) - A project, workspace or folder containing your codebase. +- **Staging** - State the files that are to be added, those that have changed or those that have been deleted from the repository for a commit. +- **Commit** - A saved snapshot of the codebase that has an associated hash. +- **Branch** - A separate history chain that can later be merged into other branches. +- **Clone** - A machine local copy of a repository, usually obtained from a remote repository hosting service (GitHub, GitLab). +- **HEAD** - The top (most recent) commit of a branch or repository. +- **Checkout** - The means to switch to a branch (HEAD) or commit. +- **Pull/Push** - Sync the local repository with the remote repository by pushing up your changes or pulling in the remote ones. +- **Fetch** - Pull metadata about remote changes without integrating remote changes. +- **Merge** - Combine the history of another branch into the current branch. +- **Stash** - Save changes in a temporary save commit as a Work-In-Progress (WIP). +- **Tags** - A named commit in a repository's history. +- **Rebase** - A technique for reapplying commits on top of a base branch HEAD. +- **Diff** - The difference between a file, folder, commit or branch across commits and branches. +- **Remote** - A copy of a repository that lives off your machine. +- **Pull Request** - A request to merge a branch's changes into your branch (usually a feature branch into main). +- **Fork** - A fork is a clone of a repository that shares its history and acts similar to a branch but is logically separated from the original with the forkee as the owner of the fork. +- **Upstream** - The source location of a repository. +- **OSS** - Acronym for Open Source Software. ### Git Workflow -The basic workflow for getting started with are as follows: +The basic workflow for getting started is as follows: 1. Initialise a repository [ie. create the repository] 2. Add/write file contents 3. Stage changes 4. Commit changes -5. Create branches for different features, usually branched from the `main` branch (or equivalent) +5. Create branches for different features, usually branched from the main branch (or equivalent) 6. Add/make changes 7. Stage new changes 8. Commit changes -9. Repeat 6-8 until feature is done -10. Create a 'Pull Request'. This is a request for the owner of the `main` branch to merge your branches changes into `main` ie. pull them into main. -11. Code owner merges feature branch into `main` +9. Repeat 6-8 until the feature is done +10. Create a 'Pull Request'. This is a request for the owner of the main branch to merge your branch's changes into main ie. pull them into main. +11. Code owner merges feature branch into main 12. Deploy changes 13. Repeat 5-12 for projects lifetime. diff --git a/src/git/install.md b/src/git/install.md index b5a08f7..1993a4c 100644 --- a/src/git/install.md +++ b/src/git/install.md @@ -1,7 +1,7 @@ # Installing Git -It is really simple to install, instructions and binaries can be obtained from its [official download](https://git-scm.com/download) page. Select your target platform (Windows, macOS, Linux) to see the various options for install Git. +Git is really simple to install, instructions and binaries can be obtained from its [official download](https://git-scm.com/download) page. Select your target platform (Windows, macOS, Linux) to see the various options for install Git. -> Note: On Windows, you will have to got through an install Wizard. Customize the installation to whatever you see fit but you must tick the option for added Git to your system `%PATH%` or 'PATH'. +> Note: On Windows, you will have to got through an install Wizard. Customize the installation to whatever you see fit but you **must tick the option** for adding Git to your system `%PATH%` or 'PATH'. For the purposes of the this book, we will assume you are using a Bash-based terminal. This is just the regular shell on Linux and macOS. You can use the Git Bash Shell that installs with Git on Windows. diff --git a/src/git/merging.md b/src/git/merging.md index 74bdeb9..efeacf4 100644 --- a/src/git/merging.md +++ b/src/git/merging.md @@ -3,7 +3,7 @@ Merging is the process of combining two (or more) histories together. The commits of the branch being merged into another are 'replayed' onto the 'base' branch synchronizing the histories and finally combining the result into a single commit. Merging two branches requires the branches have a common ancestor commit that can be used as the base of the combined histories. To merge branches we use the `merge` command, supplying the name of the branch we want to merge, which will be merged into the the current branch. ```sh -# Merge branch 'feature' into this branch +# Merge branch 'feature' into your current branch git merge feature ``` diff --git a/src/git/rebasing.md b/src/git/rebasing.md index 778f8ad..f759ba6 100644 --- a/src/git/rebasing.md +++ b/src/git/rebasing.md @@ -1,13 +1,13 @@ # Rebasing -Rebasing is a powerful feature of Git that allows you to rewrite the history of a branch. When you branch, the commit and branch from which you branched from becomes the base of *your* branch's history. However, if changes are made to the base branch then your branch and the base branch are said to have divergent histories. If you want to integrate the changes from the base into your branch you have two options: +Rebasing is a powerful feature of Git that allows you to rewrite the history of a branch. When you branch, the commit and branch from which you branched from becomes the base of _your_ branch's history. However, if changes are made to the base branch then your branch and the base branch are said to have divergent histories. If you want to integrate the changes from the base into your branch you have two options: 1. Merge the changes into your branch 2. Rebase your branch -Merging is the simplest and most obvious solutions. it involves simply pulling the changes from the base branch back into your branch as an new merge commit, tieing the histories together. This is often what you will want to do but it cna clutter the history of your branch if the base branch is very active as you will often have to merge the base back into your branch. +Merging is the simplest and most obvious solution. It involves simply pulling the changes from the base branch back into your branch as a new merge commit, tying the histories together. This is often what you will want to do but it can clutter the history of your branch if the base branch is very active as you will often have to merge the base back into your branch. -Rebasing, as the name suggests allows you to rip up the base of your branch and root it to the `HEAD` of the same or even another branch. This allows you to take the changes and apply them into the **history** of your branch. +Rebasing, as the name suggests allows you to rip up the base of your branch and root it to the `HEAD` of the same branch or even another branch. This allows you to take the changes on these branches and apply them into the **history** of your branch. ```sh git rebase @@ -15,7 +15,7 @@ git rebase ## Interactive Rebasing -Git also offers interactive rebasing which allows you to control exactly how the history is rewritten for the branch. This feature can be enhanced by IDE (Integrated Developer Environments) allowing you to effectively rewrite your progress as you go. +Git also offers interactive rebasing which allows you to control exactly how the history is rewritten for the branch. This feature can be enhanced by IDEs (Integrated Developer Environments), allowing you to effectively rewrite your progress as you go. ```sh git rebase -i @@ -23,4 +23,4 @@ git rebase -i ## When not to rebase -Rebasing is powerful but can make it difficult to track when upstream/divergent changes are integrated into a branch. In general it is best to ***not*** rebase when the branch is public (ie. rebase `main` onto a feature for... whatever reason) especially if the branch has an upstream remote as this will create divergent histories between your local rebased branch and the remote which can be extremely difficult to fix and track. +Rebasing is powerful but can make it difficult to track when upstream/divergent changes are integrated into a branch. In general it is best to **_not_** rebase when the branch is public (ie. rebase `main` onto a feature for... whatever reason) especially if the branch has an upstream remote as this will create divergent histories between your local rebased branch and the remote which can be extremely difficult to fix and track. diff --git a/src/github/collaboration.md b/src/github/collaboration.md index f3f2b94..616427a 100644 --- a/src/github/collaboration.md +++ b/src/github/collaboration.md @@ -4,43 +4,43 @@ While GitHub can simply be used as a remote host for repos, allowing you to push ## GitHub flavoured Markdown -A large proportion of text written on GitHub is written in Markdown (like this books source). Markdown is a markup language which can be used to describe the format and structure of written text, similar to HTML or LaTeX. There are many variations of Markdown which add various functionality to the language. GitHub uses its own version which extends the capabilities expressed in the CommonMark (standard) Markdown specification. +A large proportion of text written on GitHub is written in Markdown (like this book's source). Markdown is a markup language which can be used to describe the format and structure of written text, similar to HTML or LaTeX. There are many variations of Markdown which add various functionality to the language. GitHub uses its own version which extends the capabilities expressed in the CommonMark (standard) Markdown specification. - [CommonMark](https://commonmark.org/) - [Markdown Basic Syntax Guide](https://www.markdownguide.org/basic-syntax/) - [Markdown Extended Syntax Guide](https://www.markdownguide.org/extended-syntax/) - [GitHub Flavoured Markdown (GFM) Specification](https://github.github.com/gfm/) -GitHub's extensions to Markdown include some common extensions found across many Markdown parsers including support for Strikethrough text, tables and task list items (checklist). These allow you to express more complex structures with Markdown however are not that interesting and specific to GitHub. You can see the syntax for most of Markdown in the second and third links above including these common extensions. +GitHub's extensions to Markdown include some common extensions found across many Markdown parsers including support for Strikethrough text, tables and task list items (checklist). These allow you to express more complex structures with Markdown, however, are not that interesting and specific to GitHub. You can see the syntax for most of Markdown in the second and third links above including these common extensions. -More interesting are the collaboration based extensions to Markdown that are specific to GitHub. Within any Markdown text on GitHub you are able to link and refer to Issues, discussions, Pull Requests (PR), commits, people and even organisation teams from any repo/org. This is done by using the characters `#` and `@` as prefixes. +More interesting are the collaboration-based extensions to Markdown that are specific to GitHub. Within any Markdown text on GitHub, you are able to link and refer to Issues, discussions, Pull Requests (PR), commits, people and even organisation teams from any repo/org. This is done by using the characters `#` and `@` as prefixes. ### Prefix - `#` -You may notice that Issues, PRs and discussions have an associated #-number. This is used to reference the item within other items of the same or other repos. The `#` prefix can be used to create a link to the item in the Markdown of the current item. The Markdown editors on GitHub will even render a scrollable UI component you can use to search by name for the item you want to link when you type start typing `#`. You can even reference items from different repos (as long as they are public) by prefixing the `#` with the name of the owner (GitHub username) and the repos name eg. `MonashDeepNeuron\HPC-Training#1`. You can also create a pretty link if you put the link somewhere in a list item. +You may notice that Issues, PRs and discussions have an associated #-number. This is used to reference the item within other items of the same or other repos. The `#` prefix can be used to create a link to the item in the Markdown of the current item. The Markdown editors on GitHub will even render a scrollable UI component you can use to search by name for the item you want to link when you start typing `#`. You can even reference items from different repos (as long as they are public) by prefixing the `#` with the name of the owner (GitHub username) and the repos name eg. `MonashDeepNeuron\HPC-Training#1`. You can also create a pretty link if you put the link somewhere in a list item. ### Prefix - `@` -Like many social media platforms, the `@` prefix is used to mention users and teams with a users handle being their username. Like `#`, typing `@` will bring up a list of users and teams you can mention, autocompleting the text if you select an option manually. Teams from organisation are prefixed with the orgs name (like cross repo item links) followed by the team name. eg. The Monash DeepNeuron GitHub organisation has a GitHub team called 'HPC Training' which can be mentioned like so `@MonashDeepNeuron/hpc-training`. Mentioning a GitHub team notify the whole team. You can also use the `@` prefix to link specific commits however, no matter which repo it is from you must prefix the whole thing with the repo owner and name eg. `MonashDeepNeuron/HPC-Training@767c7f0`. +Like many social media platforms, the `@` prefix is used to mention users and teams with a user's handle being their username. Like `#`, typing `@` will bring up a list of users and teams you can mention, auto-completing the text if you select an option manually. Teams from organisations are prefixed with the orgs name (like cross repo item links) followed by the team name. For example, the Monash DeepNeuron GitHub organisation has a GitHub team called 'HPC Training' which can be mentioned like so `@MonashDeepNeuron/hpc-training`. Mentioning a GitHub team notifies the whole team. You can also use the `@` prefix to link specific commits, however, no matter which repo it is from, you must prefix the whole thing with the repo owner and name eg. `MonashDeepNeuron/HPC-Training@767c7f0`. -> Note: Team names can have spaces but in links the spaces are replaced with dashes/hyphens (`-`). +> Note: Team names can have spaces, but in links the spaces are replaced with dashes/hyphens (`-`). ## Collaboration Guidelines and Documents -Within a repo there are often many common documents that are used to describe the collaboration process and guidelines for an OSS. These documents are used to outline the behaviour expected by contributors, how to make contributions, often the codes styling guidelines etc.. Here are some common documents you may find in a repo and the overarching purpose they serve to contributors and users. +Within a repo, there are often many common documents that are used to describe the collaboration process and guidelines for an OSS. These documents are used to outline the behaviour expected by contributors, how to make contributions, code styling guidelines etc.. Here are some common documents you may find in a repo and the overarching purpose they serve to contributors and users. > Note: > -> - Really any kind of file can be used to store this as long as the text is accessible by users and contributors so often plain text files (`*.txt`) or Markdown files (`*.md`) are used. Markdown is often favoured as it has better facilities to describes the structure of the document and can then be rendered on GitHub or externally. -> - It is a convention that this contributor documentation files be capitialised however, it is not required. -> - None of these documents are strictly necessary for a repo to function however, they can make it easier for peopel to start contributing to one. +> - Any kind of file can be used to store this as long as the text is accessible by users and contributors, so often plain text files (`*.txt`) or Markdown files (`*.md`) are used. Markdown is often favoured as it has better facilities to describe the structure of the document and can then be rendered on GitHub or externally. +> - It is a convention that this contributor documentation file be capitialised, however, it is not required. +> - None of these documents are strictly necessary for a repo to function, however, they can make it easier for people to start contributing to one. - README - This is the front page of your codebase. Often containing a summary of the project, a 'quickstart' tutorial and may some examples (all optional). - CONTRIBUTING - Describes the steps potential contributors should take to make contributions to the project. - CODE_OF_CONDUCT - The expected behaviour of contributors when interacting with each other and users. - GUIDELINES - Similar and like a combination of the CODE_OF_CONDUCT and the CONTRIBUTING documents. -- LICENSE - Details the license the code operate under and -- INSTALL - Instructions on how to install, setup and use a project either for development or end-user usage. -- CITATION - If your work is academic in nature you can use this file to hold the appropriate citation so users of the project or people that took inspiration of the project can properly cite your work (often uses the `*.cff` extension). +- LICENSE - Details the license the code operate under +- INSTALL - Instructions on how to install, setup and use a project, either for development or end-user usage. +- CITATION - If your work is academic in nature you can use this file to hold the appropriate citation so users of the project or people who took inspiration from the project can properly cite your work (often uses the `*.cff` extension). - ACKNOWLEDGMENTS / AUTHORS - A file listing the contributors, authors, co-authors, owners and/or co-owners of a repository. Can also be used to pay tribute to people who've helped with the project, particularly if the contributions were indirect or undocumented (advice etc.). - CHANGELOG - Used to describe the changes between one version to another. Many of these files could be littered throughout your project if it has many independent parts or has had a long lifetime. diff --git a/src/github/create-cloning-upload.md b/src/github/create-cloning-upload.md index fb19b72..616d77a 100644 --- a/src/github/create-cloning-upload.md +++ b/src/github/create-cloning-upload.md @@ -1,6 +1,6 @@ # Creating and Cloning a Remote Repository -Creating and cloning a repository on GitHub is super simple. Simply go to [github.com](https://github.com) and click the green 'New' button on the left panel. This will instruct you on how to create a repository. You will have to give your repo a name, possibly a description and attach a software license and `README.md`. Additionally you can have it generate a `.gitignore` for the programming language the source code of the repo will written in to prevent commonly ignore files (eg. executables and binaries) to be committed. This will then generate a very boilerplate repo which you can then clone using the `clone` command via SSH or HTTP. +Creating and cloning a repository on GitHub is super simple. Simply go to [github.com](https://github.com) and click the green 'New' button on the left panel. This will instruct you on how to create a repository. You will have to give your repo a name, a description (optional) and attach a software license and `README.md`. Additionally, you can have it generate a `.gitignore` for the programming language that the source code of the repo will be written in to prevent commonly ignored files (e.g. executables and binaries) from being committed. This will then generate a very boilerplate repo which you can then clone using the `clone` command via SSH or HTTP. ```sh # Clone with SSH diff --git a/src/github/discussions.md b/src/github/discussions.md index 847c0c0..99b8259 100644 --- a/src/github/discussions.md +++ b/src/github/discussions.md @@ -1,7 +1,7 @@ # Discussions -Discussions are places where you can ask questions, share ideas or have general conversations that aren't necessarily Issues. This can be a great place to discuss ideas or get further information on how to use a project or even collaborate on it. It is also beneficial to the maintainers as it can help surface things missing in th projects official documentation. +Discussions are places where you can ask questions, share ideas or have general conversations that aren't necessarily Issues. This can be a great place to discuss ideas or get further information on how to use a project or even collaborate on it. It is also beneficial to the maintainers as it can help surface things missing in the project's official documentation. -Discussions are very much like the Discussion Threads from Issues and PRs. You can comment, react with emojis and even upvote posts and comments. Top level comments are also individual items which can be replied to directly making it easier to focus on sub topics generated by comments. On Q&A discussions you can also mark particular comments as the answer like a mini StackOverflow. +Discussions are very much like the Discussion Threads from Issues and PRs. You can comment, react with emojis and even upvote posts and comments. Top-level comments are also individual items which can be replied to directly making it easier to focus on sub-topics generated by comments. On Q&A discussions you can also mark particular comments as the answer like a mini StackOverflow. -Discussions can also be converted into an Issue making it easier to transfer a conversation that was once a Discussion into an Issue if the discussion resulting in an Issue being found or surfaced a desired feature from the community. +Discussions can also be converted into an Issue making it easier to transfer a conversation that was once a Discussion into an Issue if the discussion resulted in an Issue being found or surfaced a desired feature from the community. diff --git a/src/github/forks.md b/src/github/forks.md index 3f1a92b..425f571 100644 --- a/src/github/forks.md +++ b/src/github/forks.md @@ -1,7 +1,7 @@ # Forks -Forks are a combination of branches and clones of a repo. They allow you to copy a remote repo to another (usually remote) location that is independent of the 'upstream' but still retains a connection to its upstream source. Forks can exist for many reasons. A common one is you wish to extend the functionality of a codebase for your own or your organisations/companies uses. You may also want to make and test an improvement or extension of the codebase and request the changes be integrated into the upstream source for other users to benefit from the change. +Forks are a combination of branches and clones of a repo. They allow you to copy a remote repo to another (usually remote) location that is independent of the 'upstream' but still retains a connection to its upstream source. Forks can exist for many reasons. A common one is you wish to extend the functionality of a codebase for your own or your organisation's/company's uses. You may also want to make and test an improvement or extension of the codebase and request the changes be integrated into the upstream source for other users to benefit from the change. -To fork a repository you can simply clone a repository and rename the remote name from `origin` to `upstream` and setup the repo to track a different remote location as `origin`. This allows you to sync with the `upstream` remote but collaborate at `origin`. Alternatively you can use GitHub and select the fork button on a repos '<> Code' page and have GitHub setup the remote fork for you which can then allow you to simply clone the fork to your local machine to start developing on the fork. +To fork a repository you can simply clone a repository and rename the remote name from `origin` to `upstream` and set the repo to track a different remote location as `origin`. This allows you to sync with the `upstream` remote but collaborate at `origin`. Alternatively, you can use GitHub and select the fork button on a repo's '<> Code' page and have GitHub set up the remote fork for you which can then allow you to simply clone the fork to your local machine to start developing on the fork. -When forking a repository you have to be weary of the software license the original source operates on as this restricts what you are able to do with the forked software and how you are allowed to publish and distribute it. +When forking a repository you have to be wary of the software license the original source operates on as this restricts what you are able to do with the forked software and how you are allowed to publish and distribute it. diff --git a/src/github/github.md b/src/github/github.md index bcf63b1..686ef53 100644 --- a/src/github/github.md +++ b/src/github/github.md @@ -1,9 +1,9 @@ # GitHub -GitHub is a remote Git service. This allows you to store Git repositories online so that individuals and teams can access and work on Git repositories and projects remotely. It offers many features on top of basic version control such as branch, issue and feature tracking, releases, CI/CD pipelines, project management and more. Its predominately used through its website which offers control of these features through a simple GUI. Throughout your time at Monash DeepNeuron, university and probably for the rest of your career (if in a software based role), you will use service like GitHub to help management the development of projects. +GitHub is a remote Git service. This allows you to store Git repositories online so that individuals and teams can access and work on Git repositories and projects remotely. It offers many features on top of basic version control such as branch, issue and feature tracking, releases, CI/CD pipelines, project management and more. It's predominately used through its website which offers control of these features through a simple GUI. Throughout your time at Monash DeepNeuron, university and probably for the rest of your career (if in a software-based role), you will use services like GitHub to help manage the development of projects. Your first task is to sign up for a GitHub account, if you haven't already. I would highly recommend using a personal email address (not a university one) as you will most likely want access to your account after university. [GitHub - Join](https://github.com/join) -It is also a good idea to install the GitHub mobile app. This allows you track and manage projects and reply to messages and Issues from your phone. +It is also a good idea to install the GitHub mobile app. This allows you to track and manage projects and reply to messages and Issues from your phone. diff --git a/src/github/issues.md b/src/github/issues.md index 1604163..eb14a30 100644 --- a/src/github/issues.md +++ b/src/github/issues.md @@ -4,31 +4,31 @@ Issues are a fundamental tool for users and collaborators to express faults in a ## Discussion Thread -Following the original creation of an Issue and its description, collaborators can reply to Issue using the discussion thread. This is a history of all actions and comments made on an Issue and can be used to focus discussions about the Issue at the Issues location. You can also add reactions to an Issues or comment. +Following the original creation of an Issue and its description, collaborators can reply to the Issue using the discussion thread. This is a history of all actions and comments made on an Issue and can be used to focus discussions about the Issue at the Issue's location. You can also add reactions to an Issue or comment. ## Closing an Issue -In the dialog box that is used to craft a comment, there is an option to close the Issues which marks the Issue as resolved or alternatively, you can close an Issue as "Won't Fix" meaning the Issue will not be resolved or considered. You can also reopen the Issue if it persists or becomes an Issue again. +In the dialog box that is used to craft a comment, there is an option to close the Issue which marks the Issue as resolved or alternatively, you can close an Issue as "Won't Fix" meaning the Issue will not be resolved or considered. You can also reopen the Issue if it persists or becomes an Issue again. ## Todos -Using a Markdown checklist in the description of an Issue will at a todo meter and item count to the top of the Issues page as well as to the Issues row on the 'Issues' tab. List can be treated like a regular todo/checklist list for anything that needs to be down to complete the Issue where you can tick/untick items as you go and it will be reflected in the UI. +Using a Markdown checklist in the description of an Issue will add a todo meter and item count to the top of the Issue's page as well as to the Issues row on the 'Issues' tab. List can be treated like a regular todo/checklist list for anything that needs to be done to complete the Issue where you can tick/untick items as you go and it will be reflected in the UI. ## Assignees -Assignees allow you to add a person you want to work on a particular Issue. You can assign individual users or teams if within an organisation. +Assignees allow you to add a person you want to work on a particular Issue. You can assign individual users or teams within an organisation. ## Labels -Labels are descriptor tags that can make it easier to categories Issues which can make it easier to find or group common Issues together. +Labels are descriptor tags that can make it easier to categorise Issues, allowing us to find or group common Issues together. ## Projects -This section allows you to add your Issue to a project board and have it tracked by GitHub automatically allowing better integration between a repos Issues and the general management of the team or organisation. +This section allows you to add your Issue to a project board and have it tracked by GitHub automatically allowing for better integration between a repo's Issues and the general management of the team or organisation. ## Milestones -You can make an Issue a part of a milestones progress. +You can make an Issue a part of a milestone's progress. ## Development @@ -48,7 +48,7 @@ Lock the conversation from further modifications (usually for archival purposes) ## Pin Issues -Pin the Issue on the repos main 'Issues' tab putting it at the forefront of all collaborators view. +Pin the Issue on the repos main 'Issues' tab putting it at the forefront of all collaborators' view. ## Convert to Discussion diff --git a/src/github/licenses-oss.md b/src/github/licenses-oss.md index 443f36b..5e3c6bc 100644 --- a/src/github/licenses-oss.md +++ b/src/github/licenses-oss.md @@ -1,16 +1,16 @@ # Licensing and OSS -When developing any software, the code and resulting binaries that you distribute will have to have some software license governing how the software can be used and redistributed. This is especially important for OSS as your source code, not just built binaries are available for all to see and use and being able to control how it is used and limit the amount of liability you hold as the creator from other peoples/companies/organisations use can become very important. +When developing any software, the code and resulting binaries that you distribute will have to have some software license governing how the software can be used and redistributed. This is especially important for OSS as your source code, not just built binaries, are available for all to see and use. Being able to control how your source code is used, and being able to limit the amount of liability you hold as the creator from other peoples'/companies'/organisations' use of your software can become very important. -There are many existing OSS licenses, each with their own benefits, downfalls and use cases. Each allow for the software licensed under them to be used for different things and can also control how derivative work can be distributed and used. Here are a few of the most common OSS license with links to copies of them. +There are many existing OSS licenses, each with their own benefits, downfalls and use cases. Each allows for the software licensed under them to be used for different things and can also control how derivative work can be distributed and used. Here are a few of the most common OSS licenses with links to copies of them. -- [AGPL-3.0](licenses/AGPL-3.0) - GNU Affero General Public License, a free copy left license similar to GPL-3.0 but has an addition term to allow users who interact with the licensed software over a network to receive the source for that program. -- [Apache-2.0](licenses/Apache-2.0) - A copyright license allow anyone modify the original source as long as the source retains its original Apache-2.0 license and as the modifications are listed in the distribution of the modified source. Authors of Apache-2.0 licensed source cannot be help liable under this license. -- [BSD-3-Clause](licenses/BSD-3-Clause) - Simple copyright license allow anyone to do whatever they want with BSD 3-Clause license software as long as the software retains it original BSD 3-Clause license. It also states that contributors of the original source cannot be used to endorse derivative works without explicit prior permission. -- [BSL-1.0](licenses/BSL-1.0) - Simple copyright license allow anyone to do whatever they want with BSL-1.0 license software as long as the software retains it original BSL-1.0 license unless distributed as a compiled binary. -- [GPL-2.0](licenses/GPL-2.0) - GNU General Public License Version 2, a free copy left license. -- [GPL-3.0](licenses/GPL-3.0) - GNU General Public License Version 3, a free copy left license similar to GPL-2.0 but with stricter copyleft requirements. -- [LGPL-3.0](licenses/LGPL-3.0) - GNU Lesser General Public License Version 3, a free copy left license similar to GPL-3.0 but LGPL-3.0 software is able to be used and modified with non-GPL-3.0 license source as longe as th originally LGPL-3.0 licensed source retains its original license and the LGPL-3.0 source cna be replaced with other source with no effect on the end users usage of the compiled program. -- [MIT](licenses/MIT) - Simple copyright license allow anyone to do whatever they want with MIT license software as long as the software retains it original MIT license. Authors of MIT licensed source cannot be help liable under this license. -- [MPL-2.0](licenses/MPL-2.0) - Mozilla Public License Version 2.0, is a middle ground license that aims to balance the benefits of permissive licenses like MIT and copyleft licenses like GPL-3.0. +- [AGPL-3.0](licenses/AGPL-3.0) - GNU Affero General Public License, a free copyleft license similar to GPL-3.0 but has an additional term to allow users who interact with the licensed software over a network to receive the source for that program. +- [Apache-2.0](licenses/Apache-2.0) - This copyright license allows anyone modify the original source as long as the source retains its original Apache-2.0 license and the modifications are listed in the distribution of the modified source. Authors of Apache-2.0 licensed source cannot be held liable under this license. +- [BSD-3-Clause](licenses/BSD-3-Clause) - Simple copyright license that allows anyone to do whatever they want with BSD 3-Clause license software as long as the software retains its original BSD 3-Clause license. It also states that contributors of the original source cannot be used to endorse derivative works without explicit prior permission. +- [BSL-1.0](licenses/BSL-1.0) - Simple copyright license that allows anyone to do whatever they want with BSL-1.0 license software as long as the software retains it original BSL-1.0 license unless distributed as a compiled binary. +- [GPL-2.0](licenses/GPL-2.0) - GNU General Public License Version 2, a free copyleft license. +- [GPL-3.0](licenses/GPL-3.0) - GNU General Public License Version 3, a free copyleft license similar to GPL-2.0 but with stricter copyleft requirements. +- [LGPL-3.0](licenses/LGPL-3.0) - GNU Lesser General Public License Version 3, a free copyleft license similar to GPL-3.0 but LGPL-3.0 software is able to be used and modified with non-GPL-3.0 license source as long as th originally LGPL-3.0 licensed source retains its original license and the LGPL-3.0 source can be replaced with other sources with no effect on the end users usage of the compiled program. +- [MIT](licenses/MIT) - Simple copyright license allow anyone to do whatever they want with MIT license software as long as the software retains its original MIT license. Authors of MIT-licensed source cannot be held liable under this license. +- [MPL-2.0](licenses/MPL-2.0) - Mozilla Public License Version 2.0, is a middle-ground license that aims to balance the benefits of permissive licenses like MIT and copyleft licenses like GPL-3.0. - [Unlicense](licenses/Unlicense) - A license that releases the software into the public domain. diff --git a/src/github/milestones.md b/src/github/milestones.md index 7b08fb3..3def791 100644 --- a/src/github/milestones.md +++ b/src/github/milestones.md @@ -1,3 +1,3 @@ # Milestones -Milestones are a easy progression trackers that can be used to, well mark important Milestones for a project and link this progress to the resolution of Issues or merging of PRs. Milestones also have an end date associated with them to help keep you on track. To create a Milestone, go to either the 'Issues' or 'Pull requests' tab of the repo and to the top right of the list views you will see a button called 'Milestones'. From this page you can create a Milestone. Issues and PRs are added to the Milestone from the page of the particular time you want to add. Milestones are good for tracking large goals that span many Issues and PRs. You must go back to the Milestones page and close it manually to meat the Milestones deadline. +Milestones are progression trackers that can be used to, well, mark important Milestones for a project and link this progress to the resolution of Issues or merging of PRs. Milestones also have an end date associated with them to help keep you on track. To create a Milestone, go to either the 'Issues' or 'Pull requests' tab of the repo and to the top right of the list views you will see a button called 'Milestones'. From this page, you can create a Milestone. Issues and PRs are added to the Milestone from the page of the particular time you want to add. Milestones are good for tracking large goals that span many Issues and PRs. You must go back to the Milestones page and close it manually to meet the Milestones deadline. diff --git a/src/github/pr.md b/src/github/pr.md index 6b05e3d..b6c87f9 100644 --- a/src/github/pr.md +++ b/src/github/pr.md @@ -1,16 +1,16 @@ # Pull Requests -Pull Requests (PRs) are request from collaborators to pull in their new changes from a feature branch into one of the main development, testing or deployment branches. This allows the maintainers of a project to more carefully view the changes made and consider how they want the changes to be integrated. Maintainers and reviewers can also request the contributor to make changes to their contribution to make it fit better with the existing codebase. PRs are essential to quality assurance (QA) and that breaking changes are not introduced to a codebase unless explicitly allowed. A PR is really just a call to `git merge` with extra steps and oversight of the merge although a squash merge or rebase can be chosen instead. PRs can also be created as drafts, allowing you to continue to commit changes to the incoming branch without the risk of maintainers or other contributors completing the PR before it is ready. +Pull Requests (PRs) are requests from collaborators to pull in their new changes from a feature branch into one of the main development, testing or deployment branches. This allows the maintainers of a project to more carefully view the changes made and consider how they want the changes to be integrated. Maintainers and reviewers can also request the contributor to make changes to their contribution to make it fit better with the existing codebase. PRs are essential to quality assurance (QA) and ensuring that breaking changes are not introduced to a codebase unless explicitly allowed. A PR is essentially just a call to `git merge` with extra steps and oversight of the merge although a squash merge or rebase can be chosen instead. PRs can also be created as drafts, allowing you to continue to commit changes to the incoming branch without the risk of maintainers or other contributors completing the PR before it is ready. > Note: A squash merge will combine the history of all commits on the incoming branch into a single commit that is then added to the base branch. ## Discussion Thread -Just like Issues, PRs also have a discussion thread that allow conversations about the PR to be in the same place as the PR. +Just like Issues, PRs also have a discussion thread that allows conversations about the PR to be in the same place as the PR. ## Closing a PR -Again, like Issues you can close a PR meaning it cannot be merged without reopening the PR. +Again, like Issues, you can close a PR meaning it cannot be merged without reopening the PR. ## Reviewers @@ -22,15 +22,15 @@ Assignees allow you to add a person you want to work on merging a particular PR. ## Labels -Labels are descriptor tags that can make it easier to categories PRs which can make it easier to find or group common PRs together. +Labels are descriptor tags that can make it easier to categorise PRs which can make it easier to find or group common PRs together. ## Projects -This section allows you to add your PR to a project board and have it tracked by GitHub automatically allowing better integration between a repos PRs and the general management of the team or organisation. +This section allows you to add your PR to a project board and have it tracked by GitHub automatically allowing better integration between a repo's PRs and the general management of the team or organisation. ## Milestones -You can make an PR a part of a milestones progress. +You can make a PR a part of a milestone's progress. ## Development @@ -42,7 +42,7 @@ Change your notification settings for the PR. ## Participants -View who is/has been involved in an PR. +View who is/has been involved in a PR. ## Lock conversations diff --git a/src/github/push-pull-fetch.md b/src/github/push-pull-fetch.md index 2abaa11..119506f 100644 --- a/src/github/push-pull-fetch.md +++ b/src/github/push-pull-fetch.md @@ -1,10 +1,10 @@ # Push, Pull, Fetch -When interacting with remote repos, there are three key operations you will perform frequently. These are pushing your local changes to a remote, pulling and integrating new changes from a remote and fetching the metadata of available changes. All these changes +When interacting with remote repos, there are three key operations you will perform frequently. These are pushing your local changes to a remote repo, pulling and integrating new changes from a remote into your local repo and fetching the metadata of available changes. ## Push -Pushing is the process of uploading our local changes to a remote location. You can also use the `-u` flag to setup a new remote reference if the local branch does not exist on the remote yet. +Pushing is the process of uploading our local changes to a remote location. You can also use the `-u` flag to set up a new remote reference if the local branch does not exist on the remote yet. ```sh git push @@ -21,7 +21,7 @@ git pull ## Fetch -Fetching is a very powerful tool. It allows us to pull the updated refs from a remote location with integrating the changes meaning we can view what has changed before our local history is fast-forwarded or merged with the corresponding remote branch. +Fetching is a very powerful tool. It allows us to pull the updated refs from a remote location without integrating the changes into your local repo meaning that we can view what has changed before our local history is fast-forwarded or merged with the corresponding remote branch. ```sh git fetch diff --git a/src/github/releases.md b/src/github/releases.md index 3f0b8de..09dfaaa 100644 --- a/src/github/releases.md +++ b/src/github/releases.md @@ -1,3 +1,3 @@ # Tags and Releases -We saw Git chapter tags and how they can be used to create named commit points, often for marking versions of the codebase. GitHub takes this to the next step by allowing you to use tags to create GitHub releases where you can store your packaged versions of the codebase and share what has changed to your users. It can even generate crude changelogs for you based on commit message (a good reason to create good commit messages). +We saw Git chapter tags and how they can be used to create named commit points, often for marking versions of the codebase. GitHub takes this to the next step by allowing you to use tags to create GitHub releases where you can store your packaged versions of the codebase and share what has changed with your users. It can even generate crude changelogs for you based on you commit message (a good reason to create good commit messages). diff --git a/src/github/setup.md b/src/github/setup.md index 40dadd0..622b180 100644 --- a/src/github/setup.md +++ b/src/github/setup.md @@ -1,9 +1,9 @@ # Setup -Once you have a GitHub account setup, it is a good idea to link it with you local Git configuration for your system. Open a new shell and run the following commands, filling in your own details. +Once you have a GitHub account setup, it is a good idea to link it with your local Git configuration for your system. Open a new shell and run the following commands, filling in your details. ```sh -# Set the name that is identifiable for credit when review version history +# Set the name that is identifiable for credit when reviewing version history git config --global user.name "github-username" # Set an Email address that will be associated with each history marker @@ -15,13 +15,13 @@ git config --global color.ui auto ## GitHub Personal Access Tokens -To access private repos from GitHub you will need to either setup SSH ([below](#ssh--git)) or generate a personal access token to use as a password for HTTP login. Follow [this](https://github.com/settings/tokens) link and click the 'Generate new token' (select the 'classic' token option). Tick every box and name the token something like 'Full Access Token'. This will act as a universal password for accessing your GitHub recourses. Make sure to also set it to have now expiration date so it never becomes invalid. Once you generate the token make sure to copy and store it in a secure location as you will never be able to after this. +To access private repos from GitHub you will need to either set up SSH ([below](#ssh--git)) or generate a personal access token to use as a password for HTTP login. Follow [this](https://github.com/settings/tokens) link and click the 'Generate new token' (select the 'classic' token option). Tick every box and name the token something like 'Full Access Token'. This will act as a universal password for accessing your GitHub recourses. Make sure to also set it to have no expiration date so it never becomes invalid. Once you generate the token make sure to copy and store it in a secure location as you will never be able to after this. -> Note: It should be noted that this is not a best practice as losing this token or leaking will completely expose your account. This is method for convenience not safety. You should read the options and tick only whats necessary for a token to control in future. +> Note: It should be noted that this is not a best practice as losing this token or leaking it will completely expose your account. This is a method for convenience not safety. You should read the options and tick only what's necessary for a token to control in future. ## SSH + Git -Typically you can just use the HTTP protocol to clone or upload repos however this is not as secure and cloning private repos requires a Personal Access Token. Using SSH is generally far more secure and far more convenient. First we must install OpenSSH however, this is different for every platform. +Typically you can just use the HTTP protocol to clone or upload repos, however, this is not as secure as using SSH and cloning private repos requires a Personal Access Token. Using SSH is generally far more secure and far more convenient. To do this, we must first install OpenSSH, the process of which can be different for every platform. ### Install OpenSSH @@ -83,4 +83,4 @@ You will then need to copy the public key to your clipboard. You can print the k cat ~/.ssh/id_ed25519.pub ``` -Then, go to your GitHub account, go to settings, and click on the SSH and GPG keys tab (or click [this](https://github.com/settings/keys) link). Click on New SSH key, and paste the key into the box. Give it a name, and click Add SSH key. You should now be able to clone repos using SSH. To do this, go to the repo you want to clone, but instead of copying the HTTP link, copy the SSH link, and then its regular Git cloning. +Then, go to your GitHub account, go to settings, and click on the SSH and GPG keys tab (or click [this](https://github.com/settings/keys) link). Click on "New SSH key", and paste the key into the box. Give it a name, and click "Add SSH key". You should now be able to clone repos using SSH. To do this, go to the repo you want to clone, but instead of copying the HTTP link, copy the SSH link, and then its regular Git cloning. diff --git a/src/github/workflow.md b/src/github/workflow.md index cf27104..fd03603 100644 --- a/src/github/workflow.md +++ b/src/github/workflow.md @@ -1,27 +1,27 @@ # Workflow -In this page we are going to explore a potential workflow you can use with Git and GitHub when collaborating with multiple people. No it doesn't have a name, I'm not a marketing guy and it doesn't need one. The focus of this workflow is to allow as-easy-as-possible integration of many different features without breaking the entire system and its deployment by funneling changes down from feature (or patch) branches into staging branches and finally into the main deployment branch. +In this page, we are going to explore a potential workflow you can use with Git and GitHub when collaborating with multiple people. No, it doesn't have a name, I'm not a marketing guy and it doesn't need one. The focus of this workflow is to allow as-easy-as-possible integration of many different features without breaking the entire system and its deployment by funneling changes down from feature (or patch) branches into staging branches and finally into the main deployment branch. ## Main Deployment Branch -In essence you have a single branch that is used as as the deployment branch. You can of course call ths whatever you want but we'll assume this is the `main` branch. From the `main` you make deployments and use tags to mark releases. +In essence, you have a single branch that is used as the deployment branch. You can of course call this whatever you want but we'll assume this is the `main` branch. From the `main` you make deployments and use tags to mark releases. ## Development and Staging Branches -You also have a mirroring branch that acts as the source of both new feature branches and the staging area to ensure integrating multiple features do not break each others new functionality or existing functionality. I typically call this `dev` but again, you are free to call it whatever you want. You can also have multiple staging levels if you want more rigorous filtering down of features. The `dev` branch is to be kept up to date with `main`. This should be easy to maintain if you only pull `dev` changes into `main` and don't update `main` directly but you can pull `main` back into `dev` if need be. +You also have a mirroring branch that acts as the source of both new feature branches and the staging area to ensure integrating multiple features does not break each other's new functionality or existing functionality. I typically call this `dev` but again, you are free to call it whatever you want. You can also have multiple staging levels if you want more rigorous filtering down of features. The `dev` branch is to be kept up to date with `main`. This should be easy to maintain if you only pull `dev` changes into `main` and don't update `main` directly but you can pull `main` back into `dev` if need be. ## Creating Feature Branches -From the `HEAD` of `dev` new branches are created for feature development. This will ensure that if a separate but new feature is created and pulled into `dev` your new feature can benefit or not have issues later on merging the two histories together. If need be features can obviously be created from any point in `dev` history if you do not want to include branch-base staged changes. When a feature is based off an Issue use the GitHub 'Create branch from Issue'. Ensure to change the base branch to the `dev` branch. You can name these branches whatever you want but the GitHub generated one is good enough. +From the `HEAD` of `dev` new branches are created for feature development. This will ensure that if a separate but new feature is created and pulled into `dev` your new feature can benefit or not have issues later on merging the two histories together. If need be features can be created from any point in the `dev` history if you do not want to include branch-based staged changes. When a feature is based on an Issue use the GitHub 'Create branch from Issue'. Ensure to change the base branch to the `dev` branch. You can name these branches whatever you want but the GitHub generated one is good enough. ## Merging Features to Development or Staging Branches -When a feature is ready to be integrated, create a PR from the feature branch into the `dev` branch (or appropriately levelled staging branch if applicable) and request reviews from the relevant people/maintainers. If you are not a maintainer then the reviews/maintainers will do the rest and should keep you updated on the PR's progress and may request clarification or revisions to make the changes fit into the existing/upcoming codebase. In the PR's description it is good to include a brief description/list of the changes you have made as well as link and related Issues, PR's, external resources or anything else relevant to the PR however, consult the CONTRIBUTING, CODE_OF_CONDUCT and GUIDELINES files for the repo to ensure you adhere to the specific repos contributing policies as every repo can be different, even if managed by the same people, company and/or organisation. +When a feature is ready to be integrated, create a PR from the feature branch into the `dev` branch (or appropriately levelled staging branch if applicable) and request reviews from the relevant people/maintainers. If you are not a maintainer then the reviews/maintainers will do the rest and should keep you updated on the PR's progress and may request clarification or revisions to make the changes fit into the existing/upcoming codebase. In the PR's description it is good to include a brief description/list of the changes you have made as well as link and related Issues, PRs, external resources or anything else relevant to the PR however, consult the CONTRIBUTING, CODE_OF_CONDUCT and GUIDELINES files for the repo to ensure you adhere to the specific repos contributing policies as every repo can be different, even if managed by the same people, company and/or organisation. ## Merging Development or Staging Branches into the Main Deployment Branch -If you are a maintainer of a repo you may have to setup a PR for merging upcoming changes into the `main` branch. If you are maintaining a bigger project then coordinating with other maintainers and contributors about which changes you want to integrate into each release can make it easier to create the PRs and stage as many new changes in `dev` that is feasible so you can thoroughly test how the changes play together. You can make a single release for each PR into `main` or you can do multiple PR's if you have a more structured release schedule. Ensure you also have this PR reviewed by others as it can help catch problems before they hit you main branch. You can also branch the `HEAD` of `main` and merge a test PR into this new branch to do test deployments before pulling `dev` into `main`. +If you are a maintainer of a repo you may have to set up a PR for merging upcoming changes into the `main` branch. If you are maintaining a bigger project then coordinating with other maintainers and contributors about which changes you want to integrate into each release can make it easier to create the PRs and stage as many new changes in `dev` that is feasible so you can thoroughly test how the changes play together. You can make a single release for each PR into `main` or you can do multiple PRs if you have a more structured release schedule. Ensure you also have this PR reviewed by others as it can help catch problems before they hit your main branch. You can also branch the `HEAD` of `main` and merge a test PR into this new branch to do test deployments before pulling `dev` into `main`. ## Notes -This is not a very thorough workflow but is aimed to be as simple as possible while still be effective for teams to collaborate together. This workflow does not govern coding practices, commit conventions nor stop bad code from entering a codebase but can help setup a skeleton for collaboration between multiple people. Maintainers and collaborators should still make use of the Issues, Discussions, Projects etc. to help coordinate and track problems and changes for a repo. +This is not a very thorough workflow but is aimed to be as simple as possible while still being effective for teams to collaborate together. This workflow does not govern coding practices, commit conventions nor stop bad code from entering a codebase but can help set up a skeleton for collaboration between multiple people. Maintainers and collaborators should still make use of the Issues, Discussions, Projects etc. to help coordinate and track problems and changes for a repo. diff --git a/src/home.md b/src/home.md index 41e82af..0bf965b 100644 --- a/src/home.md +++ b/src/home.md @@ -1,14 +1,14 @@ # Welcome -Welcome to *Git Gud*, an introductory book and reference to using the Git-SCM tool and the GitHub platform. In this book you will learn how to utilise the Git Command Line Interface (CLI) to manage the development, distribution, tracking and versioning of software as well as utilise the online platform GitHub in order to store this information remotely, run Continuous Integration (CI) jobs, contribute to Closed Source and Open Source Software (OSS), integrate your changes into large codebases and publish your own software. +Welcome to _Git Gud_, an introductory book and reference to using the Git-SCM tool and the GitHub platform. In this book, you will learn how to utilise the Git Command Line Interface (CLI) to manage the development, distribution, tracking and versioning of software as well as utilise the online platform GitHub to store this information remotely, run Continuous Integration (CI) jobs, contribute to Closed Source and Open Source Software (OSS), integrate your changes into large codebases and publish your own software. ## How to use this book -Using the book is pretty self explanatory. The content is split up into chapters which covers a particular topic which can be further broken down sections. You navigate through the book mostly chronologically using the arrow buttons on either side of the page (can't miss them). You can also look through the chapters and sections to find particular topics or using the search bar, which can be activated by pressing S. Each chapter has a challenges section. These contain various tasks to complete related to the content of each chapter. +Using the book is pretty self-explanatory. The content is split up into chapters which cover a particular topic which can be further broken down into sections. You navigate through the book mostly chronologically using the arrow buttons on either side of the page (can't miss them). You can also look through the chapters and sections to find particular topics or use the search bar, which can be activated by pressing S. Each chapter has a challenges section. These contain various tasks to complete related to the content of each chapter. ## Contributing -You can contribute to the book by accessing its GitHub repository (GitHub log in the top right hand corner of any page). Follow the contributing guidelines on the repository for more details. +You can contribute to the book by accessing its GitHub repository (GitHub log in the top right-hand corner of any page). Follow the contributing guidelines on the repository for more details. --- diff --git a/src/tlrd.md b/src/tlrd.md index 8cfcbe7..d8cb54c 100644 --- a/src/tlrd.md +++ b/src/tlrd.md @@ -9,7 +9,7 @@ The section of the book is designed to be a quick reference to some of the most ## Setup ```sh -# Set the name that is identifiable for credit when review version history +# Set the name that is identifiable for credit when reviewing version history git config --global user.name "github-username" # Set an Email address that will be associated with each history marker @@ -48,7 +48,7 @@ git diff git diff --staged # Commit staged changes w/ message -git commit -m "Commit Message" +git commit -m "Your commit message" ``` ## Branches @@ -73,13 +73,13 @@ git merge ## Inspecting and Compare ```sh -# Show commits from current branch's history +# Show commits from the current branch's history git log # Show commits on branch-A not on branch-B git log .. -# Show commits that modified file, even across renames +# Show commits that modified a given file, even across renames git log --follow # Show diff of what is in branch-A that is not on branch-B @@ -98,10 +98,10 @@ git remote add # Retrieve changes from remote without integrating changes git fetch -# Fetch and merge changes from remote from the tracked remote branch -git pull +# Fetch and merge changes from a remote branch into your local branch +git pull -# Transmit changes from local branch to remote onto branch +# Transmit changes from local branch into a remote branch git push # Set current branch to track branch at remote @@ -130,7 +130,7 @@ git reset --hard # Save modified and staged changes in stash git stash -# Show all stashes in stack-order +# Show all stashes in stack-order git stash list # Pop stash from top of stash-stack From 4aa76b1f9c574d757e817e2886872e231c390ba7 Mon Sep 17 00:00:00 2001 From: Nyan Kyaw <62088177+NyanKyaw@users.noreply.github.com> Date: Sun, 1 Oct 2023 12:46:14 +1100 Subject: [PATCH 13/14] Update .gitignore Added empty line. --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 8afc88e..87066e1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ book -*.DS_Store \ No newline at end of file +*.DS_Store From 8ef2fbde713af00d234b16cbbbd8836e211c8d6c Mon Sep 17 00:00:00 2001 From: Nyan Kyaw <62088177+NyanKyaw@users.noreply.github.com> Date: Sun, 1 Oct 2023 12:48:15 +1100 Subject: [PATCH 14/14] Update licenses-oss.md Fixing links. --- src/github/licenses-oss.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/github/licenses-oss.md b/src/github/licenses-oss.md index 5e3c6bc..c50fffd 100644 --- a/src/github/licenses-oss.md +++ b/src/github/licenses-oss.md @@ -4,13 +4,13 @@ When developing any software, the code and resulting binaries that you distribut There are many existing OSS licenses, each with their own benefits, downfalls and use cases. Each allows for the software licensed under them to be used for different things and can also control how derivative work can be distributed and used. Here are a few of the most common OSS licenses with links to copies of them. -- [AGPL-3.0](licenses/AGPL-3.0) - GNU Affero General Public License, a free copyleft license similar to GPL-3.0 but has an additional term to allow users who interact with the licensed software over a network to receive the source for that program. -- [Apache-2.0](licenses/Apache-2.0) - This copyright license allows anyone modify the original source as long as the source retains its original Apache-2.0 license and the modifications are listed in the distribution of the modified source. Authors of Apache-2.0 licensed source cannot be held liable under this license. -- [BSD-3-Clause](licenses/BSD-3-Clause) - Simple copyright license that allows anyone to do whatever they want with BSD 3-Clause license software as long as the software retains its original BSD 3-Clause license. It also states that contributors of the original source cannot be used to endorse derivative works without explicit prior permission. -- [BSL-1.0](licenses/BSL-1.0) - Simple copyright license that allows anyone to do whatever they want with BSL-1.0 license software as long as the software retains it original BSL-1.0 license unless distributed as a compiled binary. -- [GPL-2.0](licenses/GPL-2.0) - GNU General Public License Version 2, a free copyleft license. -- [GPL-3.0](licenses/GPL-3.0) - GNU General Public License Version 3, a free copyleft license similar to GPL-2.0 but with stricter copyleft requirements. -- [LGPL-3.0](licenses/LGPL-3.0) - GNU Lesser General Public License Version 3, a free copyleft license similar to GPL-3.0 but LGPL-3.0 software is able to be used and modified with non-GPL-3.0 license source as long as th originally LGPL-3.0 licensed source retains its original license and the LGPL-3.0 source can be replaced with other sources with no effect on the end users usage of the compiled program. -- [MIT](licenses/MIT) - Simple copyright license allow anyone to do whatever they want with MIT license software as long as the software retains its original MIT license. Authors of MIT-licensed source cannot be held liable under this license. -- [MPL-2.0](licenses/MPL-2.0) - Mozilla Public License Version 2.0, is a middle-ground license that aims to balance the benefits of permissive licenses like MIT and copyleft licenses like GPL-3.0. -- [Unlicense](licenses/Unlicense) - A license that releases the software into the public domain. +- [AGPL-3.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/AGPL-3.0) - GNU Affero General Public License, a free copyleft license similar to GPL-3.0 but has an additional term to allow users who interact with the licensed software over a network to receive the source for that program. +- [Apache-2.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/Apache-2.0) - This copyright license allows anyone modify the original source as long as the source retains its original Apache-2.0 license and the modifications are listed in the distribution of the modified source. Authors of Apache-2.0 licensed source cannot be held liable under this license. +- [BSD-3-Clause](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/BSD-3-Clause) - Simple copyright license that allows anyone to do whatever they want with BSD 3-Clause license software as long as the software retains its original BSD 3-Clause license. It also states that contributors of the original source cannot be used to endorse derivative works without explicit prior permission. +- [BSL-1.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/BSL-1.0) - Simple copyright license that allows anyone to do whatever they want with BSL-1.0 license software as long as the software retains it original BSL-1.0 license unless distributed as a compiled binary. +- [GPL-2.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/GPL-2.0) - GNU General Public License Version 2, a free copyleft license. +- [GPL-3.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/GPL-3.0) - GNU General Public License Version 3, a free copyleft license similar to GPL-2.0 but with stricter copyleft requirements. +- [LGPL-3.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/LGPL-3.0) - GNU Lesser General Public License Version 3, a free copyleft license similar to GPL-3.0 but LGPL-3.0 software is able to be used and modified with non-GPL-3.0 license source as long as th originally LGPL-3.0 licensed source retains its original license and the LGPL-3.0 source can be replaced with other sources with no effect on the end users usage of the compiled program. +- [MIT](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/MIT) - Simple copyright license allow anyone to do whatever they want with MIT license software as long as the software retains its original MIT license. Authors of MIT-licensed source cannot be held liable under this license. +- [MPL-2.0](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/MPL-2.0) - Mozilla Public License Version 2.0, is a middle-ground license that aims to balance the benefits of permissive licenses like MIT and copyleft licenses like GPL-3.0. +- [Unlicense](https://github.com/MonashDeepNeuron/Template-Docs/tree/main/licenses/Unlicense) - A license that releases the software into the public domain.