aboutsummaryrefslogtreecommitdiff
path: root/doc/git-permalink.en.1.in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/git-permalink.en.1.in')
-rw-r--r--doc/git-permalink.en.1.in190
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/git-permalink.en.1.in b/doc/git-permalink.en.1.in
new file mode 100644
index 0000000..63d8f0e
--- /dev/null
+++ b/doc/git-permalink.en.1.in
@@ -0,0 +1,190 @@
+.TH GIT-PERMALINK 1 @DATE@ "git-permalink @VERSION@" "git-permalink user manual"
+
+
+.SH NAME
+
+git-permalink - Git extension to generate web permalinks of files in a repository.
+
+
+.SH SYNOPSIS
+
+\fBgit-permalink\fR [\fIOPTIONS\fR] \fIFILE\fR [\fILINENO\fR]
+
+
+.SH DESCRIPTION
+
+\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.
+
+\fBgit-permalink\fR then uses \fBxdg-open\fR(1) to open the URL.
+
+.SH OPTIONS
+
+.TP
+\fB-p\fR
+Only print the web URL link to STDOUT, 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 CONFIGURATION
+
+.SS SUPPORTED REMOTES
+
+The current supported remotes are:
+
+.RS
+.IP \(bu
+git.euandreh.xyz (where git-permalink itself is hosted =p)
+.IP \(bu
+sourcehut
+.IP \(bu
+git.kernel.org
+.IP \(bu
+savannah
+.IP \(bu
+notabug
+.IP \(bu
+codeberg
+.IP \(bu
+bitbucket
+.IP \(bu
+pagure
+.IP \(bu
+gitlab
+.IP \(bu
+github
+.RE
+
+Patches to add support for more source code forges are welcome!
+
+See
+.UR https://euandreh.xyz/git-permalink/TODOs.html#task-cebc5298-17ad-5c60-dfa5-a25b66433a3a
+#task-cebc5298-17ad-5c60-dfa5-a25b66433a3a
+.UE
+for discussion and more information.
+
+.SS OVERRIDES
+
+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).
+
+There are two configuration options available:
+
+.TP
+\fBgit-permalink.template-file-commit\fR
+An URL template where the name of the \fIfile\fR comes first, and the \fIcommit\fR comes second.
+cgit uses this style of URL, with something like in:
+
+.nf
+ https://git.euandreh.xyz/fallible/tree/%s?id=%s
+.fi
+
+On this example, the name of the \fIfile\fR comes first and \fIcommit\fR comes at the very end after "id=".
+
+.TP
+\fBgit-permalink.template-commit-file\fR
+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:
+
+.nf
+ https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s
+.fi
+
+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 EXAMPLES
+
+Open \fIsrc/fold.c\fR of a project with its origin pointing to \fIsourcehut\fR:
+
+.nf
+ $ git permalink src/fold.c 125
+ Opening https://git.sr.ht/~sircmpwn/ctools/tree/fbf17d92f5ed1c38983f73df912f051ad0f9ef2d/item/src/fold.c#L125
+.fi
+
+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):
+
+.nf
+ $ git permalink -p nongnu/packages/clojure.scm 59-94
+ https://gitlab.com/nonguix/nonguix/-/blob/c9d7f30bcbd3a6e3076e56a972c33963c73c4d58/nongnu/packages/clojure.scm#L59-94
+.fi
+
+.P
+Configure an URL override, and open the file \fIsrc/app_add.c\fR without selecting an specific line:
+
+.nf
+ $ 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
+.fi
+
+.P
+Open file called \fI--help\fR:
+
+.nf
+ $ git permalink -- --help
+ Opening https://git.euandreh.xyz/non-existent-repository/tree/--help?id=470a9fa9329495cfcbef8cc5e32e3a38d3c3103e
+.fi
+
+.SH EXIT STATUS
+
+.TP
+.B 0
+Successful execution.
+
+.TP
+.B 1
+Unsupported remote.
+See the supported list in SUPPORTED REMOTES, and how to add custom ones in OVERRIDES.
+
+.TP
+.B 2
+Invalid arguments.
+
+
+.SH SEE ALSO
+
+\fBgit-config\fR(1)
+\fBxdg-open\fR(1)
+
+
+.SH AUTHORS
+
+.MT eu@euandre.org
+EuAndreh
+.ME
+and contributors.
+
+
+.SH BUGS
+
+.IP \(bu
+Report bugs to the
+.MT ~euandreh/public\-inbox@lists.sr.ht
+mailing list
+.ME .
+Use the subject "\f(CR[git\-permalink] BUG or TASK:
+<description>\fR".
+.IP \(bu
+Browse bugs
+.UR https://euandreh.xyz/git\-permalink/TODOs.html
+online
+.UE .
+.IP \(bu
+.UR https://euandreh.xyz/git\-permalink/
+Homepage
+.UE .
+.IP \(bu
+.UR https://lists.sr.ht/~euandreh/public\-inbox?search=%5Bgit\-permalink%5D
+Comments and discussions
+.UE .