# [PATCH v3] gitk: add README with usage, build, and contribution details

2 messages from 2025-08-27 to 2025-08-28. Participants: Michael Rappazzo, Johannes Sixt.
Thread: https://gitlist.dev/t/64049

## Michael Rappazzo, 2025-08-27 22:59

Subject: [PATCH v3] gitk: add README with usage, build, and contribution details
Message-ID: <20250827231417.12449-1-rappazzo@gmail.com>
URL: https://gitlist.dev/e/20250827231417.12449-1-rappazzo%40gmail.com

```
Signed-off-by: Michael Rappazzo <rappazzo@gmail.com>
---
Changes from v2:
 - use 'Gitk' to refer to the software, and 'gitk' to refer to the
   command
 - change the markdown section format to use underlines
 - wrap lines at 70-ish characters
 - add more details and examples in the `make` details

 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..bd3e9a6481
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+Gitk - The Git Repository Browser
+=================================
+
+Gitk is a graphical Git repository browser. It displays the commit
+history of a Git repository as a graph, showing the relationships
+between commits, branches, and tags.
+
+Usage
+=====
+
+To view the history of the current repository:
+ˋˋˋbash
+gitk
+ˋˋˋ
+
+To view the history of specific files or directories:
+ˋˋˋbash
+gitk path/to/file
+gitk path/to/directory
+ˋˋˋ
+
+To view a specific branch or range of commits:
+ˋˋˋbash
+gitk branch-name
+gitk v1.0..v2.0
+ˋˋˋ
+
+For more usage examples and options, see the [gitk manual](https://git-scm.com/docs/gitk).
+
+Building
+========
+
+Gitk is a Tcl/Tk application. It requires Tcl/Tk to be installed on
+your system.
+
+Running directly
+----------------
+
+Gitk can be run from the source directory without installation:
+
+ˋˋˋbash
+./gitk
+ˋˋˋ
+
+This allows for quick testing of changes.
+
+Installation
+------------
+
+To install system-wide, you can use either `make` or `meson`:
+
+ˋˋˋbash
+# Install to default location ($HOME/bin)
+make install
+
+# Install to system-wide location
+sudo make install prefix=/usr/local
+
+# Install to custom location
+make install prefix=/opt/gitk
+
+# 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.
+
+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`) and should
+have commit messages prefixed with `gitk:`.
+
+Email Patches
+-------------
+
+Send patches to git@vger.kernel.org and CC j6t@kdbg.org. See the Git
+project's [patch submission guidelines](https://git-scm.com/docs/SubmittingPatches)
+for detailed instructions on creating and sending patches.
+
+License
+=======
+
+Gitk is distributed under the GNU General Public License, either
+version 2, or (at your option) any later version.
\ No newline at end of file
-- 
2.51.0


```

## Johannes Sixt, 2025-08-28 17:54

Subject: Re: [PATCH v3] gitk: add README with usage, build, and contribution details
Message-ID: <86240b73-c775-4d4d-8904-30e8b536e5be@kdbg.org>
URL: https://gitlist.dev/e/86240b73-c775-4d4d-8904-30e8b536e5be%40kdbg.org
In-Reply-To: <20250827231417.12449-1-rappazzo@gmail.com>

```
Thanks, queued after fixing up this glitch:

> \ No newline at end of file


```