└── notes.md /notes.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | Git is a Version Control System, it records changes made to the files in your project in 'commits', 3 | snapshots of the state of the project. 4 | This allows you to keep a history of the development, to go back in time and check when this 5 | bug/feature was introduced, to share your code and easily work with other contributors. 6 | 7 | # Setup 8 | 9 | #### Installing on Linux 10 | If you're on Ubuntu, try `apt`: 11 | 12 | ```sh 13 | sudo apt install git 14 | ``` 15 | 16 | More details on other options can be found [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) 17 | 18 | #### Configuration 19 | 20 | *See [this](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) for Windows config* 21 | 22 | Now you'll want to set up git configuration. The global config file usually lives in `~/.gitconfig` 23 | for your user. You can download [this copy](#gitconfig) and adapt it for you. 24 | It also contains aliases and parameter we're going to go through later. 25 | 26 | Alternatively you can run these to set your email and name. 27 | Git is going to use them to define the author of the changes you introduce. 28 | 29 | ```sh 30 | git config --global user.name "John Doe" 31 | git config --global user.email johndoe@example.com 32 | ``` 33 | 34 | Git sometimes need text input and is going to open an editor for that. 35 | If you want Git to use another editor than your system default one, vim for example, you can run : 36 | 37 | ```sh 38 | git config --global core.editor vim 39 | ``` 40 | 41 | #### Github configuration 42 | Odoo code lives in various repositories in on Github, you'll need to log in to pull and push. 43 | If you want git to stop asking your password, you should [use ssh keys.](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) 44 | Note that it's only working when using SSH. In short, when cloning using the SSH url `git://..` instead of the HTTPS one. 45 | 46 | #### Extra tools 47 | In the following, we're going to go over the usage of Git from the command line. 48 | It's where you have the more options to work with and a good place to start learning git. 49 | It's also probably not the fastest, most user-friendly. 50 | You might want to have a look at what's possible with you IDE or 51 | [git gui](https://git-scm.com/docs/git-gui/), 52 | [lazygit](https://github.com/jesseduffield/lazygit). 53 | 54 | # Use 55 | #### Start 56 | To have git start tracking the files in a directory, you can use `git init`. 57 | It will initialize a git repository in the current folder. 58 | Otherwise, you can clone an existing repository with 59 | ```sh 60 | git clone https://github.com/libgit2/libgit2 61 | ``` 62 | 63 | #### Committing 64 | When in a git repository, files can be tracked or untracked. Git only bothers itself with tracked files. 65 | Tracked files themselves can be in different states, unmodified, modified, staged. 66 | In a usual wokflow, once we edited files, we stage those we want to commit with `git add path/to/file`. 67 | 68 | Then running `git commit` makes a commit. 69 | It open an editor for you to fill in the commit message 70 | (see [guidelines](https://www.odoo.com/documentation/14.0/developer/misc/other/guidelines.html#git) for commit messages) 71 | and when you close it, appends the new commit after the current one in the history tree. 72 | All the staged files are now unmodified (since this last commit). 73 | 74 | |![Relation between files states](https://git-scm.com/book/en/v2/images/lifecycle.png)| 75 | | :----: | 76 | | From [git-scm](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) | 77 | 78 | #### Branching 79 | After some development you end up with a chain of successives commits. 80 | The other contributor have a similar diverging branch, on their local repository. 81 | To figure out how to solve that, 82 | I'm inviting you to go through the *Introduction sequence* in **Main** and then the *Push & Pull* of 83 | the **Remote** tab on 84 | 85 | # Odoo workflow 86 | 87 | ## Rebasing 88 | At Odoo, we choose a rebase workflow, it means you should restrain from using `merge` in favor of `rebase`. 89 | This allows to have more linear, readable, history tree. 90 | 91 | 92 | In order to follow this guideline might also want to change `git pull` default behavior, 93 | forcing it to rebase instead of merging with : 94 | ```sh 95 | git config --global pull.rebase true 96 | ``` 97 | 98 | ### Branches 99 | In Odoo (and in many other places), some branches have special use and characteristics. 100 | You'll have to work with: 101 | 102 | #### Personal feature branche 103 | Branch containing your code. Usually named *odoo-version*\_*feature*\_*trigramme*. 104 | That's where you'll commit most if not all of your code. 105 | Once you have something that's worth sharing with the others, you can rebase it to the shared feature branch. 106 | 107 | ```sh 108 | git switch 15.0-feature-tri 109 | git rebase 15.0-feature-tri 15.0-feature 110 | ``` 111 | 112 | #### Shared feature branche 113 | It's the branch containing all the code for a feature, yours and other contributors. 114 | Usually named *odoo-version*\_*feature*. 115 | 116 | Once the feature is ready it's should be reviewed before going on preproduction. 117 | In order to do that, you should open a PR targeting the preproduction branch and add a reviewer. 118 | You've probably already read 119 | [Create your first PR](https://www.odoo.com/documentation/14.0/developer/howtos/rdtraining/16_guidelines_pr.html#create-your-first-pr) 120 | from the training, if not you can refer to it. 121 | 122 | Before **rebasing and merging** makes sure: 123 | - The PR has been approved 124 | - You squashed the development commits into one commit per feature, see (https://git-rebase.io/#squash), 125 | except in some cases where it makes sense keep several commits. 126 | - You check the other guidelines in the PR template 127 | 128 | 129 | After your PR has been reviewed, corrected and merged, it's a good idea to remove the now useless feature branch. 130 | Github has a convenient button for it on the PR page. This command would also do it. 131 | ```sh 132 | git push origin --delete 15.0-feature 133 | git push origin --delete 15.0-feature-tri 134 | ``` 135 | 136 | #### Production and preproduction branches 137 | Usually `main` is the production branch, the code running on the client Odoo instance. 138 | It may be behind `preproduction` by a few commits and **shouldn't diverge from it**, 139 | that is to say `preproduction` is a direct descendant of `main`. 140 | If it's not the case, it's a recipe for bad surprises when pushing code to production. 141 | 142 | 143 | The extra commits in the preproduction branch contains the development being tested before being pushed in production. 144 | These branches are sometime write protected and in any case you probably shouln't push unreviewed code on them. 145 | 146 | Two options to push in production: 147 | ##### Github PR 148 | If you have only one commit to merge is to open a PR and use the `Squash and merge` option from Github. 149 | ##### Fast-forwarding it. 150 | Again, for this to work `preproduction` and `main` shouldn't be diverging. 151 | If you're unsure test it locally without pushing, Git should tell you if it uses fast-forward. 152 | ```sh 153 | git rebase preproduction main 154 | ``` 155 | 156 | **What not to do :** 157 | For some reason `Rebase and merge` won't fast-forward and will always rewrite history, so it shouldn't be used. 158 | 159 | ### Branches on Odoo.sh 160 | If you're working on a project on Odoo.sh, you'll notice it lists the git branches under different categories. 161 | 162 | ##### Production 163 | Again, it's the code in production. 164 | 165 | ##### Staging 166 | These are branches that contains production data and some config, intended for testing. 167 | Usually the preproduction branch will also be a staged branch. 168 | Some feature branch might be staged during the development as well to get feedback from BAs or the client. 169 | 170 | Each time commits are pushed to a staging, Odoo.sh will update the staging thanks to a github Webhook 171 | 172 | ##### Development 173 | The rest of the branches. Odoo.sh will run tests on them for each push 174 | 175 | # Warnings 176 | 177 | #### Reformatting 178 | 179 | Reformatting whole files or code you're not writing will wreck the history and is a sure way to trigger merge conflicts 180 | with other contributors 181 | 182 | #### Rebasing and rewriting history 183 | Rebasing comes with caveats, 184 | if your branch has been published on the remote and other contributors are based on it, 185 | it's preferable not to rebase it. As you may have noticed in the branching tutorial, rebasing actually dupplicates commits. 186 | If a public branch is rebased the other contributors are still working on top of the old unrebased commits and it may 187 | cause hard to solve merge conflict farther down the line. 188 | 189 | This applies to amending and rewording commits as well, in short anything that rewrites history. 190 | An indication that the history has been rewritten is that some commit now have a different hash. 191 | 192 | In some cases rebasing doesn't actually rewrite history though, 193 | if no commits are modified (not amended and no ancestor changes), 194 | there is no need to. Git may simply fast-forward the branch pointer if needed. 195 | 196 | If you rewrite history of a pushed branch, you'll probably have to force push or git will reject the push. 197 | Now the issue again here is if someone else updated the same branch with their own commits, 198 | then your force push is going remove them from the branch and you might not even notice it. 199 | A solution is to use `git push --force-with-lease` instead. This will create a useful alias. 200 | ```sh 201 | git config --global alias.fpush 'push --force-with-lease' 202 | ``` 203 | 204 | 205 | If you follow the workflow as described above, it shouldn't be an issue: 206 | - Rebasing is fair game on your private feature branch, no one should be developing on it 207 | - Rebasing a feature branch at the end of development to preproduction is okay too, 208 | as the feature is finished, no one should still be working on it. 209 | - Rebasing the preproduction branch is okay as it's actually fast-forwarding. 210 | 211 | #### Making a mess 212 | It's hard to make something totally irrecuperable with git. 213 | Even if you're unsure feel free to experiment as long as you don't push on the remote. 214 | 215 | It is easier to go back to a previous state if you 216 | [create a backup branch](https://docs.gitlab.com/ee/topics/git/git_rebase.html#before-rebasing) 217 | before attempting a merge or a rebase. 218 | That being said, even if you forget to do it, 219 | and things go wrong you can probably retrieve the commits you're looking for with `git reflog`. 220 | 221 | # Further reading 222 | - The rest of the exercises from 223 | - Also see the game: 224 | - Git rebase in depth: 225 | - Man pages: 226 | - And the book: 227 | 228 | ## gitconfig 229 | ``` 230 | [user] 231 | email = tri@odoo.com 232 | name = Surname Name (tri) 233 | [alias] 234 | g = grep --break --heading --line-number 235 | lg = log --graph --pretty=tformat:'%Cred%h%Creset -%C(auto)%d%Creset %s %Cgreen(%an %ar)%Creset' 236 | hist = log --graph --date=short --pretty=tformat:'%Cred%h%Creset %Cgreen%ad%Creset | %C(auto)%d%Creset %s %Cgreen(%an)%Creset' --all 237 | fpush = push --force-with-lease 238 | [pull] 239 | rebase = true 240 | ``` 241 | 242 | 243 | --------------------------------------------------------------------------------