git-gui/README.md

   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 Johannes Sixt at
  46 https://github.com/j6t/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 [git@vger.kernel.org](mailto:git@vger.kernel.org) 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 \<author@example.com\>' 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.