├── LICENSE ├── README.md └── assets ├── Git-branching-model.pdf ├── github-create-draft-pr.png ├── github-draft-pr.png └── github-sync.png /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution-ShareAlike 4.0 International Creative Commons 2 | Corporation ("Creative Commons") is not a law firm and does not provide legal 3 | services or legal advice. Distribution of Creative Commons public licenses 4 | does not create a lawyer-client or other relationship. Creative Commons makes 5 | its licenses and related information available on an "as-is" basis. Creative 6 | Commons gives no warranties regarding its licenses, any material licensed 7 | under their terms and conditions, or any related information. Creative Commons 8 | disclaims all liability for damages resulting from their use to the fullest 9 | extent possible. 10 | 11 | Using Creative Commons Public Licenses 12 | 13 | Creative Commons public licenses provide a standard set of terms and conditions 14 | that creators and other rights holders may use to share original works of 15 | authorship and other material subject to copyright and certain other rights 16 | specified in the public license below. The following considerations are for 17 | informational purposes only, are not exhaustive, and do not form part of our 18 | licenses. 19 | 20 | Considerations for licensors: Our public licenses are intended for use by 21 | those authorized to give the public permission to use material in ways otherwise 22 | restricted by copyright and certain other rights. Our licenses are irrevocable. 23 | Licensors should read and understand the terms and conditions of the license 24 | they choose before applying it. Licensors should also secure all rights necessary 25 | before applying our licenses so that the public can reuse the material as 26 | expected. Licensors should clearly mark any material not subject to the license. 27 | This includes other CC-licensed material, or material used under an exception 28 | or limitation to copyright. More considerations for licensors : wiki.creativecommons.org/Considerations_for_licensors 29 | 30 | Considerations for the public: By using one of our public licenses, a licensor 31 | grants the public permission to use the licensed material under specified 32 | terms and conditions. If the licensor's permission is not necessary for any 33 | reason–for example, because of any applicable exception or limitation to copyright–then 34 | that use is not regulated by the license. Our licenses grant only permissions 35 | under copyright and certain other rights that a licensor has authority to 36 | grant. Use of the licensed material may still be restricted for other reasons, 37 | including because others have copyright or other rights in the material. A 38 | licensor may make special requests, such as asking that all changes be marked 39 | or described. 40 | 41 | Although not required by our licenses, you are encouraged to respect those 42 | requests where reasonable. More considerations for the public : wiki.creativecommons.org/Considerations_for_licensees 43 | 44 | Creative Commons Attribution-ShareAlike 4.0 International Public License 45 | 46 | By exercising the Licensed Rights (defined below), You accept and agree to 47 | be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 48 | 4.0 International Public License ("Public License"). To the extent this Public 49 | License may be interpreted as a contract, You are granted the Licensed Rights 50 | in consideration of Your acceptance of these terms and conditions, and the 51 | Licensor grants You such rights in consideration of benefits the Licensor 52 | receives from making the Licensed Material available under these terms and 53 | conditions. 54 | 55 | Section 1 – Definitions. 56 | 57 | a. Adapted Material means material subject to Copyright and Similar Rights 58 | that is derived from or based upon the Licensed Material and in which the 59 | Licensed Material is translated, altered, arranged, transformed, or otherwise 60 | modified in a manner requiring permission under the Copyright and Similar 61 | Rights held by the Licensor. For purposes of this Public License, where the 62 | Licensed Material is a musical work, performance, or sound recording, Adapted 63 | Material is always produced where the Licensed Material is synched in timed 64 | relation with a moving image. 65 | 66 | b. Adapter's License means the license You apply to Your Copyright and Similar 67 | Rights in Your contributions to Adapted Material in accordance with the terms 68 | and conditions of this Public License. 69 | 70 | c. BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, 71 | approved by Creative Commons as essentially the equivalent of this Public 72 | License. 73 | 74 | d. Copyright and Similar Rights means copyright and/or similar rights closely 75 | related to copyright including, without limitation, performance, broadcast, 76 | sound recording, and Sui Generis Database Rights, without regard to how the 77 | rights are labeled or categorized. For purposes of this Public License, the 78 | rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 79 | 80 | e. Effective Technological Measures means those measures that, in the absence 81 | of proper authority, may not be circumvented under laws fulfilling obligations 82 | under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, 83 | and/or similar international agreements. 84 | 85 | f. Exceptions and Limitations means fair use, fair dealing, and/or any other 86 | exception or limitation to Copyright and Similar Rights that applies to Your 87 | use of the Licensed Material. 88 | 89 | g. License Elements means the license attributes listed in the name of a Creative 90 | Commons Public License. The License Elements of this Public License are Attribution 91 | and ShareAlike. 92 | 93 | h. Licensed Material means the artistic or literary work, database, or other 94 | material to which the Licensor applied this Public License. 95 | 96 | i. Licensed Rights means the rights granted to You subject to the terms and 97 | conditions of this Public License, which are limited to all Copyright and 98 | Similar Rights that apply to Your use of the Licensed Material and that the 99 | Licensor has authority to license. 100 | 101 | j. Licensor means the individual(s) or entity(ies) granting rights under this 102 | Public License. 103 | 104 | k. Share means to provide material to the public by any means or process that 105 | requires permission under the Licensed Rights, such as reproduction, public 106 | display, public performance, distribution, dissemination, communication, or 107 | importation, and to make material available to the public including in ways 108 | that members of the public may access the material from a place and at a time 109 | individually chosen by them. 110 | 111 | l. Sui Generis Database Rights means rights other than copyright resulting 112 | from Directive 96/9/EC of the European Parliament and of the Council of 11 113 | March 1996 on the legal protection of databases, as amended and/or succeeded, 114 | as well as other essentially equivalent rights anywhere in the world. 115 | 116 | m. You means the individual or entity exercising the Licensed Rights under 117 | this Public License. Your has a corresponding meaning. 118 | 119 | Section 2 – Scope. 120 | 121 | a. License grant. 122 | 123 | 1. Subject to the terms and conditions of this Public License, the Licensor 124 | hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, 125 | irrevocable license to exercise the Licensed Rights in the Licensed Material 126 | to: 127 | 128 | A. reproduce and Share the Licensed Material, in whole or in part; and 129 | 130 | B. produce, reproduce, and Share Adapted Material. 131 | 132 | 2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions 133 | and Limitations apply to Your use, this Public License does not apply, and 134 | You do not need to comply with its terms and conditions. 135 | 136 | 3. Term. The term of this Public License is specified in Section 6(a). 137 | 138 | 4. Media and formats; technical modifications allowed. The Licensor authorizes 139 | You to exercise the Licensed Rights in all media and formats whether now known 140 | or hereafter created, and to make technical modifications necessary to do 141 | so. The Licensor waives and/or agrees not to assert any right or authority 142 | to forbid You from making technical modifications necessary to exercise the 143 | Licensed Rights, including technical modifications necessary to circumvent 144 | Effective Technological Measures. For purposes of this Public License, simply 145 | making modifications authorized by this Section 2(a)(4) never produces Adapted 146 | Material. 147 | 148 | 5. Downstream recipients. 149 | 150 | A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed 151 | Material automatically receives an offer from the Licensor to exercise the 152 | Licensed Rights under the terms and conditions of this Public License. 153 | 154 | B. Additional offer from the Licensor – Adapted Material. Every recipient 155 | of Adapted Material from You automatically receives an offer from the Licensor 156 | to exercise the Licensed Rights in the Adapted Material under the conditions 157 | of the Adapter's License You apply. 158 | 159 | C. No downstream restrictions. You may not offer or impose any additional 160 | or different terms or conditions on, or apply any Effective Technological 161 | Measures to, the Licensed Material if doing so restricts exercise of the Licensed 162 | Rights by any recipient of the Licensed Material. 163 | 164 | 6. No endorsement. Nothing in this Public License constitutes or may be construed 165 | as permission to assert or imply that You are, or that Your use of the Licensed 166 | Material is, connected with, or sponsored, endorsed, or granted official status 167 | by, the Licensor or others designated to receive attribution as provided in 168 | Section 3(a)(1)(A)(i). 169 | 170 | b. Other rights. 171 | 172 | 1. Moral rights, such as the right of integrity, are not licensed under this 173 | Public License, nor are publicity, privacy, and/or other similar personality 174 | rights; however, to the extent possible, the Licensor waives and/or agrees 175 | not to assert any such rights held by the Licensor to the limited extent necessary 176 | to allow You to exercise the Licensed Rights, but not otherwise. 177 | 178 | 2. Patent and trademark rights are not licensed under this Public License. 179 | 180 | 3. To the extent possible, the Licensor waives any right to collect royalties 181 | from You for the exercise of the Licensed Rights, whether directly or through 182 | a collecting society under any voluntary or waivable statutory or compulsory 183 | licensing scheme. In all other cases the Licensor expressly reserves any right 184 | to collect such royalties. 185 | 186 | Section 3 – License Conditions. 187 | 188 | Your exercise of the Licensed Rights is expressly made subject to the following 189 | conditions. 190 | 191 | a. Attribution. 192 | 193 | 1. If You Share the Licensed Material (including in modified form), You must: 194 | 195 | A. retain the following if it is supplied by the Licensor with the Licensed 196 | Material: 197 | 198 | i. identification of the creator(s) of the Licensed Material and any others 199 | designated to receive attribution, in any reasonable manner requested by the 200 | Licensor (including by pseudonym if designated); 201 | 202 | ii. a copyright notice; 203 | 204 | iii. a notice that refers to this Public License; 205 | 206 | iv. a notice that refers to the disclaimer of warranties; 207 | 208 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 209 | 210 | B. indicate if You modified the Licensed Material and retain an indication 211 | of any previous modifications; and 212 | 213 | C. indicate the Licensed Material is licensed under this Public License, and 214 | include the text of, or the URI or hyperlink to, this Public License. 215 | 216 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner 217 | based on the medium, means, and context in which You Share the Licensed Material. 218 | For example, it may be reasonable to satisfy the conditions by providing a 219 | URI or hyperlink to a resource that includes the required information. 220 | 221 | 3. If requested by the Licensor, You must remove any of the information required 222 | by Section 3(a)(1)(A) to the extent reasonably practicable. 223 | 224 | b. ShareAlike.In addition to the conditions in Section 3(a), if You Share 225 | Adapted Material You produce, the following conditions also apply. 226 | 227 | 1. The Adapter's License You apply must be a Creative Commons license with 228 | the same License Elements, this version or later, or a BY-SA Compatible License. 229 | 230 | 2. You must include the text of, or the URI or hyperlink to, the Adapter's 231 | License You apply. You may satisfy this condition in any reasonable manner 232 | based on the medium, means, and context in which You Share Adapted Material. 233 | 234 | 3. You may not offer or impose any additional or different terms or conditions 235 | on, or apply any Effective Technological Measures to, Adapted Material that 236 | restrict exercise of the rights granted under the Adapter's License You apply. 237 | 238 | Section 4 – Sui Generis Database Rights. 239 | 240 | Where the Licensed Rights include Sui Generis Database Rights that apply to 241 | Your use of the Licensed Material: 242 | 243 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, 244 | reuse, reproduce, and Share all or a substantial portion of the contents of 245 | the database; 246 | 247 | b. if You include all or a substantial portion of the database contents in 248 | a database in which You have Sui Generis Database Rights, then the database 249 | in which You have Sui Generis Database Rights (but not its individual contents) 250 | is Adapted Material, including for purposes of Section 3(b); and 251 | 252 | c. You must comply with the conditions in Section 3(a) if You Share all or 253 | a substantial portion of the contents of the database. 254 | 255 | For the avoidance of doubt, this Section 4 supplements and does not replace 256 | Your obligations under this Public License where the Licensed Rights include 257 | other Copyright and Similar Rights. 258 | 259 | Section 5 – Disclaimer of Warranties and Limitation of Liability. 260 | 261 | a. Unless otherwise separately undertaken by the Licensor, to the extent possible, 262 | the Licensor offers the Licensed Material as-is and as-available, and makes 263 | no representations or warranties of any kind concerning the Licensed Material, 264 | whether express, implied, statutory, or other. This includes, without limitation, 265 | warranties of title, merchantability, fitness for a particular purpose, non-infringement, 266 | absence of latent or other defects, accuracy, or the presence or absence of 267 | errors, whether or not known or discoverable. Where disclaimers of warranties 268 | are not allowed in full or in part, this disclaimer may not apply to You. 269 | 270 | b. To the extent possible, in no event will the Licensor be liable to You 271 | on any legal theory (including, without limitation, negligence) or otherwise 272 | for any direct, special, indirect, incidental, consequential, punitive, exemplary, 273 | or other losses, costs, expenses, or damages arising out of this Public License 274 | or use of the Licensed Material, even if the Licensor has been advised of 275 | the possibility of such losses, costs, expenses, or damages. Where a limitation 276 | of liability is not allowed in full or in part, this limitation may not apply 277 | to You. 278 | 279 | c. The disclaimer of warranties and limitation of liability provided above 280 | shall be interpreted in a manner that, to the extent possible, most closely 281 | approximates an absolute disclaimer and waiver of all liability. 282 | 283 | Section 6 – Term and Termination. 284 | 285 | a. This Public License applies for the term of the Copyright and Similar Rights 286 | licensed here. However, if You fail to comply with this Public License, then 287 | Your rights under this Public License terminate automatically. 288 | 289 | b. Where Your right to use the Licensed Material has terminated under Section 290 | 6(a), it reinstates: 291 | 292 | 1. automatically as of the date the violation is cured, provided it is cured 293 | within 30 days of Your discovery of the violation; or 294 | 295 | 2. upon express reinstatement by the Licensor. 296 | 297 | c. For the avoidance of doubt, this Section 6(b) does not affect any right 298 | the Licensor may have to seek remedies for Your violations of this Public 299 | License. 300 | 301 | d. For the avoidance of doubt, the Licensor may also offer the Licensed Material 302 | under separate terms or conditions or stop distributing the Licensed Material 303 | at any time; however, doing so will not terminate this Public License. 304 | 305 | e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 306 | 307 | Section 7 – Other Terms and Conditions. 308 | 309 | a. The Licensor shall not be bound by any additional or different terms or 310 | conditions communicated by You unless expressly agreed. 311 | 312 | b. Any arrangements, understandings, or agreements regarding the Licensed 313 | Material not stated herein are separate from and independent of the terms 314 | and conditions of this Public License. 315 | 316 | Section 8 – Interpretation. 317 | 318 | a. For the avoidance of doubt, this Public License does not, and shall not 319 | be interpreted to, reduce, limit, restrict, or impose conditions on any use 320 | of the Licensed Material that could lawfully be made without permission under 321 | this Public License. 322 | 323 | b. To the extent possible, if any provision of this Public License is deemed 324 | unenforceable, it shall be automatically reformed to the minimum extent necessary 325 | to make it enforceable. If the provision cannot be reformed, it shall be severed 326 | from this Public License without affecting the enforceability of the remaining 327 | terms and conditions. 328 | 329 | c. No term or condition of this Public License will be waived and no failure 330 | to comply consented to unless expressly agreed to by the Licensor. 331 | 332 | d. Nothing in this Public License constitutes or may be interpreted as a limitation 333 | upon, or waiver of, any privileges and immunities that apply to the Licensor 334 | or You, including from the legal processes of any jurisdiction or authority. 335 | 336 | Creative Commons is not a party to its public licenses. Notwithstanding, Creative 337 | Commons may elect to apply one of its public licenses to material it publishes 338 | and in those instances will be considered the "Licensor." The text of the 339 | Creative Commons public licenses is dedicated to the public domain under the 340 | CC0 Public Domain Dedication. Except for the limited purpose of indicating 341 | that material is shared under a Creative Commons public license or as otherwise 342 | permitted by the Creative Commons policies published at creativecommons.org/policies, 343 | Creative Commons does not authorize the use of the trademark "Creative Commons" 344 | or any other trademark or logo of Creative Commons without its prior written 345 | consent including, without limitation, in connection with any unauthorized 346 | modifications to any of its public licenses or any other arrangements, understandings, 347 | or agreements concerning use of licensed material. For the avoidance of doubt, 348 | this paragraph does not form part of the public licenses. 349 | 350 | Creative Commons may be contacted at creativecommons.org. 351 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Git 101 2 | 3 | ## Configuration (global and project scope) 4 | 5 | ### Global gitconfig 6 | 7 | Configure non-default behavior once on a global scope to use it in all repositories. 8 | 9 | Create the file `~/.gitconfig` or `~/.config/git/config`. 10 | 11 | ```shell 12 | [user] 13 | email = andreas.bauer@bth.se 14 | name = Andreas Bauer 15 | [core] 16 | autocrlf = input 17 | excludesfile = ~/.gitignore 18 | ``` 19 | 20 | This settings can also be set via the `git config` command: 21 | 22 | ```shell 23 | git config --global user.name "Andreas Bauer" 24 | git config --global user.email andreas.bauer@bth.se 25 | ``` 26 | 27 | [Example global gitconfig](https://github.com/andreas-bauer/dotfiles/blob/master/gitconfig) 28 | 29 | For more information see the [official documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration). 30 | 31 | ### Repository gitconfig 32 | 33 | Sometimes you want to use a different email addresses in different repositories, 34 | e.g., one for work related repositories and one for private repositories. 35 | You can change (override) global settings on a repository level by 36 | using the `--local` parameter when setting git configs. 37 | 38 | ```shell 39 | git config --local user.email myname@work.com 40 | ``` 41 | 42 | You can check your local configuration by displaying the config file in the repository: 43 | 44 | ```shell 45 | cat .git/config 46 | ``` 47 | 48 | ## Gitignore 49 | 50 | ### Global gitignore file 51 | 52 | A global `.gitignore` file allows you to ignore files and directories in all 53 | Git repositories. 54 | This is especially useful when the OS creates files or directories that are not 55 | related to the Git project at all, 56 | like the `.DS_Store` files in macOS or `.Trash` folder in Linux. 57 | 58 | Create a `~/.gitignore` file and reference it in the global config (see example above). 59 | 60 | ```gitignore 61 | # KDE directory preferences 62 | .directory 63 | 64 | # Linux trash folder 65 | .Trash-* 66 | 67 | # macOS DS_Store files 68 | .DS_Store 69 | ``` 70 | 71 | [Example global gitignore file](https://github.com/andreas-bauer/dotfiles/blob/master/gitignore) 72 | 73 | ### Gitignore templates 74 | 75 | If you are not sure what the `.gitignore` file for a specific language/technology 76 | should contain you either can use a generator or existing templates. 77 | 78 | - [gitignore-generator](https://mrkandreev.name/snippets/gitignore-generator/) 79 | - [collection of .gitignore templates](https://github.com/github/gitignore) 80 | 81 | ## Commits 82 | 83 | Git commits represent atomic changes of the codebase. 84 | You can commit staged files to the repository using `git commit`. 85 | 86 | If you want to add changes to a previous commit without creating a new commit 87 | you can use the `--ammend` argument. 88 | This is helpful if you want to fix a typo you missed in the previous commit. 89 | 90 | With the argument `--verbose` all changes will be presented as a diff and 91 | you will be able to write commit messages that consist of multiple lines. 92 | 93 | ```shell 94 | # stage a specific file 95 | git add README.md 96 | 97 | # stage all files that are not ignored 98 | git add * 99 | 100 | # stage all files of a folder 101 | git add src/ 102 | 103 | # stage parts of files for partial commits 104 | git add -p 105 | 106 | # create commit with a commit message 107 | git commit -m "Add CI workflow" 108 | 109 | # add changes to previous commit instead of creating a new commit 110 | git commit --amend 111 | 112 | # show the full diff of the changes before commting 113 | git commit --verbose 114 | 115 | ``` 116 | 117 | ## Commit size 118 | 119 | Big changes are hard to understand and review by other developers. 120 | Therefore, you should make multiple small commits instead of one big commit. 121 | These commits should also follow the Single Responsibility Principle (SRP) 122 | to further improve the understandability of changes. 123 | 124 | Best practices in code reviews regarding the size of code changes [1]: 125 | 126 | - "Keep code changes small." 127 | - "Keep one Pull Request per concern." 128 | 129 | Reference: 130 | 131 | [1] Dong, L., Zhang, H., Yang, L., Weng, Z., Yang, X., Zhou, X., & Pan, Z. (2021). 132 | Survey on Pains and Best Practices of Code Review. 133 | 2021 28th Asia-Pacific Software Engineering Conference (APSEC), 482–491. [https://doi.org/10.1109/APSEC53868.2021.00055](https://doi.org/10.1109/APSEC53868.2021.00055) 134 | 135 | ## Commit messages 136 | 137 | Good commit messages helps other developers to understand the changes in your codebase. 138 | Therefore, you should explain the what and the why of a change. 139 | Additionally, commit messages should be consistent to improve the readability. 140 | 141 | The commit message should be written in a way that it could 142 | complete the following sentence: 143 | 144 | *If applied, this commit will* `[commit message]`. 145 | 146 | Example: *If applied, this commit will* `Add Docker setup for server`. 147 | 148 | Some rules for good commit messages: 149 | 150 | - Keep subject line short (50 chars) 151 | - Consistent capitalization (preferred 'Refactor …' instead of 'refactor …') 152 | - Imperative mood ('Add' instead of 'added') 153 | 154 | If you want to incorporate more information in a commit message use 155 | the following format: 156 | 157 | ```txt 158 | Add Docker setup for server 159 | 160 | * add Dockerfile 161 | * add docker-compose file 162 | * remove obsolete Makefile 163 | ``` 164 | 165 | or 166 | 167 | ```txt 168 | Add Docker setup for server 169 | 170 | The Docker setup will simplify the handling of the dev and prod environment. 171 | 172 | ``` 173 | 174 | If you are working with issues (GitHub, Jira, etc.), 175 | you should reference the issue if the commit closes an issue. 176 | This helps to trace issues through the development process 177 | and gives the commit message more contextual information (why the change). 178 | 179 | Example: `Add validation to email input field (closes issue #42)` 180 | 181 | Good blog article with further information: [https://cbea.ms/git-commit/](https://cbea.ms/git-commit/). 182 | 183 | ## Undo changes 184 | 185 | You can undo changes on tracked files that are not commited yet with `git restore`. 186 | 187 | ```shell 188 | # restore all files in the current folder and its sub-folders 189 | git restore . 190 | 191 | # restore specific files 192 | git restore README.md 193 | git restore src/ 194 | git restore '*.js' 195 | 196 | # unstage a staged file 197 | git restore --staged README.md 198 | ``` 199 | 200 | To remove untracked files from the repository use `git clean`. 201 | 202 | ```shell 203 | # remove all untracked files in the tracked directories 204 | git clean -f 205 | 206 | # remove also all files from untracked directories 207 | git clean -d -f 208 | ``` 209 | 210 | ## Fix ups (rebase) 211 | 212 | A clean Git commit history helps to better understand the changes on the codebase. 213 | Commits that only fix other commits bloating the commit history. 214 | Typical examples are typo or code style fixes. 215 | 216 | ```shell 217 | # BAD: The Git history is cluttered with commits that fix previous commits 218 | # git commit history (git log) 219 | # * 8d3f6c2 (HEAD -> main) Change title 220 | # * 632d1a5 Fix linter issues for introduction section 221 | # * 9a1a989 Fix typos in introduction section 222 | # * adfe739 Add license section 223 | # * f37396e Add introduction section 224 | ``` 225 | 226 | To maintain a clean Git commit history, you should mark fix commits with the 227 | `--fixup` argument and rebase the branch. 228 | Whereas fixup expects a reference (hash) to a previous commit. 229 | 230 | ```shell 231 | # create a fixup for commit f37396e 232 | git commit --fixup f37396e 233 | 234 | # git commit history (git log) 235 | # * 8d3f6c2 (HEAD -> main) Change title 236 | # * 632d1a5 Fixup! add introduction section 237 | # * 9a1a989 Fixup! add introduction section 238 | # * adfe739 Add license section 239 | # * f37396e Add introduction section 240 | 241 | # rebase last 4 commits 242 | git rebase --autosquash --interactive HEAD~4 243 | 244 | # Rebase resulted in a clean commit history 245 | # git commit history (git log) 246 | # * 8d3f6c2 (HEAD -> main) Change title 247 | # * adfe739 Add license section 248 | # * f37396e Add introduction section 249 | ``` 250 | 251 | ❗️Don't rebase already pushed commits. 252 | 253 | ## Aliases 254 | 255 | Make you life easier by creating aliases for often used Git commands. 256 | 257 | ```bash 258 | alias gs='git status' 259 | alias ga='git add ' 260 | alias gb='git branch ' 261 | alias gc='git commit --verbose' 262 | alias gd='git diff' 263 | alias gco='git checkout ' 264 | alias gl='git log --graph --decorate --pretty=oneline --abbrev-commit' 265 | alias gr='git restore ' 266 | ``` 267 | 268 | Add Linux aliases to your shell configuration: 269 | 270 | - Bash shell: `~/.bashrc` 271 | - Zsh shell: `~/.zshrc` 272 | - Fish shell: `~/.config/fish/config.fish` 273 | 274 | [My git aliases](https://github.com/andreas-bauer/dotfiles/blob/1140290787b326b5b685cc68ee63955d4f633de4/zsh/aliases.zsh#L50) 275 | 276 | Git itself has a build-in support for aliases. 277 | 278 | ```shell 279 | # configuration 280 | git config --global alias.co checkout 281 | 282 | # usage 283 | git co 284 | ``` 285 | 286 | For more information about aliases in Git see the [official documentation](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). 287 | 288 | ## Workflows with GitHub 289 | 290 | ### Working in branches 291 | 292 | Git enables complex branching models as demonstrated [here](./assets/Git-branching-model.pdf), 293 | but you shouldn't introduce a complex branching model in your project if not necessary. 294 | 295 | A simple branching strategy based on `dev` and `feature` branches is sufficient 296 | in most cases. 297 | 298 | In a `dev` (development) branch … 299 | 300 | ```mermaid 301 | gitGraph 302 | commit 303 | branch dev 304 | commit 305 | checkout main 306 | merge dev 307 | checkout dev 308 | commit 309 | commit 310 | checkout main 311 | merge dev 312 | checkout dev 313 | commit 314 | checkout main 315 | merge dev 316 | ``` 317 | 318 | *With a feature branch workflow* all development happens in 319 | dedicated branches instead of the `main` branch. 320 | 321 | ```mermaid 322 | gitGraph 323 | commit 324 | commit 325 | branch feature-1 326 | branch feature-2 327 | checkout feature-2 328 | commit 329 | checkout feature-1 330 | commit 331 | commit 332 | checkout main 333 | merge feature-1 334 | checkout feature-2 335 | commit 336 | checkout main 337 | merge feature-2 338 | commit 339 | branch bugfix 340 | commit 341 | checkout main 342 | merge bugfix 343 | ``` 344 | 345 | Feature branches should … 346 | 347 | - have a clear focus or purpose (single-responsibility principle) 348 | - be small 349 | - have a short lifetime 350 | - be tested before merged into the `main` branch 351 | - be merged via a pull requests 352 | 353 | This allows a collaborative workflow based on pull requests with code reviews. 354 | 355 | ### Pull requests / merge requests 356 | 357 | Github allows three different types to merge pull requests 358 | that impact the Git history in different ways. 359 | 360 | - Merge commit 361 | - Rebase and merge 362 | - Squash and merge 363 | 364 | To demonstrate the differences in merge outcome we will use the following setup: 365 | A feature branch with multiple commits shall be merged into the main branch. 366 | 367 | ```mermaid 368 | gitGraph 369 | commit id:"a" 370 | commit id:"b" 371 | branch feature 372 | checkout feature 373 | commit id:"c" type: HIGHLIGHT 374 | commit id:"d" type: HIGHLIGHT 375 | checkout main 376 | ``` 377 | 378 | #### Merge commit 379 | 380 | The feature branch and its commits will be joined together with the main branch. 381 | 382 | - Github's default merge strategy 383 | - Git commit history is not as streamlined as with other merging strategies 384 | - uncomplicated roll back of features 385 | - default commit message “Merge pull request” is not helpful to understand changes 386 | 387 | ```mermaid 388 | gitGraph 389 | commit id:"a" 390 | commit id:"b" 391 | branch feature 392 | checkout feature 393 | commit id:"c" type: HIGHLIGHT 394 | commit id:"d" type: HIGHLIGHT 395 | checkout main 396 | merge feature 397 | ``` 398 | 399 | #### Rebase and merge 400 | 401 | All commits of the feature branch will be added to the 402 | main branch individually without a merge commit. 403 | 404 | - rewrites Git commit history 405 | - maintains a linear commit history 406 | - force-push is sometimes required due to the rewrite of the commit history 407 | - force-push on public repositories is not recommended 408 | - most flexible solution 409 | 410 | ```mermaid 411 | gitGraph 412 | commit id:"a" 413 | commit id:"b" 414 | commit id:"c" type: HIGHLIGHT 415 | commit id:"d" type: HIGHLIGHT 416 | ``` 417 | 418 | #### Squash and merge 419 | 420 | All commits of the feature branch will be squashed into a 421 | single commit that will be added to the main branch. 422 | 423 | - maintains a linear commit history 424 | - uncomplicated roll back of features 425 | - losing detailed commits in commit history 426 | - fine for small changes, but problematic for long-running branches 427 | 428 | ```mermaid 429 | gitGraph 430 | commit id:"a" 431 | commit id:"b" 432 | commit id:"cd" type: HIGHLIGHT 433 | ``` 434 | 435 | ### WIP (Draft) pull requests 436 | 437 | You can use a draft pull request to start an early discussion about a feature 438 | that is work-in-progress (WIP). 439 | Draft pull requests cannot be merged. 440 | 441 | When creating a pull request, select `Create draft pull request` (see screenshot). 442 | 443 | ![create draft pull request](./assets/github-create-draft-pr.png) 444 | 445 | After the author removes the draft status of the pull request, merging becomes possible. 446 | 447 | ![draft pull request](./assets/github-draft-pr.png) 448 | 449 | In Gitlab, the prefix `WIP:` marks merge requests (pull requests) as work-in-progress. 450 | 451 | ### Keep a fork up-to-date 452 | 453 | If you work on a repository fork, you need to fetch and merge upstream changes 454 | to keep your fork up-to-date with the repository you forked from. 455 | 456 | You can use GitHub's UI (see screenshot), or Git commands (see code snippet) 457 | to fetch and merge changes from the upstream repository. 458 | 459 | ![sync branch with fork](./assets/github-sync.png) 460 | 461 | ```shell 462 | # add fork as remote with the name "upstream" 463 | git remote add upstream https://github.com/andreas-bauer/git-101.git 464 | 465 | # to check all remote targets 466 | git remote -v 467 | 468 | # fetch changes from remote 469 | git fetch upstream 470 | 471 | # merge changes of a remote branch into the current branch 472 | git merge upstream/main 473 | 474 | ``` 475 | 476 | ### Commits by multiple authors 477 | 478 | In cases where multiple authors worked together on a commit 479 | , like it is the case with pair programming, 480 | only one person will be visible in the Git logs. 481 | To make contributions of other authors visible in the GitHub stats 482 | you can use the keyword `Co-authored-by:` as part of the commit message. 483 | 484 | This is especially useful in team-based student projects. 485 | 486 | Incorporate multiple author information in a commit message use 487 | the following format: 488 | 489 | ```txt 490 | Add integration tests for REST API 491 | 492 | Co-authored-by: NAME 493 | Co-authored-by: AUTHOR-NAME " 494 | ``` 495 | 496 | See the [GitHub Docs](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) for more information. 497 | 498 | ## License 499 | 500 | Copyright © 2022-2025 Andreas Bauer 501 | 502 | This work is licensed under [CC BY-SA 4.0](./LICENSE). 503 | -------------------------------------------------------------------------------- /assets/Git-branching-model.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andreas-bauer/git-101/ac8b9a1bc83be55cb31e61038725d1fc216fdfaa/assets/Git-branching-model.pdf -------------------------------------------------------------------------------- /assets/github-create-draft-pr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andreas-bauer/git-101/ac8b9a1bc83be55cb31e61038725d1fc216fdfaa/assets/github-create-draft-pr.png -------------------------------------------------------------------------------- /assets/github-draft-pr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andreas-bauer/git-101/ac8b9a1bc83be55cb31e61038725d1fc216fdfaa/assets/github-draft-pr.png -------------------------------------------------------------------------------- /assets/github-sync.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andreas-bauer/git-101/ac8b9a1bc83be55cb31e61038725d1fc216fdfaa/assets/github-sync.png --------------------------------------------------------------------------------