git-gui: add a readme
It is a good idea to have a readme so people finding the project can know more about it, and know how they can get involved. Signed-off-by: Pratyush Yadav <me@yadavpratyush.com> Acked-by: Bert Wesarg <bert.wesarg@googlemail.com>
Pratyush Yadav committed
Oct 5, 2019 at 01:23 UTC
1e6880fd06bf6b3f440065dbecf73434c142eeb6
1 file changed
+174
README.md
new
+174
@@ -0,0 +1,174 @@
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
+[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.