Changes between Version 98 and Version 99 of HowToGit
- Timestamp:
- Aug 23, 2021, 7:50:56 PM (3 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
HowToGit
v98 v99 3 3 = Git How-to = 4 4 5 **The instructions for the common contributing cases are in [https://github.com/OSGeo/grass/blob/main/CONTRIBUTING.md CONTRIBUTING] file.** 6 5 7 The repo is here: https://github.com/OSGeo/grass 6 7 **The instructions for the common contributing cases are in [https://github.com/OSGeo/grass/blob/master/CONTRIBUTING.md CONTRIBUTING] file.**8 8 9 9 Below we discuss more advanced and specific workflows. … … 22 22 * Fork the GRASS GIS repository, create feature branch(es) with the changes, and suggest your changes using pull requests. 23 23 24 === Workflow for GRASS GIS git repositories === 25 26 The same procedure is recommended also from [https://github.com/osgeo/grass-addons GRASS Addons repository]. 27 ==== Preparation: cloning the repo ==== 24 == Workflow for GRASS GIS Git repositories == 25 26 The same procedure is recommended also for [https://github.com/osgeo/grass-addons GRASS Addons repository]. 27 28 === Preparation: cloning the repo === 28 29 29 30 First [https://github.com/OSGeo/grass fork the GRASS GIS repo] in the !GitHub UI to `your_GH_account`. This is the same as what !GitHub documentation suggests. See: [https://help.github.com/en/articles/fork-a-repo Fork a repo] and [https://help.github.com/en/articles/syncing-a-fork Syncing a fork] in !GitHub help. 30 31 31 Note: add SSH key, see [https://help.github.com/en/articles/connecting-to-github-with-ssh GitHub documentation].32 Note: Add SSH key, see [https://help.github.com/en/articles/connecting-to-github-with-ssh GitHub documentation]. 32 33 33 34 Note: If you get the error message: [https://askubuntu.com/questions/610940/ssh-connect-to-host-github-com-port-22-connection-refused ''ssh: connect to host github.com port 22: Connection refused''] (e.g. because you are behind a firewall that blocks traffic on port 22), you can try to replace {{{git@github.com:}}} with {{{ssh://git@ssh.github.com:443/}}}, when you clone or remote add repos. … … 56 57 git remote add upstream git@github.com:OSGeo/grass-addons.git 57 58 }}} 58 === = Working with git ====59 === Working with Git === 59 60 60 61 Note: this requires the "remotes" to be set as shown above. … … 64 65 git fetch --all 65 66 66 ### a) updating MASTER67 # merge updates into local ma ster68 git merge upstream/ma ster67 ### a) updating the main branch 68 # merge updates into local main branch 69 git merge upstream/main 69 70 70 71 # at this point we have reached: 71 # (HEAD -> ma ster, upstream/master)72 # (HEAD -> main, upstream/main) 72 73 73 74 ### b) updating releasebranch_7_8 … … 84 85 85 86 # update own remote 86 # - clears "Your branch is ahead of 'origin/ma ster' by XX commits.", and87 # - avoids "This branch is XX commits behind OSGeo:ma ster." on GitHub web interface88 git push origin ma ster87 # - clears "Your branch is ahead of 'origin/main' by XX commits.", and 88 # - avoids "This branch is XX commits behind OSGeo:main." on GitHub web interface 89 git push origin main 89 90 90 91 # list existing branches … … 114 115 }}} 115 116 116 N OTE: for different pull requests, simply create different feature branches.117 118 === = Keep your local source code up to date ====117 Note: for different pull requests, simply create different feature branches. 118 119 === Keep your local source code up to date === 119 120 120 121 [from https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md#working-with-a-feature-branch] 121 122 122 You may need to re synchronize against masterif you need some bugfix or new capability that has been added since you created your branch123 You may need to re-synchronize against the main branch if you need some bugfix or new capability that has been added since you created your branch 123 124 124 125 {{{ 125 126 # assuming that "upstream" points to OSGeo/grass 126 127 git fetch upstream 127 git rebase upstream/ma ster128 git rebase upstream/main 128 129 129 130 # if rebase fails with "error: cannot rebase: You have unstaged changes...", then move your uncommitted local changes to "stash" 130 131 git stash 131 132 # now you can rebase 132 git rebase upstream/ma ster133 git rebase upstream/main 133 134 # apply your local changes on top 134 git stash apply && git stashpop135 git stash pop 135 136 }}} 136 137 137 138 Continue do your changes and commit/push them (ideally to a feature branch, see above). 138 139 139 === = Updating your PR from master ====140 141 Updating your PR from masteris often referred to as rebasing a PR. It comes into play in case there are142 changes in masteryou need to incorporate into your (feature or fix) branch before the PR can be merged, you need to rebase your branch to upstream:140 === Updating your PR from main === 141 142 Updating your PR from the main branch is often referred to as rebasing a PR. It comes into play in case there are 143 changes in the main branch you need to incorporate into your (feature or fix) branch before the PR can be merged, you need to rebase your branch to upstream: 143 144 144 145 {{{ 145 146 git fetch upstream 146 git rebase upstream/ma ster147 git rebase upstream/main 147 148 git status 148 149 }}} … … 173 174 }}} 174 175 175 If you have access to one of the OSGeo repositories (namel ly OSGeo/grass in this case), before force pushing, you need be sure that origin points to your fork and not the OSGeo repo. You can check that using `git remote -v`.176 If you have access to one of the OSGeo repositories (namely OSGeo/grass in this case), before force pushing, you need be sure that origin points to your fork and not the OSGeo repo. You can check that using `git remote -v`. 176 177 == Switching between branches == 177 178 … … 180 181 https://lists.osgeo.org/pipermail/grass-dev/2019-May/092653.html 181 182 182 == Testing pull requests from other contributors in ma ster==183 == Testing pull requests from other contributors in main == 183 184 184 185 !GitHub provides command line instructions under each pull request ([https://github.com/OSGeo/grass/pulls "Pulls" tab]). Please check there. … … 228 229 {{{ 229 230 Fix this error #123 230 Someone wants to merge 3 commits into OSGeo:ma sterfrom Someone:fix-this-error231 Someone wants to merge 3 commits into OSGeo:main from Someone:fix-this-error 231 232 }}} 232 233 the command would look like: … … 238 239 239 240 # after testing, you may delete locally 240 git checkout ma ster241 git checkout main 241 242 git branch -D fix-this-error 242 243 }}} … … 247 248 [alias] 248 249 pr = "!f() { git fetch -fu ${2:-upstream} refs/pull/$1/head:pr/$1 && git checkout pr/$1; }; f" 249 pr-clean = "!git checkout ma ster; git for-each-ref refs/heads/pr/* --format=\"%(refname)\" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done"250 pr-clean = "!git checkout main ; git for-each-ref refs/heads/pr/* --format=\"%(refname)\" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done" 250 251 }}} 251 252 … … 256 257 257 258 git branch -a 258 ma ster259 main 259 260 * pr/832 260 261 pr/837 … … 266 267 }}} 267 268 268 Note: to be on the safe side, only use this for testing pull request!269 Note: To be on the safe side, only use this for testing pull request! 269 270 270 271 == Fixing bugs in a release branch == … … 328 329 }}} 329 330 330 === Backporting of a single commit from ma sterto release branch ===331 === Backporting of a single commit from main to release branch === 331 332 332 333 Assumptions: … … 361 362 }}} 362 363 363 Second, get commit hash from !GitHub or //git log// in master.364 365 Third, cherry-pick the change from ma sterinto the branch:364 Second, get commit hash from !GitHub or //git log// in the main branch. 365 366 Third, cherry-pick the change from main into the branch: 366 367 367 368 {{{ … … 425 426 == Code review: generate a single diff for a PR with multiple commits == 426 427 427 To speed up reviewing of a PR with multiple commits by reading a single diff file, you may diff the branch against the branch origin point. For example, if you PR 28 is on local branch pr_28, branched from master, you can do:428 To speed up reviewing of a PR with multiple commits by reading a single diff file, you may diff the branch against the branch origin point. For example, if you PR 28 is on local branch pr_28, branched from the main branch, you can do: 428 429 429 430 {{{ … … 431 432 432 433 # note: with the three dots, it will only show diffs from changes on your side: 433 git diff ma ster...434 git diff main... 434 435 }}} 435 436 … … 452 453 === PR with multiple commits === 453 454 454 **Proposed**: it is a good idea to try to squash the accumulated commits in a PR before merging, especially if those are trivial fixes. 455 456 As an example, PRxx contains 5 commits. Esp. in case that several commits of them are trivial fixes that only add noise to the history, "squashing" those results in a cleaner history and, among other things, makes it easier to use `git bisect` and `git blame`. 457 458 Importantly, not always commits of each and every PR need to be squashed before merging. When extensive changes are being made, it often makes sense to keep them unsquashed (e.g. to make reviewing easier), but trivial fixes should still be squashed to the main commits. 459 460 === Citing co-authors in a git commit message === 461 462 For co-authors, it is suggested using `Co-authored-by` at the end of the commit message: 455 All commits for a PR are squashed into one commit when merging to the base branch (that is usually the main branch). If the individual commit messages are not usable as is for the commit message of this new commit, modify the PR description so that it is usable as a commit message when maintainers merge the PR. 456 457 You can have multiple commits in a PR or squash them depending on what you see as most appropriate, but usually multiple commits help certain aspects of the review. 458 459 === Citing co-authors in a Git commit message === 460 461 For co-authors, it is suggested using `Co-authored-by` at the end of the commit message with this syntax: 463 462 464 463 {{{ … … 474 473 * GDAL contributing: https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md 475 474 * Splitting a subfolder out into a new repository: https://help.github.com/en/github/using-git/splitting-a-subfolder-out-into-a-new-repository 475 * [wiki:Submitting/General#Commitmessages Submitting guidelines: Commit messages]
