|
| 1 | +# Git GUI - A graphical user interface for Git |
| 2 | + |
| 3 | +Git GUI allows you to use the [Git source control management |
| 4 | +tools](https://git-scm.com/) via a GUI. This includes staging, committing, |
| 5 | +adding, pushing, etc. It can also be used as a blame viewer, a tree browser, |
| 6 | +and a citool (make exactly one commit before exiting and returning to shell). |
| 7 | +More details about Git GUI can be found in its manual page by either running |
| 8 | +`man git-gui`, or by visiting the [online manual |
| 9 | +page](https://git-scm.com/docs/git-gui). |
| 10 | + |
| 11 | +Git GUI was initially written by Shawn O. Pearce, and is distributed with the |
| 12 | +standard Git installation. |
| 13 | + |
| 14 | +# Building and installing |
| 15 | + |
| 16 | +You need to have the following dependencies installed before you begin: |
| 17 | + |
| 18 | +- Git |
| 19 | +- Tcl |
| 20 | +- Tk |
| 21 | +- wish |
| 22 | +- Gitk (needed for browsing history) |
| 23 | +- msgfmt |
| 24 | + |
| 25 | +Most of Git GUI is written in Tcl, so there is no compilation involved. Still, |
| 26 | +some things do need to be done (mostly some substitutions), so you do need to |
| 27 | +"build" it. |
| 28 | + |
| 29 | +You can build Git GUI using: |
| 30 | + |
| 31 | +``` |
| 32 | +make |
| 33 | +``` |
| 34 | + |
| 35 | +And then install it using: |
| 36 | + |
| 37 | +``` |
| 38 | +make install |
| 39 | +``` |
| 40 | + |
| 41 | +You probably need to have root/admin permissions to install. |
| 42 | + |
| 43 | +# Contributing |
| 44 | + |
| 45 | +The project is currently maintained by Pratyush Yadav over at |
| 46 | +https://github.com/prati0100/git-gui. Even though the project is hosted at |
| 47 | +GitHub, the development does not happen over GitHub Issues and Pull Requests. |
| 48 | +Instead, an email based workflow is used. The Git mailing list |
| 49 | +[[email protected]](mailto:[email protected]) is where the patches are |
| 50 | +discussed and reviewed. |
| 51 | + |
| 52 | +More information about the Git mailing list and instructions to subscribe can |
| 53 | +be found [here](https://git.wiki.kernel.org/index.php/GitCommunity). |
| 54 | + |
| 55 | +## Sending your changes |
| 56 | + |
| 57 | +Since the development happens over email, you need to send in your commits in |
| 58 | +text format. Commits can be converted to emails via the two tools provided by |
| 59 | +Git: `git-send-email` and `git-format-patch`. |
| 60 | + |
| 61 | +You can use `git-format-patch` to generate patches in mbox format from your |
| 62 | +commits that can then be sent via email. Let's say you are working on a branch |
| 63 | +called 'foo' that was created on top of 'master'. You can run: |
| 64 | + |
| 65 | +``` |
| 66 | +git format-patch -o output_dir master..foo |
| 67 | +``` |
| 68 | + |
| 69 | +to convert all the extra commits in 'foo' into a set of patches saved in the |
| 70 | +folder `output_dir`. |
| 71 | + |
| 72 | +If you are sending multiple patches, it is recommended to include a cover |
| 73 | +letter. A cover letter is an email explaining in brief what the series is |
| 74 | +supposed to do. A cover letter template can be generated by passing |
| 75 | +`--cover-letter` to `git-format-patch`. |
| 76 | + |
| 77 | +After you send your patches, you might get a review suggesting some changes. |
| 78 | +Make those changes, and re-send your patch(es) in reply to the first patch of |
| 79 | +your initial version. Also please mention the version of the patch. This can be |
| 80 | +done by passing `-v X` to `git-format-patch`, where 'X' is the version number |
| 81 | +of the patch(es). |
| 82 | + |
| 83 | +### Using git-send-email |
| 84 | + |
| 85 | +You can use `git-send-email` to send patches generated via `git-format-patch`. |
| 86 | +While you can directly send patches via `git-send-email`, it is recommended |
| 87 | +that you first use `git-format-patch` to generate the emails, audit them, and |
| 88 | +then send them via `git-send-email`. |
| 89 | + |
| 90 | +A pretty good guide to configuring and using `git-send-email` can be found |
| 91 | +[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/) |
| 92 | + |
| 93 | +### Using your email client |
| 94 | + |
| 95 | +If your email client supports sending mbox format emails, you can use |
| 96 | +`git-format-patch` to get an mbox file for each commit, and then send them. If |
| 97 | +there is more than one patch in the series, then all patches after the first |
| 98 | +patch (or the cover letter) need to be sent as replies to the first. |
| 99 | +`git-send-email` does this by default. |
| 100 | + |
| 101 | +### Using GitGitGadget |
| 102 | + |
| 103 | +Since some people prefer a GitHub pull request based workflow, they can use |
| 104 | +[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool |
| 105 | +was originally written for sending patches to the Git project, but it now also |
| 106 | +supports sending patches for git-gui. |
| 107 | + |
| 108 | +Instructions for using GitGitGadget to send git-gui patches, courtesy of |
| 109 | +Johannes Schindelin: |
| 110 | + |
| 111 | +If you don't already have a fork of the [git/git](https://github.com/git/git) |
| 112 | +repo, you need to make one. Then clone your fork: |
| 113 | + |
| 114 | +``` |
| 115 | +git clone https://github.com/<your-username>/git |
| 116 | +``` |
| 117 | + |
| 118 | +Then add GitGitGadget as a remote: |
| 119 | + |
| 120 | +``` |
| 121 | +git remote add gitgitgadget https://github.com/gitgitgadget/git |
| 122 | +``` |
| 123 | + |
| 124 | +Then fetch the git-gui branch: |
| 125 | + |
| 126 | +``` |
| 127 | +git fetch gitgitgadget git-gui/master |
| 128 | +``` |
| 129 | + |
| 130 | +Then create a new branch based on git-gui/master: |
| 131 | + |
| 132 | +``` |
| 133 | +git checkout -b <your-branch-name> git-gui/master |
| 134 | +``` |
| 135 | + |
| 136 | +Make whatever commits you need to, push them to your fork, and then head over |
| 137 | +to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting |
| 138 | +git-gui/master. |
| 139 | + |
| 140 | +GitGitGadget will welcome you with a (hopefully) helpful message. |
| 141 | + |
| 142 | +## Signing off |
| 143 | + |
| 144 | +You need to sign off your commits before sending them to the list. You can do |
| 145 | +that by passing the `-s` option to `git-commit`. You can also use the "Sign |
| 146 | +Off" option in Git GUI. |
| 147 | + |
| 148 | +A sign-off is a simple 'Signed-off-by: A U Thor \<[email protected]\>' line at |
| 149 | +the end of the commit message, after your explanation of the commit. |
| 150 | + |
| 151 | +A sign-off means that you are legally allowed to send the code, and it serves |
| 152 | +as a certificate of origin. More information can be found at |
| 153 | +[developercertificate.org](https://developercertificate.org/). |
| 154 | + |
| 155 | +## Responding to review comments |
| 156 | + |
| 157 | +It is quite likely your patches will get review comments. Those comments are |
| 158 | +sent on the Git mailing list as replies to your patch, and you will usually be |
| 159 | +Cc'ed in those replies. |
| 160 | + |
| 161 | +You are expected to respond by either explaining your code further to convince |
| 162 | +the reviewer what you are doing is correct, or acknowledge the comments and |
| 163 | +re-send the patches with those comments addressed. |
| 164 | + |
| 165 | +Some tips for those not familiar with communication on a mailing list: |
| 166 | + |
| 167 | +- Use only plain text emails. No HTML at all. |
| 168 | +- Wrap lines at around 75 characters. |
| 169 | +- Do not send attachments. If you do need to send some files, consider using a |
| 170 | + hosting service, and paste the link in your email. |
| 171 | +- Do not [top post](http://www.idallen.com/topposting.html). |
| 172 | +- Always "reply all". Keep all correspondents and the list in Cc. If you reply |
| 173 | + directly to a reviewer, and not Cc the list, other people would not be able |
| 174 | + to chime in. |
0 commit comments