└── 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 | ||
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 |
--------------------------------------------------------------------------------