Introduction to Version Control with Git and GitHub PDF

Introduction to Version Control with and TAN TIEN PING Reference John Loeliger and Matthew McCullough (2012). Version control with Git. O’Reilly Media. California. https://github.com/ITboy/book/blob/master/Version%20Control%20with%20Gi t%2C%202nd%20Edition.pdf...

Introduction to Version Control with and TAN TIEN PING Reference John Loeliger and Matthew McCullough (2012). Version control with Git. O’Reilly Media. California. https://github.com/ITboy/book/blob/master/Version%20Control%20with%20Gi t%2C%202nd%20Edition.pdf BitBucket: Tutorial. https://www.atlassian.com/git/tutorials  Introduction Versioning: creation and management of multiple milestones/completions/releases of a work, which can be a file, document, software, hardware, … Why versioning? track and manage changes! Traditional way of version control: Ref: https://mikemcquaid.com/2014/01/18/why-use-version-control/  Version Control System A version control system (VCS) is a tool that manages and tracks a software, documents, and data. Track changes: who, what, why and when. Manage changes: add, modify, undo, redo changes, … Ref: https://mikemcquaid.com/2014/01/18/why-use-version-control/ Version Control System VCS is very important especially in open-source software development as most developer often work independently at different modules or issues, and they must submit the update/changes independently. There are many VCS available. The most popular is Git. Git was first introduced by Linus Torvalds to support the development of Linux kernel, but now it has been expanded to support other software development, other OS (e.g. Windows), and it can also be used to keep documents and data. Previous VCS The Source Code Control System (SCCS) was introduced in 1970s on Unix. The earliest VCS. It introduced the concept of repository. User must unlock a file and lock it back after update. The Revision Control System (RCS) was introduced in 1980s on Unix. Introduced the concept of forward delta and reverse delta concept. The Concurrent Version System (CVS) was introduced in 1986 on Unix. De facto standard for open-source development for a long time. CVS allows a file to be independently modified at private repository and then merged. BitKeeper was available in 2000. It eliminates central repository and use a distributed one instead. BitKeeper VCS – commercial system, used for Linux kernel development in 2002. In 2005, BitKeeper ends support for “free use” version1. Note: 1 BitKeeper turns open source in 2016.  Different architecture of VCS Local VCS e.g. RCS Centralized VCS e.g. CVS, subversion Distributed VCS e.g. git Ref: https://git-scm.com/book/en/v1/Getting-Started-About-Version-Control Git Why Git is introduced? Existing VCS that time does not meet the needs of Linux development. ◦ Allow parallel, independent and simultaneous development in private repositories without constant synchronization with central repository. ◦ Able to handle large number of developers at a time. ◦ Quick and efficient. ◦ Maintain integrity and thrust. Data is not compromised during transfer, and in the central repository. ◦ Enforce accountability. Keep track of who did what changes. ◦ Immutability or cannot be modified once created. ◦ Atomic transaction. A transaction that is performed or not at all. ◦ Support and encourage branch development and merging. ◦ Complete repositories. ◦ Clean design. ◦ Free & Freedom.  How you can use Git Sole user ◦ Use it just like a local VCS. Track and manage the changes that you made on files. ◦ Upload/download project to/from a remote server (e.g. GitHub). Many developers/ team ◦ Track and manage the changes that everyone made on files. ◦ Collaborate development, following a certain workflow. e.g. Gitflow, GitHub Flow... ◦ Take part in a project in GitHub. Gitflow Ref: https://proandroiddev.com/how-to-set-up-an-efficient-development-workflow-with-git-and-ci-cd-5e8916f6bece Installing Git The git installers for different OS is available at https://git-scm.com/downloads. Alternative installation procedure are available for Linux and MacOs. Ubuntu $ sudo apt-get install git Fedora $ sudo yum install git MacOs: Come with Mac OSX if you have installed XCode. Git Installation (Windows) Git Installation (Windows) In general, select the default setting given, except for the option of “Adjusting your PATH Environment”, you may want to select “Use Git and Optional Unix tools from the Command Prompts”. If you are neither familiar with DOS prompt nor Unix Commands, I would suggest you to select “Use Git and Optional Unix tools from the Commands Prompts”. There are not many Unix/Linux Commands that you have to learn to use git. These are the commands that we will use. ◦ pwd : tells you where you are. ◦ ls -a: list all files in the current directory, including hidden files. ◦ cd : change directory. You may also want to change the default (text) editor, to Notepad++ or nano, if you are not familiar with vim. vim is a very powerful editor, but it has a steep learning curve. Common Version Control Terms Repository: A collection of files managed with version control. Branch: A unique copy of the file(s) in the repository with its own history of edits Commit: Saving the changes you made to the files to your local repository. Pull: Grab changes that are not in your current repository from another repository. Push: Send your changes to a shared repository. HEAD: a reference to the current active commit. Master branch: primary branch/trunk.  Git Commands git checkout git add Working directory Staging git rm --cache git commit git reset Local repository remote repository git pull Local machine Remote server (e.g. GitHub) git push  module A{ … } module C{ … } module B{ … } module B{ … } module C{ … } Remote server (e.g. GitHub) module A{ … } module A{ … } module B{ … } module C{ … } How to create a version of File(s)? 0. Initialize a Git repository 1. Putting the file in the repository 2. Staging a file 3. Commit a file - a version is created 4. Repeat step 2 & 3 if you make changes to file 5. (Optional) pushing the file to a remote repository for sharing or even backup. How to … How to retrieve a version of file(s)? ◦ Use “git checkout” command How to rollback to previous version, and delete recent versions? ◦ Use “git reset” How to see the changes made in different versions? ◦ Use “git log” Commonly Used Git Command  Initializing a Git repository 1. Type ‘pwd’ to find out the location you are. 2. To move to the directory where you want to store your project, use the cd command. 3. In this demo, we will create an directory call project to store our HelloWorld.java. Initialize a git repository: $ git init To display the content of the directory (Unix command): $ ls -a Note: alternatively, you can also view it from WindowExplorer: https://support.microsof t.com/en- my/help/4028316/wind ows-view-hidden-files- and-folders-in-windows- 10 hidden directory.git Configure user name and email for your repository: $ git config --global user.name $ git config --global user.email Note: Git commit will use this information. You can also configure other information, such as the default text editor: $ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar - nosession -noPlugin” or $ git config --global core.editor vim To show all the config: $ git config --list Note: press ‘q’ to quit later. Adding/removing files to/from staging area Staging area: preparing files to be committed. Add a file to staging area: $ git add Add all files to staging area: $ git add. Remove file from staging area: $ git rm -- cache To remove directory from staging area: $ git rm -r --cache 1. add HelloWorld.java to staging. 2. Modify HelloWorld.java by adding few lines. 3. Type again: $ git status git status will tell us that the modified file is not not in staging area. To filter out certain file, file type, directory from being added to staging area, create a.gitignore file and list out all the files/directory that you want to filter out in the file. Save the.gitignore file in your git directory.  Git commit: Recording staged files to project history To commit, type: $ git commit My default editor is vim. The default editor will execute, allowing the user to add some comments/ notes about the commit he/she going to make. Add comments/notes about the changes that you made by inserting new lines. Do not start the line that contains comments with ‘#’ because they will be ignored. If you do not enter any thing, the git commit will be aborted. You can also execute commit and without opening up the text editor using the following command: $ git commit -m ”my comments"  You can reset the previous commit by typing, keep the changes in staging area: $ git reset --soft HEAD~1 If you want to reset the previous commit and delete the update on files that you made: $ git reset --hard HEAD~1 Another command that can do similar thing is: $ git checkout Note: see “git log” to get commit_hash You use “git reset” if you do not want to keep the errors that you made in history. E.g. when you discover some errors in the files you commit, but they have not been shared to others. You use “git checkout” if you want to keep the errors in history. Normally when the files you commit contains errors have been share/push to remote server. Ref: https://www.atlassian.com/git/tutorials/resetting-checking-out-and-reverting  $ git checkout hotfix $ git checkout hotfix $ git reset HEAD~2 $ git checkout HEAD~2 Ref: https://www.atlassian.com/git/tutorials/resetting-checking-out-and-reverting Viewing Changes To view the history of all (commit) changes made, use “git log”: $ git log To view the changes made in each commit: $ git log -p Note: text in green show the differences, strings in yellow are the commit_hash. Type ’q’ to quit. Other useful command to try out: $ git log --all --oneline $ git log --pretty=format:"%h - %an, %ar : %s"  Git branch Branch is used in VCS when you want to introduced a feature, fix a bug, introduce new version… In Git, branch is just a pointer. So it is light weight process. Create a branch will just create a new pointer actually. master master To create a branch call newfeatures: $ git branch newfeatures Note: remember to checkout after create a branch, else you might lose previous commits! newfeatures To create a branch call newfeatures and checkout (recommended): $git checkout -b newfeatures Let say in newfeature branch, we create a file HelloUniverse.java. $ git add. $ git commit -m “add HelloUniverse.java” Note: before you execute the following command, observe your FileExplorer. There are 2 files there. $ git checkout master Note: now your FileExplorer has only one file, because the HelloUniverse.java that you create is at newfeature branch, but now you are in master branch.  master $ git commit denotes the position of head master $ git commit master $ git checkout head~1 Note, You can move head backward using head~1, but you cannot move the head forward this way, but using the commit_hash or branch name. master $ git branch newfeatures $ git checkout newfeatures newfeatures or $ git checkout -b newfeatures  master $ git commit newfeatures master $ git checkout master newfeatures  Git Merge: Updating your branch Fast forward merge After branching out, there will be a point where you want to merge the branch back master newfeatures to the (normally master) branch. To merge branch to master branch: $ git checkout master $ git merge newfeatures 3-way merge If there is a straight path from master to master master feature branch, git merge can be done without any intervention. This is called ”fast forward merge”. Else, a 3-way merge is required. You need newfeatures newfeatures to resolve the conflict because Git does not know how to solve it for you. Git Merge : Updating your branch When merge conflict happens, do a “git status” to find out the files affected. you have to open the file affected by the conflict. Affected file. Open the affected file. You will notice tags like “” that tell you where the content come from. The content before “=======“ is from the receiving (e.g. master) branch, and the content after it is from the merging branch. Delete the tags and modify the content of the file as you wish. After that stage, commit the files, and optionally delete the merging branch: $ git add. $ git commit -m “merging newfeature branch” $ git branch -d newfeature GitHub GitHub is a Internet hosting service for Git repositories. GitHub was launched in 2008. GitHub can be manipulated using the Git command, or directly using online tool on the website. Ref Wikipedia: “GitHub offers its basic services free of charge. Its more advanced professional and enterprise services are commercial. Free GitHub accounts are commonly used to host open- source projects. As of January 2019, GitHub offers unlimited private repositories to all plans, including free accounts, but allowed only up to three collaborators per repository for free. Starting from April 15, 2020, the free plan allows unlimited collaborators, but restricts private repositories to 2,000 minutes of GitHub Actions per month. As of January 2020, GitHub reports having over 40 million users and more than 190 million repositories (including at least 28 million public repositories), making it the largest host of source code in the world.” You can see GitHub as it acts as a “remote” repository that stores Git projects. Nevertheless, the Git command can work without using GitHub, as the command on one machine can work with other Git repositories in different machines, because it is a distributed/peer to peer version control system. GitHub can be used to promote, and share an open source project. Ref: https://github.com/pricing How you can use GitHub? We recommend repositories remain small, ideally less than 1 GB, and less than 5 GB is strongly recommended. Smaller repositories are faster to clone and easier to work with and maintain. Individual files in a repository are strictly limited to a 100 MB maximum size limit. (Ref: https://help.github.com/en/articles/what-is-my-disk-quota) A lot of interesting open-source project for system development and research purposes. Share your system/ data to others. Collaborate in system development. Projects in GitHub Setting Up a GitHub Repository 1. Sign up an account an account at GitHub. 2. First create a ”remote” repository at GitHub. 3. Setting up the repository. 4. The GitHub remote repository is set up! 5. You want to upload your local git repository to GitHub. Setting the remote repository: $ git remote add origin https://github.com/pingtt/helloTest.git GitHub Access Using Personal Access Token Accessing GitHub using GitHub password is no longer supported. Instead you need to generate a personal access token from your GitHub account. From your GitHub account, go to Profile (top right) => Settings => Developer Settings => Personal Access Token => Generate New Token (Give your password) => Fillup the form => click Generate token => Copy the generated Token, it will be something like ghp_sFhFsSHhTzMDreGRLjmks4Tzuzgthdvfsrta Save the token at somewhere safe. $ git push -u origin master Type your username Type the token when it ask you for password. 6. Pushing the content to the remote repository. If your remote repository is not empty, you need to do git pull first. $ git push -u origin master 7. Refresh the site, and notice that the website is updated. 8. You can add a README.md either at the remote repository or local repository. 9. Synchronizing the content by pulling it from the remote repository: $ git pull origin Sharing GitHub If someone is interested in your file (and your repository is public), they can download it from your GitHub site, by clicking on the “download” button. Alternatively, they can execute the command: $ git clone https://github.com/pingtt/helloTest download button Create a GitHub Page Go to Settings Tab Thank You!