Would you like to see your link here? Contact us

Notesclub

created by hec & contributors

terms privacy

Git

curriculum-main/reading/git.livemd

@hotemetoot

dockyard

More notebooks

Git

Mix.install([
  {:jason, "~> 1.4"},
  {:kino, "~> 0.9", override: true},
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"}
])

Navigation

Home Report An Issue Command Line Livebook

Overview

Version Control

Version control is a system that helps you track changes to your files over time. It allows you to save different versions of your work and collaborate with others efficiently. With version control, you can easily compare, revert, and merge changes, ensuring that you have a history of all modifications made to your project and enabling effective collaboration and backup of your code.

Git

Git is a widely used version control system that helps you keep track of changes made to your files.

GitHub

GitHub is a web-based platform that provides hosting for software development and a community of developers to collaborate and contribute to open-source and closed-source projects. It is built on top of Git and provides a user-friendly interface for developers to manage their code.

GitHub provides several key features for developers, including:

Repositories: Developers can create and host their code in individual “repositories” on GitHub, which can be easily shared and collaborated on with other developers. These repositories can be public or private.
Collaboration: Developers can easily collaborate on code by “forking” a repository, making changes, and then submitting those changes back to the original repository through a “pull request”.
Issues: Developers can track and manage bugs, feature requests, and other tasks by creating “issues” within a repository.
Pull requests (PRs): Developers can submit changes to a repository by creating a “pull request”, which can be reviewed and approved by other members of the development team.
Branching: Developers can create and work on multiple branches of a repository, allowing them to work on different features or bug fixes without affecting the main codebase.
Wiki: Developers can create a wiki for their repository to provide documentation and other information about the codebase.

With Git and GitHub, developers store a local version of their changes with git, and push those changes to a remote version on GitHub.

Install Git

Git is a locally installed program on your computer. Git comes pre-installed on macOS and Linux operating systems. If you use Windows, you’ll have to Install Git.

Enter the following into the command line to confirm you have Git installed. You should see a similar output, but likely with a different git version.

$ git --version
git version 2.25.1

For sake of consistency with reading material and instruction in this course, we recommend using the command line for Git instead of a program such as GitHub Desktop.

Your Turn: Create A GitHub Account

Create a GitHub Account if you have not already. You may also wish to setup Setup SSH or some alternative authorization method so that you do not have to enter your credentials every time you interact with GitHub.

Raising An Issue

Anyone can raise an issue on a public GitHub project. For example, you can raise an issue by going to the issues tab on the GitHub Page of this curriculum and clicking New Issue.

Please raise an issue or speak with your instructor if you encounter a problem with the curriculum.

Initializing A Local Repository

Git uses a .git folder that stores the necessary folders and files to manage the project’s source control. We call this git-managed folder a repository.

Using the command line, you can initialize Git in your current working directory by running:

$ git init

CAUTION: DO NOT INITIALIZE GIT UNLESS YOU WANT THAT FOLDER TO BE A GIT REPOSITORY.

WARNING: USUALLY YOU SHOULD NOT NEST GIT REPOSITORIES.

Your Turn

Use the command line to create a new Git managed project called git_example.

You can use git status from the command line from the git_example folder to verify that Git manages the folder. Like so:

$ git init
Initialized empty Git repository in ~/github_example/.git/
$ git status
On branch master

No commits yet

nothing to commit (create/copy files and use "git add" to track)

Staging And Committing Changes

Git allows you to save your changes in a commit. Changes go from untracked to staged to committed.

flowchart LR
  Untracked --git add--> Staged --git commit--> Committed

You’ll use some common commands for saving changes in Git.

git status: Display Git information and see the untracked and staged changes.
git add: Stage current changes.
git commit: Save staged changes into a commit.

Putting that all together looks like this if run from the project folder. The git status commands are optional.

$ git status
$ git add .
$ git status
$ git commit -m "example commit message"
$ git status

Your Turn

You’re going to stage and commit some changes in the github_example project.

In the github_example create an empty file named finished.txt.

Use git add, and git commit to stage and commit the file. Make sure to check the status between each step with git status to see how staged and unstaged files are displayed in the terminal.

Cloning Repositories

You can clone remote repositories to create a local Git project on your computer.

flowchart LR
Remote --git clone--> Local

There are many methods for cloning a remote repository onto your computer.

Cloning With The Command Line

Many developers prefer using the command line using either HTTP, SSH, or the GitHub CLI.

You can find instructions for each method on GitHub:

HTTPS

HTTPS (Hypertext Transfer Protocol Secure) is a method of transferring data. In this case, we use it to copy files from the GitHub remote repository onto our local computer.

More practically, it’s the easiest method for the command line however the downside is it’s less secure and requires you to enter your GitHub credentials every time you use a git command.

We use git clone with the URL provided by GitHub to clone the repo with HTTPS.

$ git clone https://github.com/BrooklinJazz/github_example.git

However, you’ll need to enter credentials every time you use git push or any other git command that interacts with a remote repository.

$ git push
Username for 'https://github.com':
Password for 'https://a@github.com':

HTTP is tedious for projects that you use regularly unless you setup your machine to remember your git credentials for you.

SSH

SSH is more secure than HTTPS and doesn’t require a username or password for authentication. Instead it uses an SSH Key stored locally on your computer.

However, it’s more complex to setup. If you wish to use SSH, follow the instructions to connect to github with ssh.

You’ll want to follow the instructions for:

About SSH (optional)
Checking for existing SSH keys (optional)
Generating a new SSH key and adding it to the ssh-agent
Adding a new SSH key to your GitHub account
Testing your SSH connection
Working with SSH key passphrases (optional)

Then you can use the git clone with the SSH URL provided.

$ git clone git@github.com:BrooklinJazz/github_example.git

