A quick (and maybe practical) guide to Git and version control By Jay Johnson Necessary shout outs and reference links
• from slides from CSE 380 with Dr. Chris Simmons (UT-Austin) and • notes from Prof. Jean-Luc Thiffeault (UW-Madison) • https://betterexplained.com/articles/a-visual-guide-to-version-control/ • http://www.math.wisc.edu/~jeanluc/gitlab_instructions.php • https://betterexplained.com/articles/a-visual-guide-to-version-control/ • http://rogerdudler.github.io/git-guide/ • https://git-scm.com/book/en/v2/Getting-Started-Git-Basics • https://docs.gitlab.com/ce/gitlab-basics/start-using-git.html What is version control?
• It tracks your files over time! • Makes life easier. You probably have already done this…
• Have you ever done something like?... • Resume-may2015.docx • Resume-june2017.docx • Or this… • Seminar_20171116_Spratt_Draft1.tex • Seminar_20171116_Spratt_Draft2.tex
• We want a new version without destroying the old ones! • We may even use a shared folder so you don’t have to email things back and forth, and hopefully everyone relabels them when they change things. This works for small projects but large ones? A whole dissertation? Not really… What does version control do?
• Backup and Restore. Files are saved as they are edited, and you can jump to any moment in time. Need that file as it was on Feb 23, 2007? No problem. • Synchronization. Lets people share files and stay up-to-date with the latest version. • Short-term undo. Monkeying with a file and messed it up? (That’s just like you, isn’t it?). Throw away your changes and go back to the “last known good” version in the database. • Long-term undo. Sometimes we mess up bad. Suppose you made a change a year ago, and it had a bug. Jump back to the old version, and see what change was made that day. • Track Changes. As files are updated, you can leave messages explaining why the change happened (stored in the VCS, not the file). This makes it easy to see how a file is evolving over time, and why. • Track Ownership. A VCS tags every change with the name of the person who made it. Helpful for blamestorming giving credit. • Sandboxing, or insurance against yourself. Making a big change? You can make temporary changes in an isolated area, test and work out the kinks before “checking in” your changes. • Branching and merging. A larger sandbox. You can branch a copy of your code into a separate area and modify it in isolation (tracking changes separately). Later, you can merge your work back into the common area. Using version control
• Actually using version control is the first step • Put EVERYTHING under version control Consider putting parts of your home directory under VC Use a consistent project structure and naming convention Commit often and in logical chunks
• Write meaningful commit messages
• Do all file operations in the VCS Set up change notifications if working with multiple people Many online servers offer free code storage…
• whole Wikipedia page about it: https://en.wikipedia.org/wiki/Comparison_of_source_code_hosting_ facilities
GitLab has unlimited private repos for an unlimited number of collaborators plus it is the only one which is completely open source.
I have used Bitbucket for years and they have a great GUI environment (SourceTree) but I am migrating to GitLab. Some possible tools
• Free tools! • RCS – revision control systems • CVS – concurrent version systems • SVN - subversion • Mercurial • Git – which we will talk about today
• Commercial • MS Visual Studio Team System • IBM Rational Software: • Clearcase AccuRev • MKS Integrity Who uses Git? What is git?
• DISTRIBUTED version control system • Everyone has the complete history • Everything is done offline • No central authority • Changes can be shared without a server • This means you don’t have to be connected to your server to make changes, you can do them whenever and just ’push’ them later. Git tracks your folder in a series of snapshots in time Some quick jargon
• Repository (repo): the folder/directory in which you are tracking changes • Master: think the tree trunk – all changes are on here • Branch: Another copy of your filesystem where you can make changes with no worries about breaking things! • Add: pick which files you want to change. • Commit: Think ‘saving a new version’ this is a snapshot in time of your files • Push: Send the changes to Gitlab or your server • Pull: When ask for the changes by others (or you on other computers) • HEAD: The most current commit in the working directory The Git workflow: Three Steps The Git workflow: Three Steps
The basic Git workflow goes something like this: 1. You modify files in your working tree. 2. You selectively stage just those changes you want to be part of your next commit, which adds only those changes to the staging area. 3. You do a commit, which takes the files as they are in the staging area and stores that snapshot permanently to your Git directory. add & commit When to commit?
• Committing too often may leave the repo in a state where the current version doesn’t really work, or you can’t reasonably find when things broke • Committing too infrequently means that you can’t track your changes very well and it makes conflicts much more likely pushing changes branching (more advanced) useful hints Let’s start together! Make a folder
• mkdir mynewrepo • cd mynewrepo • git init Introduce yourself to git
• $ git config --global user.name "John Doe" • $ git config --global user.email [email protected] Optional: Set your default text editor
• For Notepad++ on windows • git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -nosession” • For vim (or emacs) on Unix-based • git config –global core.editor vim Check your settings….
• git config --list
Or for a specific key’s value • git config
• Why do we do this? • It makes logging in a whole lot easier. Check if you already have an SSH key
Git Bash on Windows / GNU/Linux / macOS / PowerShell: • $ cat ~/.ssh/id_rsa.pub
Windows Command Prompt: • $ type %userprofile%\.ssh\id_rsa.pub
• If you see something starting with ‘ssh-rsa’ then you are set! You can just skip ahead and copy it. • If you don’t, then you need to make one! Generating a new SSH key pair
Git Bash on Windows / GNU/Linux / macOS: • $ ssh-keygen
When asked for a file path, just use the default by pressing enter. If you already have an SSH key pair but want to use a new one, Google how to do it…
Next you will be asked for a password, you should* put one in but don’t need one for now. Enter one or skip it by pressing enter. To change the password in the future use… • ssh-keygen -p
• Go to ‘SSH Keys’ tab in ’Profile Settings’ • Paste your key in the ‘Key’ section • Give a reasonable name “Laptop” • Make sure that copied everything starting with ‘ssh-rsa’ and ending with your email. • Optionally, test your setup (replace ‘example.com’ with your GitLab domain)… ssh –T [email protected] Create a new project in GitLab
• get the folder from gitlab make a file, add it, commit it and send it back! • $ git clone [email protected]:jayjohnson/mynewrepo.git • $ cd mynewrepo • $ touch README.md • $ git add README.md • $ git commit -m "add README" • $ git push -u origin master Merges and diffs
If someone else (or another computer) made a change and it conflicts with what you have committed, you can combine them with: $ git merge
But then you will have to commit them again $ git commit –m "Merged changes." Important other functions
$ git status which gives "status report" of the current state of your local files, and $ git diff or $ git diff paper.tex which lists the differences between local file and the original file. It is also useful to view the change history (or log) for a file or directory: $ git log paper.tex Finally, to remove a file or directory run $ git rm paper.tex which deletes the file, but will also delete for you collaborators when they pull changes from the server. Note that removals should be explained in the commit log message (as should everything else!). Some tips
• Do not be afraid to commit changes! Git remembers everything before your commit, so it is virtually impossible to break anything. • Commit changes often! It is better to have a detailed log of small changes than a huge number of simultaneous changes. In particular, if you don't commit changes often you will forget what you changed (though liberal use of 'git diff' helps to figure that out). That said, a committed changeset should usually be 'consistent,' in the sense that it doesn't break things for everyone else. But sometimes it is preferable to have smaller changesets that do break things, as long as you don't push your changes to the server until done. Just make sure the log message reflects this. • Write helpful log messages! It takes a few seconds more but it's worth it. Refer to changes in specific individual files. Your collaborators will thank you, and you will thank yourself when you revisit the project two years down the line. For multiline log messages, the first line should be a summary of the changes. • Do not include binaries, executables, logs, etc. or any other files that can be recreated. The idea behind version control is to keep track of meaningful changes to files. Binary files tend to change often, and are designed to be recreated from sources. Log files also change often, since they usually contain dates. Unless the binary or log information is truly essential (i.e, the PDF figures in a paper), these should not be versioned. See next slide for how to avoid them showing up on 'git stat'. Exclude certain file types on $ git status .gitignore file: To avoid unversioned files showing up on 'git stat', which is distracting and might lead to you not noticing changes, add their file names to the special .gitignore file, which lives at the base of the project folder. For example, when dealing with LaTeX documents, my .gitignore file usually contains *.aux *.bbl *.blg *.log .DS_Store The final line ignores the clutter files generated by OSX. Note that the file .gitignore should itself be under version control ('git add .gitignore'). replace local changes Going back to an early commit
• Great flow chart for deciding how to go back to something older… • https://raw.githubusercontent.com/emmajane/gitforteams/master/resources/w orkflow-undoing-changes.png • More info at: • https://stackoverflow.com/questions/4114095/how-to-revert-git-repository-to-a- previous-commit • Simple way • Find which commit you want to go back to with (remember the sha1 # where you are going • $ git log • Go to that commit you want • $ git checkout
• if you want to go back and see what you committed (without going online to Gitlab) use $ git log • options • only show X number of entries • $ -[number] • show each on one line • $ --pretty=oneline (can also be ‘short’, ‘full’, etc..) • show the difference of each commit • $ -p • simple clean • $ git log -oneline –n 10 • Ex: $ git log -3 --pretty=oneline • so many ways to customize what you want to see • https://git-scm.com/book/id/v2/Git-Basics-Viewing-the-Commit-History More advanced features… new branch and switch to it update & merge tagging More info / references
• https://betterexplained.com/articles/a-visual-guide-to-version- control/ • http://rogerdudler.github.io/git-guide/ • https://git-scm.com/book/en/v2/Getting-Started-Git-Basics • https://docs.gitlab.com/ce/gitlab-basics/start-using-git.html