doc/git-permalink.1: Write initial version

1 files changed, 157 insertions, 0 deletions

diff --git a/doc/git-permalink.1 b/doc/git-permalink.1
index e69de29..dbc8c55 100644
--- a/doc/git-permalink.1
+++ b/doc/git-permalink.1
@@ -0,0 +1,157 @@
+.TH GIT-PERMALINK 1 @DATE@ "git-permalink @VERSION@
+.
+.
+.SH NAME
+git-permalink - Git extension to generate web permalinks of files in a repository
+.
+.
+.SH SYNOPSYS
+.P
+\fBgit-permalink\fR [\fI-p\fR] \fIFILE\fR [\fILINENO\fR]
+.
+.
+.SH DESCRIPTION
+.
+.P
+\fBgit-permalink\fR will use Git itself to get a) the commit at \fIHEAD\fR and b) the \fIremote.origin.url\fR via \fBgit-config\fR(1), and optionally c) an URL template override.
+It then uses those values to build a permalink URL, with the commit included on it to ensure it is \fIpermanent\fR, and optionally the line number of the selected file.
+.
+.P
+\fBgit-permalink\fR then uses \fBxdg-open\fR(1) to open the URL.
+.
+.SH OPTIONS
+.
+.TP
+.B -p
+Only print the web URL link, don't try to open it with \fBxdg-open\fR(1) or do anything else.
+By default this is turned off.
+.
+.TP
+\fB--help\fR, \fB-h\fR
+Show show help text.
+.
+.TP
+\fB--version\fR, \fB-V\fR
+Show version number.
+.
+.
+.SH OVERRIDES
+.P
+If you want to configure the permalink URL template for a project with an unsupported origin you can do so via \fBgit-config\fR(1).
+.
+.P
+There are two configuration options available:
+.
+.TP
+.B git-permalink.template-commit-file
+An URL template where the \fIcommit\fR comes first, and the name of the \fIfile\fR comes second.
+cgit uses this style of URL, with something like in:
+.EX
+
+https://git.euandreh.xyz/fallible/tree/%s?id=%s
+
+.EE
+On this example, the \fIfile\fR comes first and \fIcommit\fR comes at the very end after "id=".
+.
+.TP
+.B git-permalink.template-file-commit
+An URL template where the \fIcommit\fR comes first, and the name of the \fIfile\fR comes second.
+sourcehut uses this style of URL, with something like:
+.EX
+
+https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s
+
+.EE
+On this example, the \fIcommit\fR comes first on the URL path, and the \fIfile\fR name comes at the end.
+.
+.P
+If none of those values are found by \fBgit-config\fR(1) and \fBgit-permalink\fR can't guess the URL, it exits with an error.
+.
+.
+.SH SUPPORTED REMOTES
+.P
+The current supported remotes are:
+.
+.IP
+git.euandreh.xyz
+.IP
+sourcehut
+.IP
+savannah
+.IP
+gitlab
+.IP
+github
+.
+.P
+Patches to add support for more source code forges are welcome!
+.br
+See
+.UR https://euandreh.xyz/git-permalink/TODOs.html#task-cebc5298-17ad-5c60-dfa5-a25b66433a3a
+.UE
+for discussion and more information.
+.
+.SH EXAMPLES
+.
+.P
+Open \fIsrc/fold.c\fR of a project with its origin pointing to \fIsourcehut\fR:
+.RS
+.EX
+
+$ git permalink src/fold.c 125
+Opening https://git.sr.ht/~sircmpwn/ctools/tree/fbf17d92f5ed1c38983f73df912f051ad0f9ef2d/item/src/fold.c#L125
+.EE
+.RE
+.
+.P
+Generate link for lines 59 through 94 of \fInongnu/packages/clojure.scm\fR on a project hosted on \fIgitlab\fR, but only print it \fIwithout\fR opening with \fBxdg-open\fR(1):
+.RS
+.EX
+
+$ git permalink -p nongnu/packages/clojure.scm 59-94
+https://gitlab.com/nonguix/nonguix/-/blob/c9d7f30bcbd3a6e3076e56a972c33963c73c4d58/nongnu/packages/clojure.scm#L59-94
+.EE
+.RE
+.
+.P
+Configure an URL override, and open the file \fIsrc/app_add.c\fR without selecting an specific line:
+.RS
+.EX
+
+$ git config git-permalink.template-file-commit 'https://git.alpinelinux.org/apk-tools/tree/%s?id=%s'
+$ git permalink src/app_add.c
+Opening https://git.alpinelinux.org/apk-tools/tree/src/app_add.c?id=aeeb119fd8652c044cd5ceebce572b5c716914e3
+.EE
+.RE
+.
+.
+.SH SEE ALSO
+.P
+\fBgit-config\fR(1)
+\fBxdg-open\fR(1)
+.
+.
+.SH AUTHORS
+.P
+EuAndreh
+.MT eu@euandre.org
+.ME
+and contributors.
+.
+.
+.SH BUGS
+Report bugs to:
+.MT ~euandreh/public-inbox@lists.sr.ht
+.ME
+.br
+Browse bugs at:
+.UR https://euandreh.xyz/git-permalink/TODOs.html
+.UE
+.br
+Home page:
+.UR https://euandreh.xyz/git-permalink/
+.UE
+.br
+Discussions:
+.UR https://lists.sr.ht/~euandreh/public-inbox?search=[git-permalink]
+.UE