1 of 19

Git Branches and GitHub Project Management

REU Site: Applying Data Science on Energy-efficient Cluster Systems and Applications

Training Material

2 of 19

Git - Branches

Branches are different versions of a repository at one time.

Default Branch: main (old version use master)

Create a new branch: making a copy of main as it was at that point in time.

If someone else made changes to the main branch while you were working on your branch, you could pull in those updates.

Image Source: https://guides.github.com/activities/hello-world/

More on Git Branch: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

3 of 19

Git - Examples of Using Branches

A project with two major features

If bugs exist in the test version, go back to the feature development version to fix them.

feature1_dev

feature2_dev

feature1_test

feature2_test

merge

release_candidate

main

merge

new branch

version released

new branch

regression test

new branch

merge

4 of 19

Git - Examples of Using Branches (2)

Create branches with features have no dependencies

feature1_dev

feature2_dev

merge

main

merge

version released

merge

version released

merge test

5 of 19

Git - Examples of Using Branches (3)

A successful git branch model

main branch
develop branch

Supporting branches

Feature branches
Release branches
Hotfix branches

server bugs

Source: https://nvie.com/posts/a-successful-git-branching-model/

6 of 19

Git Commands for Branch

git branch: list, create, or delete branches
git switch: switch branches
git merge: join two or more development histories together
git remote: manage set of tracked repositories
git stash: stash the changes in a dirty working directory away

Source https://git-scm.com/docs https://ndpsoftware.com/git-cheatsheet.html#loc=index;

7 of 19

Git - Branching and Merging Commands

git branch: create a new branch

$ git branch <new_branch>
$ git branch --list

List all existing branches with current branch highlighted

git switch: switch to a specific branch

$ git switch <branch_name>
When you switch between branches, the files shown in your local computer will also be updated accordingly
All the untracked files does not get impacted when you move in between different branches.

git checkout: switch branches or restore working tree files

$ git checkout <branch>

Switch to <branch> and update the index and files in the working tree, and by pointing HEAD at the current branch
HEAD is a reference to the last commit in the currently check-out branch

$ git checkout -b <new_branch_name>

Create and check out the <new_banch_name>

Source: https://git-scm.com/docs

8 of 19

Git - Branching and Merging Commands (cont.)

git push: push a local branch to remote

$ git push -u origin <branch_name>
The above command will push the local branch <branch_name> to the remote repository with the name origin/<branch_name>
$ git push origin <local-branch-name>:<remote-branch-name>

Specify a different remote branch name

git merge: join two or more development histories together

$ git merge <branch>

Merge the <branch> to the current branch
Running git merge with non-trivial uncommitted changes is discouraged
Push your merge to origin after you finished the merge

$ git merge --abort

Abort the current conflict resolution process, and try to reconstruct the pre-merge state

Source: https://git-scm.com/docs

Project manager to perform the merge back to master

9 of 19

Git - Branching and Merging Commands (cont.)

Merge conflicts occur

when competing changes are made to the same line of a file
when one person edits a file and another one deletes the same file

Solve merge conflict

$ git pull pull the up-to-date version from remote branch
$ git status check which file(s) has(/have) conflict(s)
Editing the file(s) to resolve conflicts (remove the highlighted lines)

Add a new line in the test_branch.txt.

<<<<<<< HEAD

Inset a new line from the Document folder.

=======

Insert a new line from the Desktop folder.

>>>>>>> 18f5d421d6e7a7c7f49d72ff04ab302a18a60b2d

$ git add <file_name>
$ git commit -m “Resolved merge conflict by incorporating both suggestions. ”

Make sure that you have resolved all the conflicts in the file(s). You could search for “=======” in the conflict file(s).

Test if your program works after solving the merge conflicts. Then push your changes to the remote branch.

10 of 19

Activities: group practice

Create a practice repository for your group on GitHub
Everyone create your own branch and switch to it

$ git branch <your_dev_branch_name>
$ git switch <your_dev_branch_name>

Add some files to your own branch
Commit your changes in your own branch
Push your own branch to the remote repository

$ git push -u origin <your_dev_branch_name>

Merge main into your branch

$ git switch <your_dev_branch_name>
$ git merge main

Merge your branch back to the main branch

$ git switch main
$ git pull
$ git merge <your_dev_branch_name>

Be very careful if you need to merge back to the main. You may want to first check if there are any updates on the origin/main, merge it to your dev branch, and test and merge it back. Ask a Git expert in your group or your project manager.

11 of 19

GitHub - Create a Branch and Pull Request

Create a new branch

