├── CONTRIBUTING.md ├── LICENSE.md └── README.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Hello and thank you for looking to improve the Git Style Guide. 2 | 3 | * If you want to translate the style guide, fork the repository and add your 4 | translation in your fork (edit `README.md`). Then open a pull request that adds the link to your fork (note that languages are listed alphabetically). 5 | * Please follow the [style guide](README.md)! 6 | 7 | Thanks! 8 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Git Style Guide 2 | 3 | This is a Git Style Guide inspired by [*How to Get Your Change Into the Linux 4 | Kernel*](https://kernel.org/doc/html/latest/process/submitting-patches.html), 5 | the [git man pages](http://git-scm.com/doc) and various practices popular 6 | among the community. 7 | 8 | Translations are available in the following languages: 9 | 10 | * [Chinese (Simplified)](https://github.com/aseaday/git-style-guide) 11 | * [Chinese (Traditional)](https://github.com/JuanitoFatas/git-style-guide) 12 | * [French](https://github.com/pierreroth64/git-style-guide) 13 | * [Georgian](https://github.com/davidkadaria/git-style-guide) 14 | * [German](https://github.com/runjak/git-style-guide) 15 | * [Greek](https://github.com/grigoria/git-style-guide) 16 | * [Italian](https://github.com/vincendep/git-style-guide) 17 | * [Japanese](https://github.com/objectx/git-style-guide) 18 | * [Korean](https://github.com/ikaruce/git-style-guide) 19 | * [Polish](https://github.com/mbiesiad/git-style-guide/tree/pl_PL) 20 | * [Portuguese](https://github.com/guylhermetabosa/git-style-guide) 21 | * [Russian](https://github.com/alik0211/git-style-guide) 22 | * [Spanish](https://github.com/jeko2000/git-style-guide) 23 | * [Thai](https://github.com/zondezatera/git-style-guide) 24 | * [Turkish](https://github.com/CnytSntrk/git-style-guide) 25 | * [Ukrainian](https://github.com/denysdovhan/git-style-guide) 26 | 27 | If you feel like contributing, please do so! Fork the project and open a pull 28 | request. 29 | 30 | # Table of contents 31 | 32 | 1. [Branches](#branches) 33 | 2. [Commits](#commits) 34 | 1. [Messages](#messages) 35 | 3. [Merging](#merging) 36 | 4. [Misc.](#misc) 37 | 38 | ## Branches 39 | 40 | * Choose *short* and *descriptive* names: 41 | 42 | ```shell 43 | # good 44 | $ git checkout -b oauth-migration 45 | 46 | # bad - too vague 47 | $ git checkout -b login_fix 48 | ``` 49 | 50 | * Identifiers from corresponding tickets in an external service (eg. a GitHub 51 | issue) are also good candidates for use in branch names. For example: 52 | 53 | ```shell 54 | # GitHub issue #15 55 | $ git checkout -b issue-15 56 | ``` 57 | 58 | * Use lowercase in branch names. External ticket identifiers with uppercase 59 | letters are a valid exception. Use *hyphens* to separate words. 60 | 61 | ```shell 62 | $ git checkout -b new-feature # good 63 | $ git checkout -b T321-new-feature # good (Phabricator task id) 64 | $ git checkout -b New_Feature # bad 65 | ``` 66 | 67 | * When several people are working on the *same* feature, it might be convenient 68 | to have *personal* feature branches and a *team-wide* feature branch. 69 | Use the following naming convention: 70 | 71 | ```shell 72 | $ git checkout -b feature-a/main # team-wide branch 73 | $ git checkout -b feature-a/maria # Maria's personal branch 74 | $ git checkout -b feature-a/nick # Nick's personal branch 75 | ``` 76 | 77 | Merge at will the personal branches to the team-wide branch (see ["Merging"](#merging)). 78 | Eventually, the team-wide branch will be merged to "main". 79 | 80 | * Delete your branch from the upstream repository after it's merged, unless 81 | there is a specific reason not to. 82 | 83 | Tip: Use the following command while being on "main", to list merged 84 | branches: 85 | 86 | ```shell 87 | $ git branch --merged | grep -v "\*" 88 | ``` 89 | 90 | ## Commits 91 | 92 | * Each commit should be a single *logical change*. Don't make several 93 | *logical changes* in one commit. For example, if a patch fixes a bug and 94 | optimizes the performance of a feature, split it into two separate commits. 95 | 96 | *Tip: Use `git add -p` to interactively stage specific portions of the 97 | modified files.* 98 | 99 | * Don't split a single *logical change* into several commits. For example, 100 | the implementation of a feature and the corresponding tests should be in the 101 | same commit. 102 | 103 | * Commit *early* and *often*. Small, self-contained commits are easier to 104 | understand and revert when something goes wrong. 105 | 106 | * Commits should be ordered *logically*. For example, if *commit X* depends 107 | on changes done in *commit Y*, then *commit Y* should come before *commit X*. 108 | 109 | Note: While working alone on a local branch that *has not yet been pushed*, it's 110 | fine to use commits as temporary snapshots of your work. However, it still 111 | holds true that you should apply all of the above *before* pushing it. 112 | 113 | ### Messages 114 | 115 | * Use the editor, not the terminal, when writing a commit message: 116 | 117 | ```shell 118 | # good 119 | $ git commit 120 | 121 | # bad 122 | $ git commit -m "Quick fix" 123 | ``` 124 | 125 | Committing from the terminal encourages a mindset of having to fit everything 126 | in a single line which usually results in non-informative, ambiguous commit 127 | messages. 128 | 129 | * The summary line (ie. the first line of the message) should be 130 | *descriptive* yet *succinct*. Ideally, it should be no longer than 131 | *50 characters*. It should be capitalized and written in imperative present 132 | tense. It should not end with a period since it is effectively the commit 133 | *title*: 134 | 135 | ```shell 136 | # good - imperative present tense, capitalized, fewer than 50 characters 137 | Mark huge records as obsolete when clearing hinting faults 138 | 139 | # bad 140 | fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails. 141 | ``` 142 | 143 | * After that should come a blank line followed by a more thorough 144 | description. It should be wrapped to *72 characters* and explain *why* 145 | the change is needed, *how* it addresses the issue and what *side-effects* 146 | it might have. 147 | 148 | It should also provide any pointers to related resources (eg. link to the 149 | corresponding issue in a bug tracker): 150 | 151 | ```text 152 | Short (50 chars or fewer) summary of changes 153 | 154 | More detailed explanatory text, if necessary. Wrap it to 155 | 72 characters. In some contexts, the first 156 | line is treated as the subject of an email and the rest of 157 | the text as the body. The blank line separating the 158 | summary from the body is critical (unless you omit the body 159 | entirely); tools like rebase can get confused if you run 160 | the two together. 161 | 162 | Further paragraphs come after blank lines. 163 | 164 | - Bullet points are okay, too 165 | 166 | - Use a hyphen or an asterisk for the bullet, 167 | followed by a single space, with blank lines in 168 | between 169 | 170 | The pointers to your related resources can serve as a footer 171 | for your commit message. Here is an example that is referencing 172 | issues in a bug tracker: 173 | 174 | Resolves: #56, #78 175 | See also: #12, #34 176 | 177 | Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 178 | ``` 179 | 180 | Ultimately, when writing a commit message, think about what you would need 181 | to know if you run across the commit in a year from now. 182 | 183 | * If a *commit A* depends on *commit B*, the dependency should be 184 | stated in the message of *commit A*. Use the SHA1 when referring to 185 | commits. 186 | 187 | Similarly, if *commit A* solves a bug introduced by *commit B*, it should 188 | also be stated in the message of *commit A*. 189 | 190 | * If a commit is going to be squashed to another commit use the `--squash` and 191 | `--fixup` flags respectively, in order to make the intention clear: 192 | 193 | ```shell 194 | $ git commit --squash f387cab2 195 | ``` 196 | 197 | *(Tip: Use the `--autosquash` flag when rebasing. The marked commits will be 198 | squashed automatically.)* 199 | 200 | ## Merging 201 | 202 | * **Do not rewrite published history.** The repository's history is valuable in 203 | its own right and it is very important to be able to tell *what actually 204 | happened*. Altering published history is a common source of problems for 205 | anyone working on the project. 206 | 207 | * However, there are cases where rewriting history is legitimate. These are 208 | when: 209 | 210 | * You are the only one working on the branch and it is not being reviewed. 211 | 212 | * You want to tidy up your branch (eg. squash commits) and/or rebase it onto 213 | the "main" in order to merge it later. 214 | 215 | That said, *never rewrite the history of the "main" branch* or any other 216 | special branches (ie. used by production or CI servers). 217 | 218 | * Keep the history *clean* and *simple*. *Just before you merge* your branch: 219 | 220 | 1. Make sure it conforms to the style guide and perform any needed actions 221 | if it doesn't (squash/reorder commits, reword messages etc.) 222 | 223 | 2. Rebase it onto the branch it's going to be merged to: 224 | 225 | ```shell 226 | [my-branch] $ git fetch 227 | [my-branch] $ git rebase origin/main 228 | # then merge 229 | ``` 230 | 231 | This results in a branch that can be applied directly to the end of the 232 | "main" branch and results in a very simple history. 233 | 234 | *(Note: This strategy is better suited for projects with short-running 235 | branches. Otherwise it might be better to occassionally merge the 236 | "main" branch instead of rebasing onto it.)* 237 | 238 | * If your branch includes more than one commit, do not merge with a 239 | fast-forward: 240 | 241 | ```shell 242 | # good - ensures that a merge commit is created 243 | $ git merge --no-ff my-branch 244 | 245 | # bad 246 | $ git merge my-branch 247 | ``` 248 | 249 | ## Misc. 250 | 251 | * There are various workflows and each one has its strengths and weaknesses. 252 | Whether a workflow fits your case, depends on the team, the project and your 253 | development procedures. 254 | 255 | That said, it is important to actually *choose* a workflow and stick with it. 256 | 257 | * *Be consistent.* This is related to the workflow but also expands to things 258 | like commit messages, branch names and tags. Having a consistent style 259 | throughout the repository makes it easy to understand what is going on by 260 | looking at the log, a commit message etc. 261 | 262 | * *Test before you push.* Do not push half-done work. 263 | 264 | * Use [annotated tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags) 265 | for marking releases or other important points in the history. Prefer 266 | [lightweight tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_lightweight_tags) 267 | for personal use, such as to bookmark commits for future reference. 268 | 269 | * Keep your repositories at a good shape by performing maintenance tasks 270 | occasionally: 271 | 272 | * [`git-gc(1)`](http://git-scm.com/docs/git-gc) 273 | * [`git-prune(1)`](http://git-scm.com/docs/git-prune) 274 | * [`git-fsck(1)`](http://git-scm.com/docs/git-fsck) 275 | 276 | # License 277 | 278 | ![cc license](http://i.creativecommons.org/l/by/4.0/88x31.png) 279 | 280 | This work is licensed under a [Creative Commons Attribution 4.0 281 | International license](https://creativecommons.org/licenses/by/4.0/). 282 | 283 | # Credits 284 | 285 | Agis Anastasopoulos / [@agisanast](https://twitter.com/agisanast) / http://agis.io 286 | ... and [contributors](https://github.com/agis-/git-style-guide/graphs/contributors)! 287 | --------------------------------------------------------------------------------