gitk: add README.md with contribution guidelines
PATCH 1/1 gitk: add README.md with contribution guidelines
--- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 README.md
README.md new file +63 -0
@@ -0,0 +1,63 @@ +# gitk - The Git Repository Browser + +This is the official repository for gitk, a graphical Git repository browser. + +## Repository Status + +- **Official Repository**: https://github.com/j6t/gitk +- **Integration**: This repository is regularly merged into the main Git repository (git.git) via subtree merges into the `gitk-git/` subdirectory + +## Contributing + +Contributions are welcome! The preferred method for submitting patches is via email to the Git mailing list, as this allows for more thorough review and broader community feedback. However, GitHub pull requests are also accepted. + +All commits must be signed off (use `git commit --signoff`). + +### Email Patches +- Create patches from this repository (github.com/j6t/gitk), not from the `gitk-git/` subdirectory in git.git +- Send patches to the Git mailing list: [email protected] and CC the maintainer: [email protected] +- Follow the Git project's patch submission guidelines +- Include `[PATCH gitk]` in the subject line + +#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +``` + +For `git send-email` configuration, see the [documentation](https://git-scm.com/docs/git-send-email) (search for "Examples of SMTP Servers"). + +For information about subscribing to the Git mailing list, see [subscription info](https://git.wiki.kernel.org/index.php/GitCommunity). Note that subscription is not required to participate in patch discussions. + +### GitHub Pull Requests +- Fork this repository and create a feature branch +- Submit a pull request with a clear description of your changes + +## Building + +gitk is a Tcl/Tk application. It requires Tcl/Tk to be installed on your system. + +### Running directly +```bash +./gitk +``` + +### Installation +To install system-wide, you can use either `make` or `meson`: + +```bash +# Using Make +make install + +# Using Meson +meson setup builddir +meson compile -C builddir +meson install -C builddir +``` + +Both build systems will handle setting the correct Tcl/Tk interpreter path and installing translation files. + +## License + +gitk is distributed under the GNU General Public License, either version 2, or (at your option) any later version.
Signature · 1 line
2.51.0
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```
Just being curious, but does the project strongly discourage a multi-patch topic?
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
Thanks.
Quoted 12 lines · Junio C Hamano
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```Just being curious, but does the project strongly discourage a multi-patch topic?
I don't believe so. I think most people know how to submit a github PR, but J6t has mentioned that he prefers the mailing list (as noted in the readme). So I wrote a simple example to show that patching by email doesn't have to be scary.
Quoted 3 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I can revise. I will wait for more comments before sending a v2.
Quoted 14 lines · Mike Rappazzo
Quoted 12 lines · Junio C Hamano
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```Just being curious, but does the project strongly discourage a multi-patch topic?
Quoted 4 lines
I don't believe so. I think most people know how to submit a github PR, but J6t has mentioned that he prefers the mailing list (as noted in the readme). So I wrote a simple example to show that patching by email doesn't have to be scary.
As the original assumes that you are on the branch where you are taking the patch(es) from, perhaps
$ git format-patch --subject-prefix='PATCH gitk' @{u}..would work? I was mostly reacting to the "-1" on the command line.
Quoted 4 lines
Quoted 2 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I can revise. I will wait for more comments before sending a v2.
Thanks.
Quoted 22 lines · Junio C Hamano
Quoted 14 lines · Mike Rappazzo
Quoted 12 lines · Junio C Hamano
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```Just being curious, but does the project strongly discourage a multi-patch topic?
Quoted 4 lines
I don't believe so. I think most people know how to submit a github PR, but J6t has mentioned that he prefers the mailing list (as noted in the readme). So I wrote a simple example to show that patching by email doesn't have to be scary.
Quoted 6 lines
As the original assumes that you are on the branch where you are taking the patch(es) from, perhaps
$ git format-patch --subject-prefix='PATCH gitk' @{u}..would work? I was mostly reacting to the "-1" on the command line.
@{u}.. is funny, because that seems to assume that you haven't pushed your changes to its upstream yet. I could say master.. but that assumes that you named the branch that (as opposed to main or something). I will try a few different ways and see how they feel. As I said, I just wanted an example to demystify patching by email. I think if I add something above to clarify that this is just an example and not verbose instructions it could help too.
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I can revise. I will wait for more comments before sending a v2.
Thanks.
Quoted 31 lines · Mike Rappazzo
Quoted 22 lines · Junio C Hamano
Quoted 14 lines · Mike Rappazzo
Quoted 12 lines · Junio C Hamano
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```Just being curious, but does the project strongly discourage a multi-patch topic?
Quoted 4 lines
I don't believe so. I think most people know how to submit a github PR, but J6t has mentioned that he prefers the mailing list (as noted in the readme). So I wrote a simple example to show that patching by email doesn't have to be scary.
Quoted 6 lines
As the original assumes that you are on the branch where you are taking the patch(es) from, perhaps
$ git format-patch --subject-prefix='PATCH gitk' @{u}..would work? I was mostly reacting to the "-1" on the command line.
Quoted 7 lines
@{u}..is funny, because that seems to assume that you haven't pushed your changes to its upstream yet. I could saymaster..but that assumes that you named the branch that (as opposed tomainor something). I will try a few different ways and see how they feel. As I said, I just wanted an example to demystify patching by email. I think if I add something above to clarify that this is just an example and not verbose instructions it could help too.
It is less funny when @{u} is the branch you started your work from and where you hope to integrate to, as in
git switch -c topic origin/master
or something.
Then, you might use @{push} to refer to that "somewhere else" you push to that is not the place to which you hope your changes will go. It is certainly different from lots of GitHub- and similar tutorials that encourage "git push -u <remote> <branch>," which sets @{upstream} to what I prefer to use @{push} for. Granted, those tutorials use something closer to a centralized workflow, and what I'm describing (what mailing list flows are?) is more triangular.
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I can revise. I will wait for more comments before sending a v2.
Linking to https://git-send-email.io/ is probably the best advice on making sending patches less scary.
Signature · 1 line
D. Ben Knoble
Quoted 12 lines · Junio C Hamano
README.md line 27
Quoted 6 lines · Michael Rappazzo
README.md new file +6
-0+#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +```Just being curious, but does the project strongly discourage a multi-patch topic?
Quoted 2 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I alwyays use
git format-patch ... -opatchez
cat patchez/* | less
Because sending out something weird to a mailing list gives me the chills. (And there might be format-patch bugs.)
Signature · 1 line
Kristoffer Haugsbakk
Quoted 10 lines · Kristoffer Haugsbakk
Quoted 2 lines
It would be really nice if you add "review them here before you run send-email" step between these two commands ;-).
I alwyays use
git format-patch ... -opatchez
cat patchez/* | lessBecause sending out something weird to a mailing list gives me the chills. (And there might be format-patch bugs.)
Thanks for a tip.
It matches what I do, except that I use ./+jc/<topic-name>/ directories as the staging area, as I tend to keep what I sent out for a few days, and I strongly prefer to give its own directory to each topic, to avoid "git send-email *.patch" sending out random unrelated patches.
Thank you. However, I hate to say that this isn't the text that I would expect on the front page of the repository.
An important part is missing: first-time visitors are not addressed at all. We should state what this software is about and show examples how to use it effectively, perhaps include a link to the manual
(https://git-scm.com/docs/gitk).
I would prefer not to have format-patch+send-email tutorial in this text nor how to make Github PRs. It is OK to have links to tutorials. The prefix [PATCH gitk] hasn't been used in the past, but we do have the convention that commit summaries have the prefix 'gitk:'. This alone distinguishes submissions sufficiently (and then also simplifies using 'git format-patch' a bit).
Do not say that "this is the official repository". Remember that every clone would say that, too. That would be confusing. In the Git world, this status isn't achieved by proclamation, but by convention.
I wouldn't include the details how Gitk is also shipped with the Git repository, but at most that it is. It is not even necessary to discourage people from making patches in the gitk-git/ directory. git am -3 can cope with such patches quite well. Allowing such contributions lowers the entry barrier.
Am 20.08.25 um 21:52 schrieb Michael Rappazzo:
Quoted 76 lines
Signed-off-by Michael Rappazzo <[email protected]>--- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 README.mdREADME.md new file +63
-0@@ -0,0 +1,63 @@ +# gitk - The Git Repository Browser + +This is the official repository for gitk, a graphical Git repository browser. + +## Repository Status + +- **Official Repository**: https://github.com/j6t/gitk +- **Integration**: This repository is regularly merged into the main Git repository (git.git) via subtree merges into the `gitk-git/` subdirectory + +## Contributing + +Contributions are welcome! The preferred method for submitting patches is via email to the Git mailing list, as this allows for more thorough review and broader community feedback. However, GitHub pull requests are also accepted. + +All commits must be signed off (use `git commit --signoff`). + +### Email Patches +- Create patches from this repository (github.com/j6t/gitk), not from the `gitk-git/` subdirectory in git.git +- Send patches to the Git mailing list: [email protected] and CC the maintainer: [email protected] +- Follow the Git project's patch submission guidelines +- Include `[PATCH gitk]` in the subject line + +#### Creating and Sending Patches +After committing your changes: +```bash +git format-patch -1 --subject-prefix="PATCH gitk" +git send-email [email protected] [email protected] *.patch +``` + +For `git send-email` configuration, see the [documentation](https://git-scm.com/docs/git-send-email) (search for "Examples of SMTP Servers"). + +For information about subscribing to the Git mailing list, see [subscription info](https://git.wiki.kernel.org/index.php/GitCommunity). Note that subscription is not required to participate in patch discussions. + +### GitHub Pull Requests +- Fork this repository and create a feature branch +- Submit a pull request with a clear description of your changes + +## Building + +gitk is a Tcl/Tk application. It requires Tcl/Tk to be installed on your system. + +### Running directly +```bash +./gitk +``` + +### Installation +To install system-wide, you can use either `make` or `meson`: + +```bash +# Using Make +make install + +# Using Meson +meson setup builddir +meson compile -C builddir +meson install -C builddir +``` + +Both build systems will handle setting the correct Tcl/Tk interpreter path and installing translation files. + +## License + +gitk is distributed under the GNU General Public License, either version 2, or (at your option) any later version.