GIT Tutorial Version control and shared development - PowerPoint Presentation

1. GIT TutorialVersion control and shared developmentApril 30, 2018Peder Larson, PhDAssociate ProfessorUCSF Department of Radiology and Biomedical Imaging

2. What is git?Version controlTrack changes you make to software or other documentsGo back to old versions, or look at changesShared development platformDesigned to support projects with multiple developersCreate branches, merge and track individual user changes, report and assign issuesDistributedEvery version of the repository, whether local or hosted (e.g. github, Radiology gitlab) is a full repository, so access to host requiredTransition to and from local copy to hosted repository, between hosted sites, and between local copiesApril 30, 2018Git tutorial2

3. Why Git?Sharing and jointly developing codeStandard tool for version control & software development, easy to work with othersOpen source and freeDistributed – track changes on your local copiesJobsEmployers may consider your github/gitlab/bitbucket profile as part of your CV for tech jobsAsk any graduate who works on software in industry – they must use version controlMany Toolse.g. github desktop client, probably many othersWeb interfacesApril 30, 2018Git tutorial3

4. Prominent Git Software GroupsTensorFlow (Google) https://github.com/tensorflow Python https://github.com/python Facebook https://github.com/facebook LinkedIn https://github.com/linkedin April 30, 2018Git tutorial4

5. Selected Imaging Repositories/GroupsSIVIC - https://github.com/SIVICLab/sivic ANTS – Advanced Normalization Tools https://github.com/ANTsX/ANTs AFNI – Analysis of Functional NeuroImages https://github.com/afni/afni ISMRMRD – ISMRM raw data formatBART – Berkeley advanced reconstruction toolbox https://github.com/mrirecon/bart Many more!April 30, 2018Git tutorial5

6. Git Servers and Structurehttps://git.radiology.ucsf.edu/Radiology git serverBehind firewall, only accessible by Radiology users, no public reposSensitive projects (data, IP)Easily explored by others in Radiologygithub.comMost widely used servicePublic and private repositories (“Repos”)Request academic account for unlimited free private repos for 2 years – education.github.comIndividual accountsGroups – for groups with multiple shared projects, e.g. lab/research group, specific project/grant, organizationApril 30, 2018Git tutorial6

7. My Personal Git EcosystemRadiology gitplarson - personal account, for my own projects or initial developmentmatlabEPSI processingEPIC-MRI – group account for GE MRI EPIC programming projects (so far I’m the only user  )3dradialprose_prostatefidcsi_c133duteconesGitHubagentmess – personal account, personal projects, papers, playing around with codeLarsonLab – group account for shared projects and sustained projectshyperpolarized-mri-toolboxmripy (Python tools for MRI, including neural networks, originally from Peng Cao)Spectral-Spatial-RF-Pulse-DesignMRI-education-resourcesUCSF-EPIC-MRIFor sharing EPIC software with othersAll private repositories (GE proprietary information)April 30, 2018Git tutorial7Incredibly valuable for these projects!

8. GitHub/GitLab featuresStar – any interesting codeWatch – be notified of repo changesFork – make your own copy to use and modifyApril 30, 2018Git tutorial8

9. Remember to …Commit every day!Practice, and don’t worry about mistakes since there’s a history of all your changesApril 30, 2018Git tutorial9

10. InitializationLogin – git.radiology.ucsf.edu or github.comCreate New Repository/ProjectClone ‘git clone <address>’ Copy address from webClone to multiple places (laptop, SCS network)Add files or import in existing directoryCheck file status ‘git status’, should show Untracked FilesAdd these files to git repository with ‘git add’Check file status ‘git status’, should show Changes to Be CommittedCommit ’git commit –m “<commit message>” ‘Push changes to remote repository (e.g. github, radiology git) ‘git push’Check web!April 30, 2018Git tutorial10

11. Daily WorkflowPull changes from remote repo (in case others have added edits) ‘git pull’If you are just a user (not developer) of repo/project, then this is all you needModify filesCheck status ‘git status’Add changes ‘git add’Confirm status ‘git status’Commit ‘git commit’Push changes ‘git push’ (don’t need to do for every commit, but at least every day is best)Quick commit – ‘git commit –a –m <message>” stages all changes to be commited and then commitsApril 30, 2018Git tutorial11

