README.md

Learning Git Version Control System

---

Repository for learning git and GitHub collaboratively adapted for SnowEx from the UW Hackweek template.

There are many ways to contribute to a project and two of those are higlighted below. We encourage participants to practice either one during an event and many open source projects have similar guides to contribute.

The two flows are:

• Contributing directly with a branch
• Contributing through a fork

Git workflows

Which one to choose?

The way you can contribute and choose one of the above flows depends on your access privileges to a repository. You can use both flows, if you are part of the organization that owns the repository. This is the case when you participate in the hackweek and we added you to the GitHub organizaion. Once you are not part of the organization or if you want to contribute to a repository that is on someone else's personal account, then you need to use a fork.

Terminology

Before we dive into the workflows, here some essential terms and links to definitions:

• Branch
• Clone
• Fork
• Pull Request or short PR
• Push

Contributing through a fork

An in-depth description for the forking workflow can be found here

Here are the steps using this repository:

1. Fork the repository. This can be done using the top right button on github.com on

   https://github.com/snowex-hackweek/learning-git
   

   

   Choose your user account in the dialog and it will create a fork under your GitHub user account.

2. Go to your user page on github.com, get the URL, and clone the repository locally.

   For this, you can use a button on the GitHub user interface to copy the URL.

   

   The below command has <your-user-name> as a sample placeholder. This should be replaced by your actual GitHub username.

   git clone https://github.com/<your-user-name>/learning-git.git

3. Once inside the newly cloned repository, add SnowEx as the original source for your forked repository

   This is step is considered adding a remote to a repository.

    # Change to the directory
    cd learning-git
    # Add a new remote with the name 'SnowEx' as the original fork source
    git remote add SnowEx https://github.com/snowex-hackweek/learning-git.git

4. Verify that the remote was added successfully

   List all remotes

   git remote -v

   The remote with the name origin is the default chosen name by git when you cloned the repository. This will always point to the URL of the one used in the clone command.

   In our case it is:

   SnowEx	https://github.com/snowex-hackweek/learning-git.git (fetch)
   SnowEx	https://github.com/snowex-hackweek/learning-git.git (push)
   origin	https://github.com/<your-user-name>/learning-git.git (fetch)
   origin	https://github.com/<your-user-name>/learning-git.git (push)

5. Make a new branch

   # The '-b' is indicating a new branch with the name `new_branch`
   # It will also change to that.
   git checkout -b new_branch

   Output:

   Switched to a new branch 'new_branch'

6. Verify you are on the new branch

   # Show all branches of the repository, the current active has the `*`
   git branch

   Output:

   main
   * new_branch

7. Make changes within the new branch

   With this practice repository, you have to create a folder within contributions folder with your GitHub username as the folder name. Use a new markdwon file (.md) or text file (.txt) file to practice git with. No other file types or folders are allowed outside your designated folder with this practice run.

8. Commit the changes

   # Add the new files
   git add .
   # Commit the changes
   git commit -m "My new files"

9. Push the changes to your forked repository

   git push origin new_branch

10. Create a pull request from your new branch

    Go to your user page on github.com. There, you will see a banner to create the pull request.

    

11. Go to the pull request tab on the SnowEx website and celebrate!

     https://github.com/snowex-hackweek/learning-git/pulls

Keeping up to date with changes to the source (origin)

By forking the repository, you created a snapshot at that point in time of the learning-git repository. To get any changes from the SnowEx repository copied into your version, you need to issue a pull command.

Here the steps:

1. Inside your forked repository

   The first command queries for all changes to the main branch on SnowEx. You added the SnowEx remote in step number 3 above.

   git fetch SnowEx

   Sample output:

   remote: Enumerating objects: 1, done.
   remote: Counting objects: 100% (1/1), done.
   remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
   Unpacking objects: 100% (1/1), 623 bytes | 623.00 KiB/s, done.
   From github.com:snowex-hackweek/learning-git
      03a9288..64e856e  main       -> SnowEx/main
   

2. Go back to the main branch in your fork

   git checkout main

3. Transfer all the changes

   This will transfer all the changes since your fork command from the SnowEx main branch to your version of the main branch, making it up to date.

   git pull SnowEx main

   Sample output:

   From github.com:snowex-hackweek/learning-git
   * branch            main       -> FETCH_HEAD
   Successfully mreged and updated refs/heads/main.

Contributing through a branch

The following explains the steps to contribute directly to a repository using a branch.

In a nutshell, here the steps:

1. Clone the repository on your local computer

   ‼️ NOTE This is different from the above as you are cloning the original repository and not your fork.

   Command:

   git clone https://github.com/snowex-hackweek/learning-git

2. Create a branch

   Choose a unique name that is not already taken in the repository and helps other collaborators to identify your work. In this case we are adding a branch with name 'feature_xyz'

   # The '-b' is indicating a new branch with the name `feature_xyz`
   # It will also change to that.
   git co -b feature_xyz

   Sample output:

   Switched to a new branch 'feature_xyz'

3. Verify you are on the new branch

   # Show all branches of the repository, the current active has the `*`
   git branch

   Output:

   main
   * feature_xyz

4. Make changes within the new branch

   With this practice repository, you have to create a folder within contributions folder with your GitHub username as the folder name. Use a new markdwon file (.md) or text file (.txt) file to practice git with. No other file types or folders are allowed outside your designated folder with this practice run.

5. Commit the changes

   # Add the new files
   git add .
   # Commit the changes
   git commit -m "My new files"

6. Push the changes to the GitHub repository

   git push origin feature_xyz

7. Create a pull request from your new branch

   Go to the repository page on github.com. There, you will see a banner to create the pull request.

   

8. Go to the pull request tab and celebrate!

    https://github.com/snowex-hackweek/learning-git/pulls

9. Clean up and delete the branch locally and on the website.

   Once your pull request is merged to the main branch, it is a good practice to delete the created branch. This has to be done in two places, once on the pull request page on github.com and the other on your local repository.

   For github.com, see the official documentation on how to delete a branch after it has been merged. In this practice repository, we have setup a rule that will take care of this step for you.

   Locally, however, you must still do this yourself and here the steps you need to execute within your local repository:

   # Go back to the `main` branch
   git checkout main
   # Get the latest changes that include your pull request
   git pull
   # Delete the branch. Here, our practice run branch `feature_xyz`
   # The -d flag is a safety option that only allows fully merged branches
   # to be deleted.
   git branch -d feature_xyz

Commit messages

Good commit messages for each change helps you and your collaborators. Here a quick read on recommended practices

Resources

• Git cheat sheet