blob: 4d32c7a09dd9eaa14b6f4ea9bb9d3daf3164c3d1 [file] [log] [blame]
Erik Faye-Lund4d066832020-06-12 20:09:42 +02001Source Code Repository
2======================
3
Erik Faye-Lund50e26e52020-09-29 18:57:33 +02004Mesa uses `Git <https://git-scm.com>`__ as its source code management
Erik Faye-Lund4d066832020-06-12 20:09:42 +02005system.
6
Erik Faye-Lund50e26e52020-09-29 18:57:33 +02007The master Git repository is hosted on
Erik Faye-Lund4d066832020-06-12 20:09:42 +02008`freedesktop.org <https://www.freedesktop.org>`__.
9
Erik Faye-Lundb1c16e52020-06-27 10:00:10 +020010You may access the repository either as an :ref:`anonymous
11user <anonymous>` (read-only) or as a :ref:`developer <developer>`
Erik Faye-Lund4d066832020-06-12 20:09:42 +020012(read/write).
13
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020014You may also `browse the main Mesa Git
Erik Faye-Lund4d066832020-06-12 20:09:42 +020015repository <https://gitlab.freedesktop.org/mesa/mesa>`__ and the `Mesa
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020016demos and tests Git
Erik Faye-Lund4d066832020-06-12 20:09:42 +020017repository <https://gitlab.freedesktop.org/mesa/demos>`__.
18
19.. _anonymous:
20
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020021Anonymous Git Access
Erik Faye-Lund4d066832020-06-12 20:09:42 +020022--------------------
23
24To get the Mesa sources anonymously (read-only):
25
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020026#. Install the Git software on your computer if needed.
Erik Faye-Lund4d066832020-06-12 20:09:42 +020027#. Get an initial, local copy of the repository with:
28
29 ::
30
31 git clone https://gitlab.freedesktop.org/mesa/mesa.git
32
33#. Later, you can update your tree from the master repository with:
34
35 ::
36
37 git pull origin
38
39#. If you also want the Mesa demos/tests repository:
40
41 ::
42
43 git clone https://gitlab.freedesktop.org/mesa/demos.git
44
45.. _developer:
46
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020047Developer Git Access
Erik Faye-Lund4d066832020-06-12 20:09:42 +020048--------------------
49
Erik Faye-Lund7ee8a3a2020-09-25 15:20:20 +020050If you wish to become a Mesa developer with GitLab merge privilege,
Erik Faye-Lund4d066832020-06-12 20:09:42 +020051please follow this procedure:
52
53#. Subscribe to the
54 `mesa-dev <https://lists.freedesktop.org/mailman/listinfo/mesa-dev>`__
55 mailing list.
Erik Faye-Lund5ee55b22020-06-27 10:21:45 +020056#. Start contributing to the project by :doc:`submitting
57 patches <submittingpatches>`. Specifically,
Erik Faye-Lund4d066832020-06-12 20:09:42 +020058
Erik Faye-Lund7ee8a3a2020-09-25 15:20:20 +020059 - Use `GitLab <https://gitlab.freedesktop.org/>`__ to create your
Erik Faye-Lund4d066832020-06-12 20:09:42 +020060 merge requests.
61 - Wait for someone to review the code and give you a ``Reviewed-by``
62 statement.
63 - You'll have to rely on another Mesa developer to push your initial
64 patches after they've been reviewed.
65
66#. After you've demonstrated the ability to write good code and have had
67 a dozen or so patches accepted, a maintainer may use their discretion
68 to give you access to merge your own code.
69
Erik Faye-Lund7ee8a3a2020-09-25 15:20:20 +020070Pushing code to your GitLab account via HTTPS
Erik Faye-Lund4d066832020-06-12 20:09:42 +020071---------------------------------------------
72
73Useful for people behind strict proxies
74
75You can use `personal access
76tokens <https://gitlab.freedesktop.org/profile/personal_access_tokens>`__
77to push over HTTPS if ssh will does not suit your needs. In this case,
Erik Faye-Lundb8f10752020-09-25 15:24:30 +020078create a token, and put it in the URL as shown here:
Erik Faye-Lund4d066832020-06-12 20:09:42 +020079
80::
81
82 git remote set-url --push origin https://USER:TOKEN@gitlab.freedesktop.org/your~user~name/mesa.git
83
84Windows Users
85-------------
86
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020087If you're `using Git on
Erik Faye-Lund4d066832020-06-12 20:09:42 +020088Windows <https://git.wiki.kernel.org/index.php/WindowsInstall>`__ you'll
89want to enable automatic CR/LF conversion in your local copy of the
90repository:
91
92::
93
94 git config --global core.autocrlf true
95
Erik Faye-Lund50e26e52020-09-29 18:57:33 +020096This will cause Git to convert all text files to CR+LF on checkout, and
Erik Faye-Lund4d066832020-06-12 20:09:42 +020097to LF on commit.
98
99Unix users don't need to set this option.
100
101Development Branches
102--------------------
103
104At any given time, there may be several active branches in Mesa's
105repository. Generally, ``master`` contains the latest development
106(unstable) code while a branch has the latest stable code.
107
108The command ``git branch`` will list all available branches.
109
110Questions about branch status/activity should be posted to the mesa-dev
111mailing list.
112
113Developer Git Tips
114------------------
115
116#. Setting up to edit the master branch
117
Erik Faye-Lund50e26e52020-09-29 18:57:33 +0200118 If you try to do a pull by just saying\ ``git pull`` and Git
Erik Faye-Lund4d066832020-06-12 20:09:42 +0200119 complains that you have not specified a branch, try:
120
121 ::
122
123 git config branch.master.remote origin
124 git config branch.master.merge master
125
126 Otherwise, you have to say\ ``git pull origin master`` each time you
127 do a pull.
128
129#. Small changes to master
130
Erik Faye-Lund50e26e52020-09-29 18:57:33 +0200131 If you are an experienced Git user working on substantial
Erik Faye-Lund4d066832020-06-12 20:09:42 +0200132 modifications, you are probably working on a separate branch and
133 would rebase your branch prior to merging with master. But for small
134 changes to the master branch itself, you also need to use the rebase
135 feature in order to avoid an unnecessary and distracting branch in
136 master.
137
138 If it has been awhile since you've done the initial clone, try
139
140 ::
141
142 git pull
143
144 to get the latest files before you start working.
145
146 Make your changes and use
147
148 ::
149
150 git add <files to commit>
151 git commit
152
153 to get your changes ready to push back into the fd.o repository.
154
155 It is possible (and likely) that someone has changed master since you
156 did your last pull. Even if your changes do not conflict with their
Erik Faye-Lund50e26e52020-09-29 18:57:33 +0200157 changes, Git will make a fast-forward merge branch, branching from
Erik Faye-Lund4d066832020-06-12 20:09:42 +0200158 the point in time where you did your last pull and merging it to a
159 point after the other changes.
160
161 To avoid this,
162
163 ::
164
165 git pull --rebase
166 git push
167
168 If you are familiar with CVS or similar system, this is similar to
169 doing a ``cvs update`` in order to update your source tree to the
170 current repository state, instead of the time you did the last
Erik Faye-Lund50e26e52020-09-29 18:57:33 +0200171 update. (CVS doesn't work like Git in this respect, but this is
Erik Faye-Lund4d066832020-06-12 20:09:42 +0200172 easiest way to explain it.)
173
174 In any case, your repository now looks like you made your changes
175 after all the other changes.
176
177 If the rebase resulted in conflicts or changes that could affect the
178 proper operation of your changes, you'll need to investigate those
179 before doing the push.
180
181 If you want the rebase action to be the default action, then
182
183 ::
184
185 git config branch.master.rebase true
186 git config --global branch.autosetuprebase=always
187
188 See `Understanding Git
189 Conceptually <https://www.eecs.harvard.edu/~cduan/technical/git/>`__
190 for a fairly clear explanation about all of this.