Click Code tab, and the drop down menu
Type in <new_brach_name> in the input textbox and hit “Enter”

Select the <new_branch_name>

Make some changes
Commit the changes to this new branch

Open a Pull request

Click the Pull Request tab, and then New pull request button.
Compare the branch master with <new_branch_name>.
Look over your changes in the diffs on the Compare page.
Click the Create Pull Request button and write commit message.

Merge your <new_branch_name> into the main branch

Click the Merge pull request button to merge the changes into master.
You could delete the <new_branch_name> by click the Delete branch button.

Source: https://guides.github.com/activities/hello-world/

12 of 19

GitHub - Public v.s. Private Repository

Public repository

Everyone could view and only collaborator can commit

Private repository

Only collaborates will be able to see and commit

Public or Private ?

Start with a private repository
When you need to set it public, create a new branch <new-project> and remove all private info and data
Reinit it as a new repository

Once public, some data had been shared even it was set to be private

13 of 19

GitHub - Remove Sensitive Data

Remove sensitive data from a repository

To entirely remove unwanted files from a repository's history you can use either the git filter-branch command or the BFG Repo-Cleaner.
Removing files from a repository's history
Plugging Git Leaks: Preventing and Fixing Information Exposure in Repositories
Block command line pushes that expose your personal email address

Avoiding accidental commits in the future

Avoid using git add . or git commit -a
Use git add <filename> and git rm <filename> to individually stage files
Use git add --interactive to individually review and stage changes within each file.
Use git diff --cached to review the changes that you have staged for commit.

14 of 19

GitHub - Release a project

On GitHub, navigate to the main page of the repository.
To the right of the list of files, click Releases or Latest release.
Click Draft a new release.
Type a version number for your release. Versions are based on Git tags. We recommend naming tags that fit within semantic versioning.
Use the drop-down menu to select the branch that contains the project you want to release.
Type a title and description for your release.
Optionally, to include binary files such as compiled programs in your release, drag and drop or manually select files in the binaries box.
To notify users that the release is not ready for production and may be unstable, select This is a pre-release.
If you're ready to publicize your release, click Publish release. To work on the release later, click Save draft.

https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/managing-releases-in-a-repository

15 of 19

GitHub Project Manage

Start with an issue

Create an issue to suggest a new idea or track a bug. Then organize and assign tasks to your team. And don’t spare any attachments—issues support most image and file types.

Tasks - Issue, comment, and pull request descriptions support Markdown task lists—checklists you can use to coordinate and track parts of a project. Reorder tasks as your priorities change, and check them off as you complete each one.
Assignees and mentions - Assign up to ten teammates to an issue or pull request to make sure work has an owner. Mentioning other people or teams in the issue will notify them if something changes. They can also stay in the loop by opting to receive notifications whenever someone posts a comment.
Labels - Tagging issues and pull requests with labels allows you to quickly search for them later. Filter your issues by label to find and reference all issues that are part of your project.
Milestones - Add a milestone to track a project as part of a larger goal, like a quarterly to-do list or a big feature. Then watch your milestone’s overall progress from the milestone page.

Source: https://github.com/features/project-management/

16 of 19

GitHub Project Manage (cont.)

2. Link issues and pull requests

When you link a pull request to the issue the pull request addresses, collaborators can see that someone is working on the issue. When you merge a linked pull request into the default branch of a repository, its linked issue is automatically closed.

On GitHub, navigate to the main page of the repository.
Under your repository name, click Pull requests.
In the list of pull requests, click the pull request that you'd like to link to an issue.
In the right sidebar, click Linked issues.
Click the issue you want to link to the pull request.

You can link a pull request to an issue by using a supported keyword in the pull request's description.

The syntax for closing keywords depends on whether the issue is in the same repository as the pull request.

Source: https://github.com/features/project-management/

close	fix	resolve
closes	fixes	resolves
closed	fixed	resolved

17 of 19

GitHub Project Manage (cont.)

3. See your work take shape with Projects

Visualize all of your work and prioritize it right alongside your code with projects boards.
See status of tasks, either in a repository or across your organization.

Source: https://github.com/features/project-management/

18 of 19

GitHub README file

An awesome README template

A GitHub repo of README files

https://github.com/matiassingers/awesome-readme
Examples of README files for different types of projects

19 of 19

References

Git

Basic Branching and Merge: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
Merge Conflicts: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line

Github

Branch creation: https://guides.github.com/activities/hello-world
Release Management:https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/managing-releases-in-a-repository
Project Management: https://github.com/features/project-management/

REU Site: Applying Data Science on Energy-efficient Cluster Systems and Applications