12. Advanced Workflows - ignoring files.gitignore – this is a file within your git repository that can choose to ignore certain files. For example, large data files, temporary files, executables. .gitignore templates at https://github.com/github/gitignoreCopy into main directoryIn GitHub Desktop app, right-click to add files to .gitignoreWant to store large files? Use “git-lfs” (large file storage) git-lfs.github.com April 30, 2018Git tutorial12

13. Advanced Workflows - Branching “Branch”separate version of repository to work onCreate a branch to fix a bug, add a new feature, or play around without disrupting the “master” branch (default branch when you start a projectEasy to explore and visualize via web interfacesFirst branch created is the “master”April 30, 2018Git tutorial13

14. Advanced Workflows – Creating and Editing New BranchVia Web interfaceThen switch to branch in repositoryList all branches ‘git branch –a’Checkout new branch ‘git checkout <branchname>’Confirm you are now working on new branch ‘git branch’Or Command LineCheck current branch ‘git branch -a’ (lists branches, * indicated curent branch_Switch to starting branch if needed, e.g. ‘git checkout master’ to create branch from master Create new branch ‘git branch <branchname>’Checkout new branch ‘git checkout <branchname>’Confirm you are now working on new branch ‘git branch’April 30, 2018Git tutorial14

15. Advanced Workflows – Creating and Editing New BranchNormally, a repository is a single directory and you can switch between branches (‘git branch’ to view branches, ‘git checkout <branchname>’ to switch)This can cause problems if you (like me) forget to check what branch you are working onAlternativeKeep one repository as a ‘master’ git clone git@git.radiology.ucsf.edu:PLarson/git-tutorial-test.git git-tutorial-test_masterClone another version of repo for development(more like SVN)git clone git@git.radiology.ucsf.edu:PLarson/git-tutorial-test.git git-tutorial-test_branchcd git-tutorial-test_branchgit checkout <branchname>April 30, 2018Git tutorial15

16. Advanced Workflows – Merging BranchesCreate a Merge/pull requestWhen you want to put branches together, merge the changesE.g. you have added feature in a feature branch, merge back into the master branchI find this easiest via web interfacesWhen you push changes ‘git push’, message:remote: To create a merge request for branch2, visit:remote:   https://git.radiology.ucsf.edu/PLarson/git-tutorial-test/merge_requests/new?merge_request%5Bsource_branch%5D=branch2Review and submit merge requestConfirm request and submit (last steps are so you can review the changes carefully before continuing)April 30, 2018Git tutorial16

17. Fixing conflictsCan arise when remote repo is out of sync with local copy, or during merging of branchesFind conflicting files ‘git status’Edit with your favorite editorConflicting lines marked with <<<<, ====, >>>>Choose appropriate changes, remove lines with <<<<, ====, >>>>Mark resolution with ‘git add’CommitPushApril 30, 2018Git tutorial17

18. Advanced Workflows - OtherMultiple Remote Repos (e.g. github vs radiology git)Can sync local copy with bothMove repository to other locationCreate empty repositoryAdd as a remote ‘git remote add github https://github.com/agentmess/git-tutorial-test.git’ (can change “github” to be description of another remote repository, use ”origin” if you want to make this the new default repository )Push to new remote ‘git push --all github’ April 30, 2018Git tutorial18

19. Advanced Workflows - OtherTags/releasesWhen you’ve got a stable productAllows others to easily find stable version or version that will work for themIssuesKeep track of bugs to fix or features to addApril 30, 2018Git tutorial19

20. Other features for citing and sharing (GitHub based)Zenodo for citing codeGet DOI for citing your code! https://zenodo.org/account/settings/github/ Webpages – e.g. Radiology retreat, BART https://mrirecon.github.io/bart/ https://pages.github.com/Setup at username.github.ioMATLAB File Exchange – automatically post your MATLAB code from github here April 30, 2018Git tutorial20

21. More resourcesGoogle your error messagehttps://intrarad.ucsf.edu/twiki/bin/view/Sysadmin/GitLabhttps://git.radiology.ucsf.edu/EPIC-MRI/BestPracticesGetting Started guides on github and gitlabApril 30, 2018Git tutorial21

22. Remember to …Commit every day!Practice, and don’t worry about mistakes since there’s a history of all your changesgit on itgit your roll ongit ‘er doneeverybody git togetherApril 30, 2018Git tutorial22