1Source Code Repository 2====================== 3 4Mesa uses `Git <https://git-scm.com>`__ as its source code management 5system. 6 7The upstream Git repository is hosted on 8`freedesktop.org <https://www.freedesktop.org>`__. 9 10You may access the repository either as an :ref:`anonymous 11user <anonymous>` (read-only) or as a :ref:`developer <developer>` 12(read/write). 13 14You may also `browse the main Mesa Git 15repository <https://gitlab.freedesktop.org/mesa/mesa>`__ and the `Mesa 16demos and tests Git 17repository <https://gitlab.freedesktop.org/mesa/demos>`__. 18 19.. _anonymous: 20 21Anonymous Git Access 22-------------------- 23 24To get the Mesa sources anonymously (read-only): 25 26#. Install the Git software on your computer if needed. 27#. Get an initial, local copy of the repository with: 28 29 .. code-block:: console 30 31 git clone https://gitlab.freedesktop.org/mesa/mesa.git 32 33#. Later, you can update your tree from the upstream repository with: 34 35 .. code-block:: console 36 37 git pull origin 38 39#. If you also want the Mesa demos/tests repository: 40 41 .. code-block:: console 42 43 git clone https://gitlab.freedesktop.org/mesa/demos.git 44 45.. _developer: 46 47Developer Git Access 48-------------------- 49 50If you wish to become a Mesa developer with GitLab merge privilege, 51please follow this procedure: 52 53#. Subscribe to the 54 `mesa-dev <https://lists.freedesktop.org/mailman/listinfo/mesa-dev>`__ 55 mailing list. 56#. Start contributing to the project by :doc:`submitting 57 patches <submittingpatches>`. Specifically, 58 59 - Use `GitLab <https://gitlab.freedesktop.org/>`__ to create your 60 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 70Pushing code to your GitLab account via HTTPS 71--------------------------------------------- 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 does not suit your needs. In this case, create 78a token, and put it in the URL as shown here: 79 80.. code-block:: console 81 82 git remote set-url --push origin https://USER:TOKEN@gitlab.freedesktop.org/your~user~name/mesa.git 83 84Windows Users 85------------- 86 87If you're `using Git on 88Windows <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.. code-block:: console 93 94 git config --global core.autocrlf true 95 96This will cause Git to convert all text files to CR+LF on checkout, and 97to 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, ``main`` 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 main branch 117 118 If you try to do a pull by just saying\ ``git pull`` and Git 119 complains that you have not specified a branch, try: 120 121 .. code-block:: console 122 123 git config branch.main.remote origin 124 git config branch.main.merge main 125 126 Otherwise, you have to say\ ``git pull origin main`` each time you 127 do a pull. 128 129#. Small changes to main 130 131 If you are an experienced Git user working on substantial 132 modifications, you are probably working on a separate branch and 133 would rebase your branch prior to merging with main. But for small 134 changes to the main branch itself, you also need to use the rebase 135 feature in order to avoid an unnecessary and distracting branch in 136 main. 137 138 If it has been awhile since you've done the initial clone, try 139 140 .. code-block:: console 141 142 git pull 143 144 to get the latest files before you start working. 145 146 Make your changes and use 147 148 .. code-block:: console 149 150 git add <files to commit> 151 git commit 152 153 to get your changes ready to push back into the freedesktop.org 154 repository. 155 156 It is possible (and likely) that someone has changed main since you 157 did your last pull. Even if your changes do not conflict with their 158 changes, Git will make a fast-forward merge branch, branching from 159 the point in time where you did your last pull and merging it to a 160 point after the other changes. 161 162 To avoid this, 163 164 .. code-block:: console 165 166 git pull --rebase 167 git push 168 169 If you are familiar with CVS or similar system, this is similar to 170 doing a ``cvs update`` in order to update your source tree to the 171 current repository state, instead of the time you did the last 172 update. (CVS doesn't work like Git in this respect, but this is 173 easiest way to explain it.) 174 175 In any case, your repository now looks like you made your changes 176 after all the other changes. 177 178 If the rebase resulted in conflicts or changes that could affect the 179 proper operation of your changes, you'll need to investigate those 180 before doing the push. 181 182 If you want the rebase action to be the default action, then 183 184 .. code-block:: console 185 186 git config branch.main.rebase true 187 git config --global branch.autosetuprebase=always 188 189 See `Understanding Git 190 Conceptually <https://www.eecs.harvard.edu/~cduan/technical/git/>`__ 191 for a fairly clear explanation about all of this. 192