{"id":21735139,"url":"https://github.com/caltech-ipac/grits2018-github-tutorial","last_synced_at":"2025-03-21T00:20:39.883Z","repository":{"id":149118036,"uuid":"144000885","full_name":"Caltech-IPAC/grits2018-github-tutorial","owner":"Caltech-IPAC","description":"Github tutorial at GRITS 2018","archived":false,"fork":false,"pushed_at":"2020-12-14T20:41:09.000Z","size":48,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":30,"default_branch":"dev","last_synced_at":"2025-01-25T20:43:48.613Z","etag":null,"topics":["caltech","git","github","grits","ipac","scratch","temporary","tutorial"],"latest_commit_sha":null,"homepage":"https://www.ipac.caltech.edu/GRITS/2018/","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Caltech-IPAC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-08T10:57:10.000Z","updated_at":"2020-12-14T20:41:11.000Z","dependencies_parsed_at":"2023-05-05T02:31:20.762Z","dependency_job_id":null,"html_url":"https://github.com/Caltech-IPAC/grits2018-github-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caltech-IPAC%2Fgrits2018-github-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caltech-IPAC%2Fgrits2018-github-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caltech-IPAC%2Fgrits2018-github-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Caltech-IPAC%2Fgrits2018-github-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Caltech-IPAC","download_url":"https://codeload.github.com/Caltech-IPAC/grits2018-github-tutorial/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244712724,"owners_count":20497544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caltech","git","github","grits","ipac","scratch","temporary","tutorial"],"created_at":"2024-11-26T05:12:01.935Z","updated_at":"2025-03-21T00:20:39.855Z","avatar_url":"https://github.com/Caltech-IPAC.png","language":"Shell","readme":"# GitHub/git tutorial\nWorkshop scratch area for demo purposes\n\n* author: [Emmanuel Joliet](https://caltech-ipac.slack.com/team/ejoliet) ejoliet@ipac.caltech.edu\n\n## Version control with Git\n\n-\u003e GitHub is a code hosting platform for version control and collaboration based on `git`. GitHub allow you to do (more) visually what git can do from the termnal (merging branch, diff, blames, insights, logs, history).\n\n-\u003e Git is a version control system:\n\nRemember those 3 concepts, the first one is required for the following ones to exist: \n1. versioning files means tracking/tagging and persisting history of file (incremental) changes\n2. restore changes back from the past (commits hash!)\n3. merge with changes from other branches/remote\n\n* Everything is local (95%!), you can work (change/track/merge your files) offline.\n* Distributed, switch repos, fork, etc.\n* Tree, branches and checkpoints `git commit \u0026\u0026 git add -u \u0026\u0026 git push` (~ `save as`): \nraise a hand whoever, in the past, saved a file appending a suffix *-VERSION_TAG* to the filename to track the changes? :raised_hand:\n\nPull request workflow, see graph with branches in [slides draft](https://caltech.box.com/s/67o8smteg4qghbl5cbqb7l65qnzn56ef) or directly [here](https://guides.github.com/introduction/flow/)\n\n## Tutorial\nThe idea is that at the end of the workshop you shouldn't be saving your file with different filename everrtytime you want to keep a version of it for the future ;-)\n\nThis tutorial will cover:\n\n* `git` main commands\n* [branches and merging](https://www.atlassian.com/git/tutorials/using-branches), i.e. if 2 branches, `master` and `dev`:\n![branches](https://cdn-images-1.medium.com/max/1800/1*tnvRls6Dg7vFt0zGdtfu_w.png)\n* github tool: graphs/metrics, pull request, code review\n\nParticipants will need a github account and be added to the (team) repos write permission to be able to interact with the IPAC repos and [Git](https://git-scm.com/) tool installed locally.\n\n## Demo through a Pull Request example\n\nParticipants will be guided through the following steps:\n\n`git` from scratch!\n\n1. **clone** the repos locally on their end (need git software installed)\n  * `git clone https://github.com/Caltech-IPAC/grits2018-github-tutorial.git` \n  * default landing branch should be `dev` (default per repos, this one has rules for PRs!)\n    * `git status -sb` to check on which branch you are\n\n2. **Pull request workflow demo** with feature/ticket **branch** from `dev` \n  * Will go through steps 3. to 9. described below (hands-on) very fast here\n  * `git checkout -b [branch name]`, required unique branch name, usually formatted as `ISSUE-ID-meaningful-short-description`\n    * for example, let's take a look at epic from JIRA board [IRSA-2060](https://jira.ipac.caltech.edu/browse/IRSA-2060) and i've picked a ticket, i.e. `IRSA-2062 improve the text`\n    * Branch name will be `IRSA-2062-improve-text`, once created, **git** will switch you to this local branch (see branches `git branch -a`, see status `git status (--long)`)\n   * Will update locally [scratch.txt](scratch.txt) and make it **bold**\n   * Will commit and push the branch\n   * Will make a [pull request](https://github.com/Caltech-IPAC/grits2018-tutorial/compare)\n   * Will show the review aspect of a PR and merge\n   * See JIRA [ticket](https://jira.ipac.caltech.edu/browse/IRSA-2062) back again with reference to branch merged and links. If demo goes bananas, see sample [here IRSA-2039](https://jira.ipac.caltech.edu/browse/IRSA-2039)\n    \n## Hands-on: back to you!\n\n3. **Assignment for you**: Imagine that you get assigned a ticket to update [names.txt](names.txt) with your name \n  * clone repos if you didn't do it yet! (see 1.)\n  * create a branch, append your github `USERNAME` to branch name, *i.e.* `git checkout -b EJOLIET-adding-name`\n  * edit and **change** the file named [names.txt](names.txt) by adding your name, don't remove other names! ;-)\n  * **commit** your changes in your branch: add/commit\n    1. `git add names.txt`\n    2. `git commit -m\"[your message]\"`\n4. continue changing/adding/commit and check the differences:\n    1. `git show` (`git show -2 -p` see history diff *2* commits behind)\n    2. Check your commit history: `git log` or more fancy `git log --decorate --graph`\n    3. *OPTIONAL*: if no commit to be made, at that point, you can: pull or rebase\n     * after pulling, check branches pulled: `git branch --all`\n     * if `dev` got new things, you will need to rebase in order to avoid conflict at the time you pull request\n    4. *OPTIONAL*: `git stash` very useful to [stage changes](https://git-scm.com/docs/git-stash) and switch from one branch to another...\n     \n5. Once done with changes, **push** to server (`-u` flag means that you'll start tracking the branch *u*pstream)\n  * First time push: `git push -u origin [branch name]`\n  * Your local branch is now synced with remote, someone else can take other or run jenkins ;-)\n  * Next pulls/pushes: `git push` or `git pull`\n\n6. **Pull Request**: in github.com, button 'pull request' should appear\n  * Show a pull request / code review\n  * *OPTIONAL* Show a case of how to [request changes](https://help.github.com/articles/about-pull-request-reviews/)  (and what to do)\n    * if request change, need to go to the branch, and\n        * change file, git add / commit / (`rebase -i` to squash) / push (steps 3 to 6 above)\n        * no rebase there because branch is already in server / no force push either\n  * wait for approve (repo rule in [settings](https://github.com/Caltech-IPAC/grits2018-tutorial/settings/branches))\n    * did you update the counter in [sum-team.txt](sum-team.txt) and run `./team-test.sh`? Jenkins will complain ;-)\n7. Show when approve changes and merge from github\n  * Branch can be deleted from github after merged\n\n8. OPTIONAL: If merge conflict (typically, same line have changed in the meantime): github will suggest commands and guidelines to solve and merge locally. Tipically you'll need to fix the conflict and commit then merge back to dev `git merge [branch]`\n\n9. Once merged, typically the branch can be deleted from github from the same pull request page.\n\n## Advanced\n\nYou want more `git`?\n\n* branch merge with --no-ff on tagged branches, otherwise fast-forward\n![no-ff](https://nvie.com/img/merge-without-ff@2x.png)\n* stage changes, `git stash`, reapply and drop last stash: `git stash pop`, others command: drop, apply stash{X}\n* create pathch and apply: `git diff hash1 hash2 \u003e patch.diff` then, apply to different branch, `git apply patch.diff`\n* rebase what? Rewriting the history! Sometime is colorful... `rebase -i` to pick and squash!\n  * I messed up a branch merged or a commit? revert remote? Rewriting history requires FORCE pushed `-f`, see this [article](http://christoph.ruegg.name/blog/git-howto-revert-a-commit-already-pushed-to-a-remote-reposit.html)\n  * `git reset` to change the pointer, `git revert` to a particular commit, go back in history at your own peril.\n* cherry picking? Is it like going to a picnic? \n* fork? And knives too... a way to contribute to a project even if they don't want you! [example](https://github.com/tmtsoftware/csw-acceptance/compare/master...ejoliet:master)\n* `git bisect` WOW!\n* see your git commands with `git reflog`\n* cleanup local branches: `git branch -d [BRANCH_NAME]` (or `-D` to force delete if branch has changed after remote merged)\n  * remote delete: `git push origin --delete [BR_NAME]`\n\n## Github and (admin) advanced tools\n\n* Permision for [teams](https://github.com/Caltech-IPAC/grits2018-tutorial/settings/collaboration)\n* See [branche rules](https://github.com/Caltech-IPAC/grits2018-tutorial/settings/branches)\n* See statistics example: [pulse](https://github.com/Caltech-IPAC/firefly/pulse)\n* See network branches example: [Firefly network](https://github.com/Caltech-IPAC/firefly/network)\n* GitHub blame tool, [example](https://github.com/Caltech-IPAC/firefly/blame/dev/src/firefly/java/edu/caltech/ipac/firefly/server/query/UserCatalogQuery.java)! see `git` useful command below to do it from console.\n\n### Need Help?\n\n#### guides\n* [Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n* [Git documentation](https://git-scm.com/docs)\n* [Github guides](https://guides.github.com) and [cheat sheet](https://services.github.com/on-demand/downloads/github-git-cheat-sheet.pdf)\n* [Useful git tips \u0026 tricks!](https://git-scm.com/book/en/v1/Git-Basics-Tips-and-Tricks), [terminal autocompletion!](https://github.com/bobthecow/git-flow-completion/wiki/Install-Bash-git-completion)\n* [To Fork or to clone, that is the question!](http://stackoverflow.com/questions/9257533/what-is-the-difference-between-origin-and-upstream-on-github/9257901#9257901)\n* [Pull request template](https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/)\n* Not for beginners but Mac/Windows users can use [SourceTree](https://www.sourcetreeapp.com/) to visualize/work on git repos/branches\n\n#### useful commands\n* [git config aliases and more](https://www.atlassian.com/git/tutorials/setting-up-a-repository/git-config) or use command `git config --global --edit` [my aliases](git-alias.txt)\n* `git config --global alias.hist 'log --pretty=format:\"%h %ad (%cr) | %s%d [%an]\" --graph --date=short'`\n* very powerful one: `git log --grep`\n* Learn more about [credentials](https://help.github.com/articles/caching-your-github-password-in-git/), clone with username, prompting your password: `git clone https://username@github.com/username/repository.git`\n* Switch username or endpoint: `git remote set-url origin https://username@github.com/Caltech-IPAC/grits2018-github-tutorial.git`\n* .gitignore? convenient when `git add -u`\n* Github blame is awesome but can i do something similar with git? YES:\n   * Do search for changes related to a string `git log --stat -S\"gator.host\" --pretty=format:'%h %an %ad %s' .`\n   * Once you know the file, see diff in each commit, [~blame](https://blog.andrewray.me/a-better-git-blame/): `git log -p -M --follow --stat -- /path/to/FILE`. Ta-da!\n* Resolve conflict with git: `git mergetool` [details](https://stackoverflow.com/questions/161813/how-to-resolve-merge-conflicts-in-git)\n\n#### HELP!?\n* [Leave message in Slack #grits-tutorial](https://caltech-ipac.slack.com/messages/CCN03J7D5)\n* [Slack me](https://caltech-ipac.slack.com/messages/@ejoliet)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaltech-ipac%2Fgrits2018-github-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaltech-ipac%2Fgrits2018-github-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaltech-ipac%2Fgrits2018-github-tutorial/lists"}