GitHub CLI

The GitHub CLI provides some conveniences for working with Git and GitHub. It allows you to use the command line to accomplish tasks that would normally require GitHub.

It’s beyond the scope of this course, but you can learn more here.

Your Turn

Clone your github_example project onto your computer under a new name github_example2.

To clone a project under a new name provide a new name to the git clone command.

$ git clone  github_example2

Branches

By default, all Git changes happen on the main branch. We can create other local or remote branches for grouping changes together. Typically, we’ll create a feature branch to group related changes together.

git checkout -b creates a new branch.

$ git checkout -b example-feature-branch-name

It can also switch from the current branch to another existing branch.

$ git checkout main

---
title: Git
---
gitGraph
   commit
   commit
   branch feature-branch
   checkout feature-branch
   commit
   commit

Merging Local Changes

We can merge changes from one local branch to another with git merge.

---
title: Git
---
gitGraph
   commit
   commit
   branch feature-branch
   checkout feature-branch
   commit
   commit
   checkout main
   merge feature-branch
   commit
   commit

We have to checkout into the branch we want to merge changes into. Here’s an example flow:

$ git checkout -b feature-branch
# Stage And Commit Changes
$ git checkout main
$ git merge feature-branch

Pushing And Pulling Changes

We can push changes from a local branch to a remote branch, and pull changes from a remote branch to a local branch using git pull and git push.

$ git pull
$ git push

The first time we push a change, we need to connect the local and remote branch using --set-upstream.

$ git push --set-upstream origin 
# Or -u For Shorthant.
$ git push -u origin

Merging Remote Changes (Making A Pull Request)

To merge remote branches, we use create a pull request on GitHub accept the pull request to merge one remote branch with another. Note, this does not update local branches. These changes need to be pulled to the corresponding local branch.

$ git checkout -b feature-branch
# Stage And Commit Changes
$ git push -u origin feature-branch
# Make Pull Request On GitHub
# Make Merge Pull Request Into Main On GitHub
$ git checkout main
$ git pull

Here’s a diagram of the complete flow.

sequenceDiagram
participant LM as Local Main
participant LF as Local Feature
participant RF as Remote Feature
participant RM as Remote Main

Note right of LM: git checkout -b feature-branch
LM --> LF: checkout
Note left of LF: git add .
Note left of LF: git commit -m "message"
LF --> LF: commit changes
Note left of RF: git push -u origin feature-branch
LF ->> RF: push changes
Note right of RF: Make PR on GitHub
RF --> RF: create pull request
Note left of RM: Accept PR on GitHub
RF ->> RM: merge pull request
Note left of RM: git checkout main
Note left of RM: git pull
RM ->> LM: pull changes

Your Turn

Create a feature-branch in your github_example project.

local: stage, commit, and merge some local changes to main.
remote: stage, commit, and push some changes to a remote branch. Make a pull request and merge it into the remove main branch. Once merged, pull the changes to your local main branch.

Branching Strategies

Trunk-Based Development

Source control allows us to store different versions of the project. Typically there is a main branch for the latest version of the project.

The most straightforward source control strategy only uses a main branch. Developers can push and pull from the main branch to get the latest changes.

sequenceDiagram
    actor D1 as Developer 1
    participant R as Main
    actor D2 as Developer 2
    D1->> R: pushes changes
    R->> D2: pull changes
    D2->> R: push changes
    R->> D1: pulls changes

It’s convenient and fast. However, it lacks any review system for code changes. Therefore it’s potentially excellent for small projects with highly trusted team members, but can be less effective for large projects requiring code review or multiple stages of testing.

Dev -> -> QA -> Staging -> Prod Pipelines

Some companies will have many stages of review for changes.

There is no universal strategy. Each project may have a different pipeline. However, some common steps include:

Feature Branch: A branch containing one specific change.
Development: Developer testing and integration branch.
Quality Assurance (QA): Quality Assurance testing branch.
Staging: Approved changes ready for production but not yet deployed.
Main: The latest available version of the project.

---
title: Git Pipeline
---
gitGraph
  commit
  branch development
  commit
  branch feature-branch
  checkout feature-branch
  commit
  commit
  commit
  branch qa
  commit
  branch staging
  commit
  branch production
  commit
  checkout main
  merge production

Merge Conflicts

Source control allows us to develop our own version of the project isolated to our local version. However, if two developers edit the same file, it’s possible to have conflicts.

These conflicts need to be manually resolved. It’s often easiest to resolve conflicts using GitHub Desktop or with Visual Studio Code.

Commit Your Progress

DockYard Academy now recommends you use the latest Release rather than forking or cloning our repository.

Run git status to ensure there are no undesirable changes. Then run the following in your command line from the curriculum folder to commit your progress.

$ git add .
$ git commit -m "finish Git reading"
$ git push

We’re proud to offer our open-source curriculum free of charge for anyone to learn from at their own pace.

We also offer a paid course where you can learn from an instructor alongside a cohort of your peers. We will accept applications for the June-August 2023 cohort soon.

Navigation

Home Report An Issue Command Line Livebook

Back

Git

curriculum-main/reading/git.livemd

Git

Navigation

Overview

Version Control

Git

GitHub

Install Git

Your Turn: Create A GitHub Account

Raising An Issue

Initializing A Local Repository

Your Turn

Staging And Committing Changes

Your Turn

Cloning Repositories

Cloning With The Command Line

HTTPS

SSH

GitHub CLI

Your Turn

Branches

Merging Local Changes

Pushing And Pulling Changes

Merging Remote Changes (Making A Pull Request)

Your Turn

Branching Strategies

Trunk-Based Development

Dev -> -> QA -> Staging -> Prod Pipelines

Merge Conflicts

Further Reading

Commit Your Progress

Navigation