@@ 1,61 1,160 @@
-# Repo Url
+# Repo URL
-Vim plugins to easily go from a source code file to a valid URL.
+RepoURL is a lua plugin for Neovim that generates URLs to the code repository of the file being edited.
-# Support
+
-**Git**
+## ✨ Features
-The following Git repository types are supported:
+- 🔗 Easily **share permalinks** with friends and colleagues
+- 🏭 Supports many software forges **out of the box**
+- ⚙️ Customize and **extend support** for additional software forges to fit your workflow perfectly.
+- 🐹 Special **support for Go**'s `go.mod` and `go.sum` files as well as files in your `GOMODCACHE`
-- [Github](https://github.com/)
-- [Gitlab](https://gitlab.com/)
-- [Sourcehut](https://sourcehut.org/)
+## 📦 Installation
-**Go cache**
+Install the plugin with your preferred package manager:
-- Simple cases work
+### [lazy.nvim](https://github.com/folke/lazy.nvim)
+```lua
+{
+ url = "https://git.sr.ht/~tomleb/repo-url.nvim",
+ config = function()
+ local ru = require 'repo-url'
+ require('repo-url').setup {
+ -- your configuration comes here
+ -- or leave it empty to use the default settings
+ -- refer to the configuration section below
+ },
+ end,
+}
+```
+
+## ⚙️ Configuration
+
+RepoURL does not provide keymaps. Instead, you are required to assign them
+yourselves. Here's an example configuration.
+
+```lua
+{
+ url = "https://git.sr.ht/~tomleb/repo-url.nvim",
+ config = function()
+ local ru = require 'repo-url'
+ require('repo-url').setup {}
+
+ vim.keymap.set({ 'n', 'v' }, '<leader>rt', ru.copy_blob_url, { desc = 'Copy blob URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rT', ru.open_blob_url, { desc = 'Open blob URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rb', ru.copy_blame_url, { desc = 'Copy blame URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rB', ru.open_blame_url, { desc = 'Open blame URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rh', ru.copy_history_url, { desc = 'Copy history URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rH', ru.open_history_url, { desc = 'Open history URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rr', ru.copy_raw_url, { desc = 'Copy raw URL' })
+ vim.keymap.set({ 'n', 'v' }, '<leader>rR', ru.open_raw_url, { desc = 'Open raw URL' })
+
+ -- For Go's go.mod file, generate permalinks to the dependency under the
+ -- cursor and copy to the clipboard or open in the default browser.
+ vim.api.nvim_create_autocmd('FileType', {
+ pattern = 'gomod',
+ group = filetype,
+ callback = function(args)
+ vim.keymap.set('n', '<leader>rg', function()
+ ru.copy_gomod_blob_url()
+ end, { desc = 'Copy gomod URL' })
+ vim.keymap.set('n', '<leader>rG', function()
+ ru.open_gomod_blob_url()
+ end, { desc = 'Open gomod URL' })
+ end,
+ })
+
+ -- For Go's go.sum file, generate permalinks to the dependency under the
+ -- cursor and copy to the clipboard or open in the default browser.
+ vim.api.nvim_create_autocmd('FileType', {
+ pattern = 'gosum',
+ group = filetype,
+ callback = function(args)
+ vim.keymap.set('n', '<leader>rg', function()
+ ru.copy_gosum_blob_url()
+ end, { desc = 'Copy gosum URL' })
+ vim.keymap.set('n', '<leader>rG', function()
+ ru.open_gosum_blob_url()
+ end, { desc = 'Open gosum URL' })
+ end,
+ })
+ end,
+}
+```
+
+RepoURL comes with the following defaults:
+
+```lua
+{
+ -- Ordered list of remotes to look for to generate the permalinks for git
+ -- repositories
+ preferred_remotes = { 'origin' },
+ -- Mapping of software forge hostname to URL builders. More details in the URL
+ -- builder's section.
+ urls_by_hostname = {
+ ['github.com'] = M.urls.github,
+ ['git.sr.ht'] = M.urls.sourcehut,
+ ['gitlab.com'] = M.urls.gitlab,
+ ['gitlab.alpinelinux.org'] = M.urls.gitlab,
+ ['codeberg.org'] = M.urls.codeberg,
+ ['go.googlesource.com'] = M.urls.gitiles,
+ ['git.zx2c4.com'] = M.urls.cgit,
+ },
+}
+```
-# Installation
+### URL builder
-Using [lazy.nvim]:
+You can teach RepoURL how to generate URLs for forges that it does not support
+out of the box.
+
+Simply provide an object with the following properties:
```lua
- {
- url = "https://git.sr.ht/~tomleb/repo-url.nvim",
- config = function()
- local ru = require 'repo-url'
- require('repo-url').setup {
- preferred_remotes = { 'upstream', 'origin' },
- urls_by_hostname = {
- ['gitlab.alpinelinux.org'] = ru.urls.gitlab,
- },
- }
-
- vim.keymap.set({ 'n', 'v' }, '<leader>rt', ru.copy_blob_url, { desc = 'Copy blob URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rT', ru.open_blob_url, { desc = 'Open blob URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rb', ru.copy_blame_url, { desc = 'Copy blame URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rB', ru.open_blame_url, { desc = 'Open blame URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rh', ru.copy_history_url, { desc = 'Copy history URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rH', ru.open_history_url, { desc = 'Open history URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rr', ru.copy_raw_url, { desc = 'Copy raw URL' })
- vim.keymap.set({ 'n', 'v' }, '<leader>rR', ru.open_raw_url, { desc = 'Open raw URL' })
-
- vim.api.nvim_create_autocmd('FileType', {
- pattern = 'gomod',
- group = filetype,
- callback = function(args)
- vim.keymap.set('n', '<leader>rg', function()
- ru.copy_gomod_blob_url()
- end, { desc = 'Copy gomod URL' })
- vim.keymap.set('n', '<leader>rG', function()
- ru.open_gomod_blob_url()
- end, { desc = 'Open gomod URL' })
- end,
- })
- end,
- }
+{
+ -- Link goes to default software forge browsing page. Required.
+ blob_url = function(opts)
+ return "https://..."
+ end,
+ -- Link goes to the blame page, showing which commit and author last modified
+ -- each line. Optional.
+ blame_url = function(opts)
+ return "https://..."
+ end,
+ -- Link goes to the history page, showing all previous commits affecting the
+ -- current file. Optional.
+ history_url = function(opts)
+ return "https://..."
+ end,
+ -- Link goes to the raw file. Optional.
+ raw_url = function(opts)
+ return "https://..."
+ end,
+ -- Link goes to the tree that the current file belongs to. Optional.
+ tree_url = function(opts)
+ return "https://..."
+ end,
```
-[lazy.nvim]: https://github.com/folke/lazy.nvim
+These functions will be given the following object (`opts`):
+
+```lua
+{
+ -- The base URL (eg: "https://github.com/my-org/my-project")
+ base_url = "",
+ -- The commit hash OR the tag
+ ref = "",
+ -- The filepath relative to the root of the repository. Not given for
+ -- `history_url` and `tree_url`.
+ filepath = "",
+ -- For normal mode, the line under the cursor. For range mode, the beginning
+ -- of the range.
+ line1 = 0,
+ -- For normal mode, the line under the cursor. For range mode, the end of the
+ -- range.
+ line2 = 0,
+}
+```