* Re: [PATCH] git-gui: add a readme
2019-10-04 22:10 [PATCH] git-gui: add a readme Pratyush Yadav
@ 2019-10-05 10:51 ` Bert Wesarg
2019-10-05 21:11 ` Pratyush Yadav
2019-10-05 19:56 ` Johannes Schindelin
` (2 subsequent siblings)
3 siblings, 1 reply; 11+ messages in thread
From: Bert Wesarg @ 2019-10-05 10:51 UTC (permalink / raw)
To: Pratyush Yadav; +Cc: Git Mailing List, Johannes Schindelin, Junio C Hamano
On Sat, Oct 5, 2019 at 12:10 AM Pratyush Yadav <me@yadavpratyush.com> wrote:
>
> 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>
> ---
>
> I don't have much experience writing this kind of readme or
> documentation, so comments are appreciated. Please feel free to chime in
> with suggestions and things that can also be added.
>
> README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 128 insertions(+)
> create mode 100644 README.md
>
> diff --git a/README.md b/README.md
> new file mode 100644
> index 0000000..d76122d
> --- /dev/null
> +++ b/README.md
> @@ -0,0 +1,128 @@
> +# Git Gui - A graphical user interface for Git
> +
> +Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> +you to use the git source control management tools via a GUI. This includes
> +staging, commiting, adding, pushing, etc. It can also be used as a blame
> +viewer, a tree browser, and a citool (make exactly one commit before exiting
> +and returning to shell). More details about git-gui can be found in its manual
> +page by either running `man git-gui`, or by visiting the [online manual
> +page](https://git-scm.com/docs/git-gui).
> +
> +Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> +standard git installation.
> +
> +# Building and installing
> +
> +Most of Git Gui is written in Tcl, so there is not much compilation involved.
> +Still, some things do need to be done, so you do need to "build" it.
> +
> +You can build Git Gui using:
> +
> +```
> +make
> +```
> +
> +And then install it using:
> +
> +```
> +make install
> +```
> +
> +You probably need to have root/admin permissions to install.
> +
> +# Contributing
> +
> +The project is currently maintained by Pratyush Yadav over at
> +https://github.com/prati0100/git-gui. Even though the project is hosted at
> +GitHub, the development does not happen over GitHub Issues and Pull Requests.
> +Instead, an email based workflow is used. The git mailing list
> +[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
> +discussed and reviewed.
> +
> +More information about the git mailing list and instructions to subscribe can
> +be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
> +
> +## Sending your changes
> +
> +Since the development happens over email, you need to send in your commits in
> +text format. Commits can be converted to emails via the two tools provided by
> +git: `git-send-email` and `git-format-patch`.
> +
> +If you are sending multiple patches, it is recommended to include a cover
> +letter. A cover letter is an email explaining in brief what the series is
> +supposed to do. A cover letter template can be generated by passing
> +`--cover-letter` to `git-format-patch`.
> +
> +After you send your patches, you might get a review suggesting some changes.
> +Make those changes, and re-send your patch(es) in reply to the first patch of
> +your initial version. Also please mention the version of the patch. This can be
> +done by passing `-v X` to `git-format-patch`, where 'X' is the version number
> +of the patch(es).
> +
> +### Using git-send-email
> +
> +You can use `git-send-email` to send patches via email. A pretty good guide to
> +configuring and using `git-send-email` can be found
> +[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
> +
> +### Using your email client
> +
> +If your email client supports sending mbox format emails, you can use
> +`git-format-patch` to get an mbox file for each commit, and then send them. If
> +there is more than one patch in the series, then all patches after the first
> +patch (or the cover letter) need to be sent as replies to the first.
> +`git-send-email` does this by default.
> +
Junio mentioned (at least?) once [1], that using only git-send-email
is not a good workflow. Instead one should use git-format-patch to
generate the patches, audit them. and then use git-send-email. I
second this.
Please switch these two sections to encompass this.
Thanks.
Bert
[1] https://public-inbox.org/git/xmqqh9n241el.fsf@gitster.mtv.corp.google.com/
> +### Using GitGitGadget
> +
> +Since some people prefer a GitHub pull request based workflow, they can use
> +[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool
> +was originally written for sending patches to the Git project, but it now also
> +supports sending patches for git-gui.
> +
> +Instructions for using GitGitGadget to send git-gui patches, courtesy of
> +Johannes Schindelin:
> +
> +If you don't already have a fork of the [git/git](https://github.com/git/git)
> +repo, you need to make one. Then clone your fork:
> +
> +```
> +git clone https://github.com/<your-username>/git
> +```
> +
> +Then add GitGitGadget as a remote:
> +
> +```
> +git remote add gitgitgadget https://github.com/gitgitgadget/git
> +```
> +
> +Then fetch the git-gui branch:
> +
> +```
> +git fetch gitgitgadget git-gui/master
> +```
> +
> +Then create a new branch based on git-gui/master:
> +
> +```
> +git checkout -b <your-branch-name> git-gui/master
> +```
> +
> +Make whatever commits you need to, push them to your fork, and then head over
> +to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting
> +git-gui/master.
> +
> +GitGitGadget will welcome you with a (hopefully) helpful message.
> +
> +## Signing off
> +
> +You need to sign off your commits before sending them to the list. You can do
> +that by passing the `-s` option to `git-commit`. You can also use the "Sign
> +Off" option in Git Gui.
> +
> +A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
> +the end of the commit message, after your explanation of the commit.
> +
> +A sign-off means that you are legally allowed to send the code, and it serves
> +as a certificate of origin. More information can be found at
> +[developercertificate.org](https://developercertificate.org/).
> --
> 2.21.0
>
^ permalink raw reply [flat|nested] 11+ messages in thread* Re: [PATCH] git-gui: add a readme
2019-10-05 10:51 ` Bert Wesarg
@ 2019-10-05 21:11 ` Pratyush Yadav
0 siblings, 0 replies; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-05 21:11 UTC (permalink / raw)
To: Bert Wesarg; +Cc: Git Mailing List, Johannes Schindelin, Junio C Hamano
On 05/10/19 12:51PM, Bert Wesarg wrote:
> On Sat, Oct 5, 2019 at 12:10 AM Pratyush Yadav <me@yadavpratyush.com> wrote:
> > +# Contributing
> > +
> > +The project is currently maintained by Pratyush Yadav over at
> > +https://github.com/prati0100/git-gui. Even though the project is hosted at
> > +GitHub, the development does not happen over GitHub Issues and Pull Requests.
> > +Instead, an email based workflow is used. The git mailing list
> > +[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
> > +discussed and reviewed.
> > +
> > +More information about the git mailing list and instructions to subscribe can
> > +be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
> > +
> > +## Sending your changes
> > +
> > +Since the development happens over email, you need to send in your commits in
> > +text format. Commits can be converted to emails via the two tools provided by
> > +git: `git-send-email` and `git-format-patch`.
> > +
> > +If you are sending multiple patches, it is recommended to include a cover
> > +letter. A cover letter is an email explaining in brief what the series is
> > +supposed to do. A cover letter template can be generated by passing
> > +`--cover-letter` to `git-format-patch`.
> > +
> > +After you send your patches, you might get a review suggesting some changes.
> > +Make those changes, and re-send your patch(es) in reply to the first patch of
> > +your initial version. Also please mention the version of the patch. This can be
> > +done by passing `-v X` to `git-format-patch`, where 'X' is the version number
> > +of the patch(es).
> > +
> > +### Using git-send-email
> > +
> > +You can use `git-send-email` to send patches via email. A pretty good guide to
> > +configuring and using `git-send-email` can be found
> > +[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
> > +
> > +### Using your email client
> > +
> > +If your email client supports sending mbox format emails, you can use
> > +`git-format-patch` to get an mbox file for each commit, and then send them. If
> > +there is more than one patch in the series, then all patches after the first
> > +patch (or the cover letter) need to be sent as replies to the first.
> > +`git-send-email` does this by default.
> > +
>
> Junio mentioned (at least?) once [1], that using only git-send-email
> is not a good workflow. Instead one should use git-format-patch to
> generate the patches, audit them. and then use git-send-email. I
> second this.
>
> Please switch these two sections to encompass this.
Thanks for pointing it out. Will fix.
> Thanks.
>
> Bert
>
> [1] https://public-inbox.org/git/xmqqh9n241el.fsf@gitster.mtv.corp.google.com/
--
Regards,
Pratyush Yadav
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] git-gui: add a readme
2019-10-04 22:10 [PATCH] git-gui: add a readme Pratyush Yadav
2019-10-05 10:51 ` Bert Wesarg
@ 2019-10-05 19:56 ` Johannes Schindelin
2019-10-05 21:10 ` Pratyush Yadav
2019-10-06 22:09 ` [PATCH v2] " Pratyush Yadav
2019-10-08 12:17 ` [PATCH v3] " Pratyush Yadav
3 siblings, 1 reply; 11+ messages in thread
From: Johannes Schindelin @ 2019-10-05 19:56 UTC (permalink / raw)
To: Pratyush Yadav; +Cc: git, Bert Wesarg
Hi Pratyush,
On Sat, 5 Oct 2019, Pratyush Yadav wrote:
> 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>
> ---
>
> I don't have much experience writing this kind of readme or
> documentation, so comments are appreciated. Please feel free to chime in
> with suggestions and things that can also be added.
>
> README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 128 insertions(+)
> create mode 100644 README.md
>
> diff --git a/README.md b/README.md
> new file mode 100644
> index 0000000..d76122d
> --- /dev/null
> +++ b/README.md
> @@ -0,0 +1,128 @@
> +# Git Gui - A graphical user interface for Git
Why not Git GUI? "Git" is a name, "GUI" is an abbreviation, and the
convention is (at least as far as I can tell) to upcase abbreviations.
> +
> +Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> +you to use the git source control management tools via a GUI. This includes
^^^
I prefer to spell it as "Git", i.e. with an upper-case "G" because "Git"
is a name. Lower-case "git" would suggest the command-line executable to
me.
> +staging, commiting, adding, pushing, etc. It can also be used as a blame
> +viewer, a tree browser, and a citool (make exactly one commit before exiting
> +and returning to shell). More details about git-gui can be found in its manual
> +page by either running `man git-gui`, or by visiting the [online manual
> +page](https://git-scm.com/docs/git-gui).
> +
> +Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> +standard git installation.
> +
> +# Building and installing
> +
> +Most of Git Gui is written in Tcl, so there is not much compilation involved.
"Most"? Are there parts that are not written in Tcl?
As far as I can tell, _no_ compilation is involved. Just a couple of
substitutions, e.g. the version number.
> +Still, some things do need to be done, so you do need to "build" it.
> +
> +You can build Git Gui using:
> +
> +```
> +make
> +```
> +
> +And then install it using:
> +
> +```
> +make install
> +```
> +
> +You probably need to have root/admin permissions to install.
> +
> +# Contributing
> +
> +The project is currently maintained by Pratyush Yadav over at
> +https://github.com/prati0100/git-gui. Even though the project is hosted at
> +GitHub, the development does not happen over GitHub Issues and Pull Requests.
> +Instead, an email based workflow is used. The git mailing list
> +[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
> +discussed and reviewed.
You might want to accompany this `README.md` with a
`.github/PULL_REQUEST_TEMPLATE.md` that explains this, and discourages
contributors from opening PRs (mind, some contributors will not even
read this, let alone delete it nor refrain from opening PRs, but most
contributors will read it and avoid unnecessary work).
Ciao,
Johannes
> +
> +More information about the git mailing list and instructions to subscribe can
> +be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
> +
> +## Sending your changes
> +
> +Since the development happens over email, you need to send in your commits in
> +text format. Commits can be converted to emails via the two tools provided by
> +git: `git-send-email` and `git-format-patch`.
> +
> +If you are sending multiple patches, it is recommended to include a cover
> +letter. A cover letter is an email explaining in brief what the series is
> +supposed to do. A cover letter template can be generated by passing
> +`--cover-letter` to `git-format-patch`.
> +
> +After you send your patches, you might get a review suggesting some changes.
> +Make those changes, and re-send your patch(es) in reply to the first patch of
> +your initial version. Also please mention the version of the patch. This can be
> +done by passing `-v X` to `git-format-patch`, where 'X' is the version number
> +of the patch(es).
> +
> +### Using git-send-email
> +
> +You can use `git-send-email` to send patches via email. A pretty good guide to
> +configuring and using `git-send-email` can be found
> +[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
> +
> +### Using your email client
> +
> +If your email client supports sending mbox format emails, you can use
> +`git-format-patch` to get an mbox file for each commit, and then send them. If
> +there is more than one patch in the series, then all patches after the first
> +patch (or the cover letter) need to be sent as replies to the first.
> +`git-send-email` does this by default.
> +
> +### Using GitGitGadget
> +
> +Since some people prefer a GitHub pull request based workflow, they can use
> +[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool
> +was originally written for sending patches to the Git project, but it now also
> +supports sending patches for git-gui.
> +
> +Instructions for using GitGitGadget to send git-gui patches, courtesy of
> +Johannes Schindelin:
> +
> +If you don't already have a fork of the [git/git](https://github.com/git/git)
> +repo, you need to make one. Then clone your fork:
> +
> +```
> +git clone https://github.com/<your-username>/git
> +```
> +
> +Then add GitGitGadget as a remote:
> +
> +```
> +git remote add gitgitgadget https://github.com/gitgitgadget/git
> +```
> +
> +Then fetch the git-gui branch:
> +
> +```
> +git fetch gitgitgadget git-gui/master
> +```
> +
> +Then create a new branch based on git-gui/master:
> +
> +```
> +git checkout -b <your-branch-name> git-gui/master
> +```
> +
> +Make whatever commits you need to, push them to your fork, and then head over
> +to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting
> +git-gui/master.
> +
> +GitGitGadget will welcome you with a (hopefully) helpful message.
> +
> +## Signing off
> +
> +You need to sign off your commits before sending them to the list. You can do
> +that by passing the `-s` option to `git-commit`. You can also use the "Sign
> +Off" option in Git Gui.
> +
> +A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
> +the end of the commit message, after your explanation of the commit.
> +
> +A sign-off means that you are legally allowed to send the code, and it serves
> +as a certificate of origin. More information can be found at
> +[developercertificate.org](https://developercertificate.org/).
> --
> 2.21.0
>
>
^ permalink raw reply [flat|nested] 11+ messages in thread* Re: [PATCH] git-gui: add a readme
2019-10-05 19:56 ` Johannes Schindelin
@ 2019-10-05 21:10 ` Pratyush Yadav
0 siblings, 0 replies; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-05 21:10 UTC (permalink / raw)
To: Johannes Schindelin; +Cc: git, Bert Wesarg
Hi Johannes,
On 05/10/19 09:56PM, Johannes Schindelin wrote:
> Hi Pratyush,
>
> On Sat, 5 Oct 2019, Pratyush Yadav wrote:
>
> > 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>
> > ---
> >
> > I don't have much experience writing this kind of readme or
> > documentation, so comments are appreciated. Please feel free to chime in
> > with suggestions and things that can also be added.
> >
> > README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 128 insertions(+)
> > create mode 100644 README.md
> >
> > diff --git a/README.md b/README.md
> > new file mode 100644
> > index 0000000..d76122d
> > --- /dev/null
> > +++ b/README.md
> > @@ -0,0 +1,128 @@
> > +# Git Gui - A graphical user interface for Git
>
> Why not Git GUI? "Git" is a name, "GUI" is an abbreviation, and the
> convention is (at least as far as I can tell) to upcase abbreviations.
Well, the _appname global variable is set to "Git Gui". But I don't mind
changing it to "GUI" either.
> > +
> > +Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> > +you to use the git source control management tools via a GUI. This includes
> ^^^
>
> I prefer to spell it as "Git", i.e. with an upper-case "G" because "Git"
> is a name. Lower-case "git" would suggest the command-line executable to
> me.
Will fix.
> > +staging, commiting, adding, pushing, etc. It can also be used as a blame
> > +viewer, a tree browser, and a citool (make exactly one commit before exiting
> > +and returning to shell). More details about git-gui can be found in its manual
> > +page by either running `man git-gui`, or by visiting the [online manual
> > +page](https://git-scm.com/docs/git-gui).
> > +
> > +Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> > +standard git installation.
> > +
> > +# Building and installing
> > +
> > +Most of Git Gui is written in Tcl, so there is not much compilation involved.
>
> "Most"? Are there parts that are not written in Tcl?
Well, there is the Makefile, which is a part of the project and not in
Tcl. Also, if I open GitHub's "language stat bar" (the colored bar below
"commits", "branches", "releases", etc), it says 96.4% Tcl, 2.7%
Makefile, and 0.9% Other.
So _technically_ there is a small part not in Tcl.
> As far as I can tell, _no_ compilation is involved. Just a couple of
> substitutions, e.g. the version number.
Yes, correct. I suppose that was bad wording. Will fix.
> > +Still, some things do need to be done, so you do need to "build" it.
> > +
> > +You can build Git Gui using:
> > +
> > +```
> > +make
> > +```
> > +
> > +And then install it using:
> > +
> > +```
> > +make install
> > +```
> > +
> > +You probably need to have root/admin permissions to install.
> > +
> > +# Contributing
> > +
> > +The project is currently maintained by Pratyush Yadav over at
> > +https://github.com/prati0100/git-gui. Even though the project is hosted at
> > +GitHub, the development does not happen over GitHub Issues and Pull Requests.
> > +Instead, an email based workflow is used. The git mailing list
> > +[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
> > +discussed and reviewed.
>
> You might want to accompany this `README.md` with a
> `.github/PULL_REQUEST_TEMPLATE.md` that explains this, and discourages
> contributors from opening PRs (mind, some contributors will not even
> read this, let alone delete it nor refrain from opening PRs, but most
> contributors will read it and avoid unnecessary work).
Will do as a follow-up patch.
Thanks for the review.
--
Regards,
Pratyush Yadav
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH v2] git-gui: add a readme
2019-10-04 22:10 [PATCH] git-gui: add a readme Pratyush Yadav
2019-10-05 10:51 ` Bert Wesarg
2019-10-05 19:56 ` Johannes Schindelin
@ 2019-10-06 22:09 ` Pratyush Yadav
2019-10-07 1:39 ` Junio C Hamano
2019-10-08 12:17 ` [PATCH v3] " Pratyush Yadav
3 siblings, 1 reply; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-06 22:09 UTC (permalink / raw)
To: git; +Cc: Bert Wesarg, Johannes Schindelin
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>
---
Changes in v2:
- s/Gui/GUI/g suggested by Johannes.
- s/git/Git/ wherever applicable suggested by Johannes.
- Clarify that there is no compilation involved, and it is just a
bunch of substitutions. Suggested by Johannes.
- Clarify that directly using `git send-email` is bad workflow, and
suggest using `git format-patch` before that. Suggested by Bert.
- Add an example of using `git format-patch`.
- Add a "Responding to review comments" section.
Range-diff against v1:
1: df866a9 ! 1: 82fd39f git-gui: add a readme
@@ -12,25 +12,26 @@
--- /dev/null
+++ b/README.md
@@
-+# Git Gui - A graphical user interface for Git
++# Git GUI - A graphical user interface for Git
+
-+Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
-+you to use the git source control management tools via a GUI. This includes
++Git GUI is a GUI for [Git](https://git-scm.com/) written in Tcl/Tk. It allows
++you to use the Git source control management tools via a GUI. This includes
+staging, commiting, adding, pushing, etc. It can also be used as a blame
+viewer, a tree browser, and a citool (make exactly one commit before exiting
+and returning to shell). More details about git-gui can be found in its manual
+page by either running `man git-gui`, or by visiting the [online manual
+page](https://git-scm.com/docs/git-gui).
+
-+Git Gui was initially written by Shawn O. Pearce, and is distributed with the
-+standard git installation.
++Git GUI was initially written by Shawn O. Pearce, and is distributed with the
++standard Git installation.
+
+# Building and installing
+
-+Most of Git Gui is written in Tcl, so there is not much compilation involved.
-+Still, some things do need to be done, so you do need to "build" it.
++Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
++some things do need to be done (mostly some substitutions), so you do need to
++"build" it.
+
-+You can build Git Gui using:
++You can build Git GUI using:
+
+```
+make
@@ -49,18 +50,29 @@
+The project is currently maintained by Pratyush Yadav over at
+https://github.com/prati0100/git-gui. Even though the project is hosted at
+GitHub, the development does not happen over GitHub Issues and Pull Requests.
-+Instead, an email based workflow is used. The git mailing list
++Instead, an email based workflow is used. The Git mailing list
+[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
+discussed and reviewed.
+
-+More information about the git mailing list and instructions to subscribe can
++More information about the Git mailing list and instructions to subscribe can
+be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
+
+## Sending your changes
+
+Since the development happens over email, you need to send in your commits in
+text format. Commits can be converted to emails via the two tools provided by
-+git: `git-send-email` and `git-format-patch`.
++Git: `git-send-email` and `git-format-patch`.
++
++You can use `git-format-patch` to generate patches in mbox format from your
++commits that can then be sent via email. Let's say you are working on a branch
++called 'foo' that was created on top of 'master'. You can run:
++
++```
++git format-patch -o output_dir master..foo
++```
++
++to convert all the extra commits in 'foo' into a set of patches saved in the
++folder `output_dir`.
+
+If you are sending multiple patches, it is recommended to include a cover
+letter. A cover letter is an email explaining in brief what the series is
@@ -75,8 +87,12 @@
+
+### Using git-send-email
+
-+You can use `git-send-email` to send patches via email. A pretty good guide to
-+configuring and using `git-send-email` can be found
++You can use `git-send-email` to send patches generated via `git-format-patch`.
++While you can directly send patches via `git-send-email`, it is recommended
++that you first use `git-format-patch` to generate the emails, audit them, and
++then send them via `git-send-email`.
++
++A pretty good guide to configuring and using `git-send-email` can be found
+[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
+
+### Using your email client
@@ -132,7 +148,7 @@
+
+You need to sign off your commits before sending them to the list. You can do
+that by passing the `-s` option to `git-commit`. You can also use the "Sign
-+Off" option in Git Gui.
++Off" option in Git GUI.
+
+A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
+the end of the commit message, after your explanation of the commit.
@@ -140,3 +156,24 @@
+A sign-off means that you are legally allowed to send the code, and it serves
+as a certificate of origin. More information can be found at
+[developercertificate.org](https://developercertificate.org/).
++
++## Responding to review comments
++
++It is quite likely your patches will get review comments. Those comments are
++sent on the Git mailing list as replies to your patch, and you will usually be
++Cc'ed in those replies.
++
++You are expected to respond by either explaining your code further to convince
++the reviewer what you are doing is correct, or acknowledge the comments and
++re-send the patches with those comments addressed.
++
++Some tips for those not familiar with communication on a mailing list:
++
++- Use only plain text emails. No HTML at all.
++- Wrap lines at around 75 characters.
++- Do not send attachments. If you do need to send some files, consider using a
++ hosting service, and paste the link in your email.
++- Do not [top post](http://www.idallen.com/topposting.html).
++- Always "reply all". Keep all correspondents and the list in Cc. If you reply
++ directly to a reviewer, and not Cc the list, other people would not be able
++ to chime in.
README.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 165 insertions(+)
create mode 100644 README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f87d92f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,165 @@
+# Git GUI - A graphical user interface for Git
+
+Git GUI is a GUI for [Git](https://git-scm.com/) written in Tcl/Tk. It allows
+you to use the Git source control management tools via a GUI. This includes
+staging, commiting, adding, pushing, etc. It can also be used as a blame
+viewer, a tree browser, and a citool (make exactly one commit before exiting
+and returning to shell). More details about git-gui can be found in its manual
+page by either running `man git-gui`, or by visiting the [online manual
+page](https://git-scm.com/docs/git-gui).
+
+Git GUI was initially written by Shawn O. Pearce, and is distributed with the
+standard Git installation.
+
+# Building and installing
+
+Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
+some things do need to be done (mostly some substitutions), so you do need to
+"build" it.
+
+You can build Git GUI using:
+
+```
+make
+```
+
+And then install it using:
+
+```
+make install
+```
+
+You probably need to have root/admin permissions to install.
+
+# Contributing
+
+The project is currently maintained by Pratyush Yadav over at
+https://github.com/prati0100/git-gui. Even though the project is hosted at
+GitHub, the development does not happen over GitHub Issues and Pull Requests.
+Instead, an email based workflow is used. The Git mailing list
+[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
+discussed and reviewed.
+
+More information about the Git mailing list and instructions to subscribe can
+be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
+
+## Sending your changes
+
+Since the development happens over email, you need to send in your commits in
+text format. Commits can be converted to emails via the two tools provided by
+Git: `git-send-email` and `git-format-patch`.
+
+You can use `git-format-patch` to generate patches in mbox format from your
+commits that can then be sent via email. Let's say you are working on a branch
+called 'foo' that was created on top of 'master'. You can run:
+
+```
+git format-patch -o output_dir master..foo
+```
+
+to convert all the extra commits in 'foo' into a set of patches saved in the
+folder `output_dir`.
+
+If you are sending multiple patches, it is recommended to include a cover
+letter. A cover letter is an email explaining in brief what the series is
+supposed to do. A cover letter template can be generated by passing
+`--cover-letter` to `git-format-patch`.
+
+After you send your patches, you might get a review suggesting some changes.
+Make those changes, and re-send your patch(es) in reply to the first patch of
+your initial version. Also please mention the version of the patch. This can be
+done by passing `-v X` to `git-format-patch`, where 'X' is the version number
+of the patch(es).
+
+### Using git-send-email
+
+You can use `git-send-email` to send patches generated via `git-format-patch`.
+While you can directly send patches via `git-send-email`, it is recommended
+that you first use `git-format-patch` to generate the emails, audit them, and
+then send them via `git-send-email`.
+
+A pretty good guide to configuring and using `git-send-email` can be found
+[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
+
+### Using your email client
+
+If your email client supports sending mbox format emails, you can use
+`git-format-patch` to get an mbox file for each commit, and then send them. If
+there is more than one patch in the series, then all patches after the first
+patch (or the cover letter) need to be sent as replies to the first.
+`git-send-email` does this by default.
+
+### Using GitGitGadget
+
+Since some people prefer a GitHub pull request based workflow, they can use
+[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool
+was originally written for sending patches to the Git project, but it now also
+supports sending patches for git-gui.
+
+Instructions for using GitGitGadget to send git-gui patches, courtesy of
+Johannes Schindelin:
+
+If you don't already have a fork of the [git/git](https://github.com/git/git)
+repo, you need to make one. Then clone your fork:
+
+```
+git clone https://github.com/<your-username>/git
+```
+
+Then add GitGitGadget as a remote:
+
+```
+git remote add gitgitgadget https://github.com/gitgitgadget/git
+```
+
+Then fetch the git-gui branch:
+
+```
+git fetch gitgitgadget git-gui/master
+```
+
+Then create a new branch based on git-gui/master:
+
+```
+git checkout -b <your-branch-name> git-gui/master
+```
+
+Make whatever commits you need to, push them to your fork, and then head over
+to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting
+git-gui/master.
+
+GitGitGadget will welcome you with a (hopefully) helpful message.
+
+## Signing off
+
+You need to sign off your commits before sending them to the list. You can do
+that by passing the `-s` option to `git-commit`. You can also use the "Sign
+Off" option in Git GUI.
+
+A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
+the end of the commit message, after your explanation of the commit.
+
+A sign-off means that you are legally allowed to send the code, and it serves
+as a certificate of origin. More information can be found at
+[developercertificate.org](https://developercertificate.org/).
+
+## Responding to review comments
+
+It is quite likely your patches will get review comments. Those comments are
+sent on the Git mailing list as replies to your patch, and you will usually be
+Cc'ed in those replies.
+
+You are expected to respond by either explaining your code further to convince
+the reviewer what you are doing is correct, or acknowledge the comments and
+re-send the patches with those comments addressed.
+
+Some tips for those not familiar with communication on a mailing list:
+
+- Use only plain text emails. No HTML at all.
+- Wrap lines at around 75 characters.
+- Do not send attachments. If you do need to send some files, consider using a
+ hosting service, and paste the link in your email.
+- Do not [top post](http://www.idallen.com/topposting.html).
+- Always "reply all". Keep all correspondents and the list in Cc. If you reply
+ directly to a reviewer, and not Cc the list, other people would not be able
+ to chime in.
--
2.21.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH v2] git-gui: add a readme
2019-10-06 22:09 ` [PATCH v2] " Pratyush Yadav
@ 2019-10-07 1:39 ` Junio C Hamano
2019-10-07 23:18 ` Pratyush Yadav
0 siblings, 1 reply; 11+ messages in thread
From: Junio C Hamano @ 2019-10-07 1:39 UTC (permalink / raw)
To: Pratyush Yadav; +Cc: git, Bert Wesarg, Johannes Schindelin
Pratyush Yadav <me@yadavpratyush.com> writes:
> -+# Git Gui - A graphical user interface for Git
> ++# Git GUI - A graphical user interface for Git
> +
> -+Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> -+you to use the git source control management tools via a GUI. This includes
> ++Git GUI is a GUI for [Git](https://git-scm.com/) written in Tcl/Tk. It allows
> ++you to use the Git source control management tools via a GUI. This includes
(ignore me if this has been discussed already)
The first sentence looks overly repeticious (it just looks to me as
if saying "Git GUI is a Git GUI written in Tcl/Tk"). Saying
Git GUI allows you to use the [Git source control management
tools](https://git-scm.com/) via a GUI and is written in
Tcl/Tk. This includes ...
may reduce the repetition somewhat. Also if I were writing this
intro, I'd move "writtein in Tcl/Tk" to a lot later or perhaps just
drop the phrase from here; what the users can gain from the tool is
much more important to the readers of this document than its
implementation detail. "Written in Tcl" is given in the installation
section anyway.
> +staging, commiting, adding, pushing, etc. It can also be used as a blame
> +viewer, a tree browser, and a citool (make exactly one commit before exiting
> +and returning to shell). More details about git-gui can be found in its manual
> +page by either running `man git-gui`, or by visiting the [online manual
> +page](https://git-scm.com/docs/git-gui).
> +
> -+Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> -+standard git installation.
> ++Git GUI was initially written by Shawn O. Pearce, and is distributed with the
> ++standard Git installation.
> +
> +# Building and installing
> +
> -+Most of Git Gui is written in Tcl, so there is not much compilation involved.
> -+Still, some things do need to be done, so you do need to "build" it.
> ++Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
> ++some things do need to be done (mostly some substitutions), so you do need to
> ++"build" it.
It is a good thing to say that it is written in Tcl for two
reasons.. The users need to know (1) they need to know Tcl/Tk to
hack on it, and (2) they need to install "wish" as a prerequisite to
run it.
Does the document mention the latter explicitly? If it does not, it
probably should. Also it helps to have msgfmt installed when
building git-gui. That also should be mentioned.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH v2] git-gui: add a readme
2019-10-07 1:39 ` Junio C Hamano
@ 2019-10-07 23:18 ` Pratyush Yadav
0 siblings, 0 replies; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-07 23:18 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Bert Wesarg, Johannes Schindelin
On 07/10/19 10:39AM, Junio C Hamano wrote:
> Pratyush Yadav <me@yadavpratyush.com> writes:
>
> > -+# Git Gui - A graphical user interface for Git
> > ++# Git GUI - A graphical user interface for Git
> > +
> > -+Git Gui is a GUI for [git](https://git-scm.com/) written in Tcl/Tk. It allows
> > -+you to use the git source control management tools via a GUI. This includes
> > ++Git GUI is a GUI for [Git](https://git-scm.com/) written in Tcl/Tk. It allows
> > ++you to use the Git source control management tools via a GUI. This includes
>
> (ignore me if this has been discussed already)
It hasn't been.
> The first sentence looks overly repeticious (it just looks to me as
> if saying "Git GUI is a Git GUI written in Tcl/Tk"). Saying
>
> Git GUI allows you to use the [Git source control management
> tools](https://git-scm.com/) via a GUI and is written in
> Tcl/Tk. This includes ...
>
> may reduce the repetition somewhat. Also if I were writing this
> intro, I'd move "writtein in Tcl/Tk" to a lot later or perhaps just
> drop the phrase from here; what the users can gain from the tool is
> much more important to the readers of this document than its
> implementation detail. "Written in Tcl" is given in the installation
> section anyway.
Will fix.
> > +staging, commiting, adding, pushing, etc. It can also be used as a blame
> > +viewer, a tree browser, and a citool (make exactly one commit before exiting
> > +and returning to shell). More details about git-gui can be found in its manual
> > +page by either running `man git-gui`, or by visiting the [online manual
> > +page](https://git-scm.com/docs/git-gui).
> > +
> > -+Git Gui was initially written by Shawn O. Pearce, and is distributed with the
> > -+standard git installation.
> > ++Git GUI was initially written by Shawn O. Pearce, and is distributed with the
> > ++standard Git installation.
> > +
> > +# Building and installing
> > +
> > -+Most of Git Gui is written in Tcl, so there is not much compilation involved.
> > -+Still, some things do need to be done, so you do need to "build" it.
> > ++Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
> > ++some things do need to be done (mostly some substitutions), so you do need to
> > ++"build" it.
>
> It is a good thing to say that it is written in Tcl for two
> reasons.. The users need to know (1) they need to know Tcl/Tk to
> hack on it, and (2) they need to install "wish" as a prerequisite to
> run it.
>
> Does the document mention the latter explicitly? If it does not, it
> probably should. Also it helps to have msgfmt installed when
> building git-gui. That also should be mentioned.
No, it does not.
I'll also check if there are any other dependencies. I installed git-gui
from my distro's package manager, so I got all the dependencies pulled
in automatically, and don't remember if there was something other than
Tcl and wish needed.
--
Regards,
Pratyush Yadav
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH v3] git-gui: add a readme
2019-10-04 22:10 [PATCH] git-gui: add a readme Pratyush Yadav
` (2 preceding siblings ...)
2019-10-06 22:09 ` [PATCH v2] " Pratyush Yadav
@ 2019-10-08 12:17 ` Pratyush Yadav
2019-10-11 21:35 ` Pratyush Yadav
3 siblings, 1 reply; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-08 12:17 UTC (permalink / raw)
To: git; +Cc: Bert Wesarg, Johannes Schindelin, Junio C Hamano
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>
---
Changes in v3:
- Reword the first paragraph to avoid some repetition. Suggested by
Junio.
- Do not mention "written in Tcl" in the intro. Suggested by Junio.
- Add a list of dependencies.
Range-diff against v2:
1: 3c8baed ! 1: b82d3ba git-gui: add a readme
@@ -14,12 +14,12 @@
@@
+# Git GUI - A graphical user interface for Git
+
-+Git GUI is a GUI for [Git](https://git-scm.com/) written in Tcl/Tk. It allows
-+you to use the Git source control management tools via a GUI. This includes
-+staging, commiting, adding, pushing, etc. It can also be used as a blame
-+viewer, a tree browser, and a citool (make exactly one commit before exiting
-+and returning to shell). More details about git-gui can be found in its manual
-+page by either running `man git-gui`, or by visiting the [online manual
++Git GUI allows you to use the [Git source control management
++tools](https://git-scm.com/) via a GUI. This includes staging, commiting,
++adding, pushing, etc. It can also be used as a blame viewer, a tree browser,
++and a citool (make exactly one commit before exiting and returning to shell).
++More details about Git GUI can be found in its manual page by either running
++`man git-gui`, or by visiting the [online manual
+page](https://git-scm.com/docs/git-gui).
+
+Git GUI was initially written by Shawn O. Pearce, and is distributed with the
@@ -27,6 +27,15 @@
+
+# Building and installing
+
++You need to have the following dependencies installed before you begin:
++
++- Git
++- Tcl
++- Tk
++- wish
++- Gitk (needed for browsing history)
++- msgfmt
++
+Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
+some things do need to be done (mostly some substitutions), so you do need to
+"build" it.
README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 174 insertions(+)
create mode 100644 README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3ee3829
--- /dev/null
+++ b/README.md
@@ -0,0 +1,174 @@
+# Git GUI - A graphical user interface for Git
+
+Git GUI allows you to use the [Git source control management
+tools](https://git-scm.com/) via a GUI. This includes staging, commiting,
+adding, pushing, etc. It can also be used as a blame viewer, a tree browser,
+and a citool (make exactly one commit before exiting and returning to shell).
+More details about Git GUI can be found in its manual page by either running
+`man git-gui`, or by visiting the [online manual
+page](https://git-scm.com/docs/git-gui).
+
+Git GUI was initially written by Shawn O. Pearce, and is distributed with the
+standard Git installation.
+
+# Building and installing
+
+You need to have the following dependencies installed before you begin:
+
+- Git
+- Tcl
+- Tk
+- wish
+- Gitk (needed for browsing history)
+- msgfmt
+
+Most of Git GUI is written in Tcl, so there is no compilation involved. Still,
+some things do need to be done (mostly some substitutions), so you do need to
+"build" it.
+
+You can build Git GUI using:
+
+```
+make
+```
+
+And then install it using:
+
+```
+make install
+```
+
+You probably need to have root/admin permissions to install.
+
+# Contributing
+
+The project is currently maintained by Pratyush Yadav over at
+https://github.com/prati0100/git-gui. Even though the project is hosted at
+GitHub, the development does not happen over GitHub Issues and Pull Requests.
+Instead, an email based workflow is used. The Git mailing list
+[git@vger.kernel.org](mailto:git@vger.kernel.org) is where the patches are
+discussed and reviewed.
+
+More information about the Git mailing list and instructions to subscribe can
+be found [here](https://git.wiki.kernel.org/index.php/GitCommunity).
+
+## Sending your changes
+
+Since the development happens over email, you need to send in your commits in
+text format. Commits can be converted to emails via the two tools provided by
+Git: `git-send-email` and `git-format-patch`.
+
+You can use `git-format-patch` to generate patches in mbox format from your
+commits that can then be sent via email. Let's say you are working on a branch
+called 'foo' that was created on top of 'master'. You can run:
+
+```
+git format-patch -o output_dir master..foo
+```
+
+to convert all the extra commits in 'foo' into a set of patches saved in the
+folder `output_dir`.
+
+If you are sending multiple patches, it is recommended to include a cover
+letter. A cover letter is an email explaining in brief what the series is
+supposed to do. A cover letter template can be generated by passing
+`--cover-letter` to `git-format-patch`.
+
+After you send your patches, you might get a review suggesting some changes.
+Make those changes, and re-send your patch(es) in reply to the first patch of
+your initial version. Also please mention the version of the patch. This can be
+done by passing `-v X` to `git-format-patch`, where 'X' is the version number
+of the patch(es).
+
+### Using git-send-email
+
+You can use `git-send-email` to send patches generated via `git-format-patch`.
+While you can directly send patches via `git-send-email`, it is recommended
+that you first use `git-format-patch` to generate the emails, audit them, and
+then send them via `git-send-email`.
+
+A pretty good guide to configuring and using `git-send-email` can be found
+[here](https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/)
+
+### Using your email client
+
+If your email client supports sending mbox format emails, you can use
+`git-format-patch` to get an mbox file for each commit, and then send them. If
+there is more than one patch in the series, then all patches after the first
+patch (or the cover letter) need to be sent as replies to the first.
+`git-send-email` does this by default.
+
+### Using GitGitGadget
+
+Since some people prefer a GitHub pull request based workflow, they can use
+[GitGitGadget](https://gitgitgadget.github.io/) to send in patches. The tool
+was originally written for sending patches to the Git project, but it now also
+supports sending patches for git-gui.
+
+Instructions for using GitGitGadget to send git-gui patches, courtesy of
+Johannes Schindelin:
+
+If you don't already have a fork of the [git/git](https://github.com/git/git)
+repo, you need to make one. Then clone your fork:
+
+```
+git clone https://github.com/<your-username>/git
+```
+
+Then add GitGitGadget as a remote:
+
+```
+git remote add gitgitgadget https://github.com/gitgitgadget/git
+```
+
+Then fetch the git-gui branch:
+
+```
+git fetch gitgitgadget git-gui/master
+```
+
+Then create a new branch based on git-gui/master:
+
+```
+git checkout -b <your-branch-name> git-gui/master
+```
+
+Make whatever commits you need to, push them to your fork, and then head over
+to https://github.com/gitgitgadget/git/pulls and open a Pull Request targeting
+git-gui/master.
+
+GitGitGadget will welcome you with a (hopefully) helpful message.
+
+## Signing off
+
+You need to sign off your commits before sending them to the list. You can do
+that by passing the `-s` option to `git-commit`. You can also use the "Sign
+Off" option in Git GUI.
+
+A sign-off is a simple 'Signed-off-by: A U Thor \<author@example.com\>' line at
+the end of the commit message, after your explanation of the commit.
+
+A sign-off means that you are legally allowed to send the code, and it serves
+as a certificate of origin. More information can be found at
+[developercertificate.org](https://developercertificate.org/).
+
+## Responding to review comments
+
+It is quite likely your patches will get review comments. Those comments are
+sent on the Git mailing list as replies to your patch, and you will usually be
+Cc'ed in those replies.
+
+You are expected to respond by either explaining your code further to convince
+the reviewer what you are doing is correct, or acknowledge the comments and
+re-send the patches with those comments addressed.
+
+Some tips for those not familiar with communication on a mailing list:
+
+- Use only plain text emails. No HTML at all.
+- Wrap lines at around 75 characters.
+- Do not send attachments. If you do need to send some files, consider using a
+ hosting service, and paste the link in your email.
+- Do not [top post](http://www.idallen.com/topposting.html).
+- Always "reply all". Keep all correspondents and the list in Cc. If you reply
+ directly to a reviewer, and not Cc the list, other people would not be able
+ to chime in.
--
2.21.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH v3] git-gui: add a readme
2019-10-08 12:17 ` [PATCH v3] " Pratyush Yadav
@ 2019-10-11 21:35 ` Pratyush Yadav
2019-10-12 10:44 ` Bert Wesarg
0 siblings, 1 reply; 11+ messages in thread
From: Pratyush Yadav @ 2019-10-11 21:35 UTC (permalink / raw)
To: git; +Cc: Bert Wesarg, Johannes Schindelin, Junio C Hamano
I'll take the silence to mean there are no further objections, and will
merge this version in to 'master'.
On 08/10/19 05:47PM, Pratyush Yadav wrote:
> 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>
> ---
> Changes in v3:
> - Reword the first paragraph to avoid some repetition. Suggested by
> Junio.
> - Do not mention "written in Tcl" in the intro. Suggested by Junio.
> - Add a list of dependencies.
--
Regards,
Pratyush Yadav
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH v3] git-gui: add a readme
2019-10-11 21:35 ` Pratyush Yadav
@ 2019-10-12 10:44 ` Bert Wesarg
0 siblings, 0 replies; 11+ messages in thread
From: Bert Wesarg @ 2019-10-12 10:44 UTC (permalink / raw)
To: Pratyush Yadav; +Cc: Git Mailing List, Johannes Schindelin, Junio C Hamano
On Fri, Oct 11, 2019 at 11:35 PM Pratyush Yadav <me@yadavpratyush.com> wrote:
>
> I'll take the silence to mean there are no further objections, and will
> merge this version in to 'master'.
correct. FWIW
Acked-by: Bert Wesarg <bert.wesarg@googlemail.com>
>
> On 08/10/19 05:47PM, Pratyush Yadav wrote:
> > 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>
> > ---
> > Changes in v3:
> > - Reword the first paragraph to avoid some repetition. Suggested by
> > Junio.
> > - Do not mention "written in Tcl" in the intro. Suggested by Junio.
> > - Add a list of dependencies.
>
> --
> Regards,
> Pratyush Yadav
^ permalink raw reply [flat|nested] 11+ messages in thread