├── .gitignore ├── README.md ├── commit-description.png └── iojs-by.png /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Git Style Guide 3 | 4 | Git style guide. 5 | This is personally how I use git, 6 | which is similar to the Express and the iojs teams' style. 7 | 8 | ## Anti-Patterns 9 | 10 | ### `Merge branch 'master' into branch 'master'` 11 | 12 | If you ever see a commit that merges a branch into itself, 13 | just run `git rebase` and it will clean itself up. 14 | 15 | ### `Merge branch 'master' into branch ...` 16 | 17 | If you're merging a parent branch into a branch and see this commit, you merged wrong. 18 | Type `git rebase master` (or whatever the master branch is) to get rid of this commit. 19 | 20 | ## Merging 21 | 22 | ### Avoid pressing the big green button 23 | 24 | If possible, don't click the big green "Merge Pull Request" button. 25 | Doing so creates a `Merge branch...` commit, which is noisy. 26 | 27 | However, if you do this, you should always reference issues that 28 | this commit solves in the commit title or description. 29 | 30 | ### Add the "committed by" message to each merge 31 | 32 | ![](iojs-by.png) 33 | 34 | - This is much cleaner than having commits that say "Merge Pull Request". 35 | - All commits will be in the order in which they are committed. 36 | When you "merge" them, they are ordered by the date they are authored (technically no, but that's how it looks). 37 | - It looks nice. 38 | 39 | There are a couple of ways to add this: 40 | 41 | - `git rebase` - only when you replay the commits, which is not always the case if the merged branch is already fast-forwarded. 42 | - `git commit --amend` 43 | 44 | ### Amend the commits 45 | 46 | So that they adhere to your styles: 47 | 48 | - Any style changes. 49 | - Change the commit message. 50 | - Edit the commit description. 51 | - Add any relevant links to the commit, such as links to the PR, issues, or information. 52 | - Add a description. 53 | - Add who else reviewed your commit. 54 | 55 | ![](commit-description.png) 56 | 57 | ### `git merge --squash` 58 | 59 | When merging your own branch, you could use `git merge --squash` to squash all your commits. 60 | I only say "merging your own branch" because doing so replaces the original author with you. 61 | Thus, you are unable to properly assign blame. 62 | 63 | ### Rebase and merge 64 | 65 | My personaly way of merging branches is the following: 66 | 67 | Checkout the branch, rebase, and force push: 68 | 69 | ```bash 70 | git checkout master 71 | git pull 72 | 73 | git checkout feature 74 | # Maybe squash and amend 75 | git rebase master 76 | git push -f 77 | ``` 78 | 79 | If rebase does nothing, just do a `git commit --amend`. 80 | 81 | The main reason is that you'd want the commits you merge to match the commits in the branch exactly. 82 | This will tell GitHub to automatically close the pull request when you merge it like so: 83 | 84 | ```bash 85 | git checkout master 86 | git merge feature 87 | git push 88 | ``` 89 | 90 | ## Branching 91 | 92 | ### `git rebase master` all day every day 93 | 94 | Don't diverge from your main branch as your problems will only exponentiate. 95 | 96 | ```bash 97 | git rebase master 98 | git push -f 99 | ``` 100 | 101 | ### Squash frequently 102 | 103 | Squash your commits frequently, but you should always squash it before merging. 104 | You do not want or need your working commits (ex. a commit adding logs, another removing them) 105 | in master as it's noisy and effectively negates itself. 106 | Squash them out! 107 | 108 | Another good reason to squash often is to make rebasing easy. 109 | If you have a lot of commits, each commit is a potential merge conflict. 110 | When you only have a single commit, you only need to do merge conflict resolution once! 111 | 112 | ### `git push -f` to only branches you own 113 | 114 | Make sure you only push to the current branch! 115 | There's a git config option for this, I don't remember what it was. 116 | You do not want to overwrite shared branches unless everyone else knows! 117 | 118 | ## Committing 119 | 120 | ### Prefix the commit message with the submodule 121 | 122 | For example, `readme: adding docs on stuff`. 123 | 124 | ### List which issues and PRs this commit solves 125 | 126 | For example, `closes #56 closes #57`. 127 | When the commit gets merged, 128 | GitHub will know to automatically close these issues. 129 | If you're working in a repository that is a fork or is expected to be a fork, 130 | expand the issue like `closes jonathanong/git-style-guide#56`. 131 | 132 | ### Add emojis to your commit messages! 133 | 134 | For example: 135 | 136 | > deps: :arrow_up: koa@~0.16.0 137 | 138 | Set a standard for your team. 139 | Currently, I only do arrows for dependency changes. 140 | It makes git way more fun! 141 | 142 | ## Creating Pull Requests 143 | 144 | ### Describe your pull request 145 | 146 | Make sure the maintainer knows what's going on. 147 | 148 | - What were the requirements and how were they satisfied? 149 | - What is some potential technical debt? 150 | - What would you like others to specifically review? 151 | - Who would you like to review this PR? `/cc` them or assign them. 152 | - Is this PR ready to merge or in progress? 153 | - What issues does it close? 154 | 155 | ### Open your pull request early 156 | 157 | Especially in teams where you want to know what others are working on. 158 | It also helps to have others look at your progress so they make sure you're not 159 | making any obvious mistakes and that you're on the right track. 160 | 161 | ### Don't change versions 162 | 163 | Let the maintainer do the versioning. 164 | The primary reason is that this commit could be included with other commits, 165 | which may warrant a different version. 166 | Thus, adding a commit that has a version in it makes everything more confusing. 167 | 168 | ### Rebase and Squash 169 | 170 | Always rebase your pull request so that it can be cleanly merged. 171 | 172 | Squash your commits appropriately - there should be as few as possible. 173 | There should not be any working commits, ex. 174 | commits where you add a log followed by another commit where they're removed. 175 | There should not be any "merge" commits 176 | 177 | ## Merging Pull Requests 178 | 179 | ### Don't be pedantic 180 | 181 | If the pull request needs some minor touch ups, 182 | don't always bother asking the collaborator to fix every tiny detail. 183 | Sometimes it's just easier to make those changes yourself, then squash the 184 | commits so that they still have the credit. 185 | 186 | For example, don't be so finicky with style changes 187 | (you should lint in your CI testing service anyways) 188 | or phrasing. 189 | Just make those changes yourself. 190 | 191 | ### Don't be afraid to cherry-pick 192 | 193 | If a pull request includes commits you are not interested in, 194 | ex. version bump commits, then simply `cherry-pick` the commits 195 | you're interested in. The collaborator will still get credit 196 | and you don't have to bother asking the collaborator to "remove those commits". 197 | -------------------------------------------------------------------------------- /commit-description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jonathanong/git-style-guide/8283aa13064555e93dc74cc1b77c7909ad67bce4/commit-description.png -------------------------------------------------------------------------------- /iojs-by.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jonathanong/git-style-guide/8283aa13064555e93dc74cc1b77c7909ad67bce4/iojs-by.png --------------------------------------------------------------------------------