Quickstart

Feature walk-through.

How do I start tracking files?

• Create a mark by :Mark. You can map a key to it.
• Now, open the telescope window by :Track views.
• You can move the entries up and down by pressing i_<C-n> and i_<C-p>.
• You can select all entries by pressing v. And, <cr> to open.
• Or, press <tab> to select multiple entries.
• You can delete an entry by i_<C-d>.
• You can change the view name in telescope by pressing i_<C-e> on the entry.
• Close the telescope window then do :Unmark.
• Open :Track views again. And, you should see the mark being erased.

Note that, you can also track commands, man-pages and help-docs.

How do branches work?

• Open :Track branches.
• If the picker is empty then the current directory is not being tracked.
• Then start by marking a file in that directory :Mark some/path/to/file or, just :Mark.
• Now, open :Track branches again. You will see a main branch being created.
• You can change the branch name in telescope by pressing i_<C-e> on the entry.
• :NewBranch will create another branch with an auto-generated label and replace the place of the main branch.
• Try Track branches again.
• :SwapBranch will swap the current main branch with the alternate branch. This functions the same way as Vim's default ^ mapping.

Note that, there can only be one main branch and one alternate branch. And, a branch will always have a main branch. It is not recommended to remove it.

How do I mark a terminal command?

• Open terminal by :terminal ls /sys/class
• Alternatively, you can also do :edit term://ls /sys/class
• Then :Mark that buffer.
• Open :Track and you should see the command being stored there.

See :help terminal for more details.

How do I mark a command that'll run on a particular directory?

• Open terminal by :edit term:///home/dharmx//rg --files \| awk -F'.' '{print $NF}'
• Then :Mark that buffer.
• Open :Track and you should see the command being stored there.
• Run it by pressing enter and it should run that command in that particular directory.

What else can we mark?

• You can mark websites i.e. :Mark https://www.google.com/search?q=gnu+rule34.
• You can mark manpages i.e. :Mark man://find(1).
• You can mark a directory as well.

Note that, selecting a directory i.e. tracked will :chdir into that directory and refresh the UI for viewing that directory's marks. This behavior is off by default.

Additionally, while you can mark virtually anything, it is not recommended to do so. This is because only a few filetypes are actually handled. For instance, marking a PDF file and opening it won't open it in a PDF reader but in Neovim albeit you can use on_choose for each UI to override that.

How do I exclude files that should not be marked?

Just pass an exclude list into the setup function.

-- we use Lua patterns for this
-- see: https://www.lua.org/pil/20.1.html
-- see: https://www.lua.org/pil/20.2.html
require("track").setup({
  exclude = {
    vim.env.XDG_CONFIG_HOME .. "/nvim/.*", -- always skip
    "lua/track/pad%.lua", -- does not allow marking
    ["^%.git/.*$"] = true, -- does not allow marking
    ["^%.git$"] = false, -- allow marking
    ["^LICENSE$"] = true, -- does not allow marking
  },
})

Note that, Lua patterns are used for this normal regex expressions will not completely work.

What are serial mappings?

Open any UI and then press any entry's line number and it'll run the config.{pickers.views,pickers.branches,pad}.hooks.on_serial callback on it.

So, if you open :Track pad and press 3 then it should open the entry at that line number.

Note that, this feature is disabled by default. Pass serial_map = true for pickers.views, pickers.branches and pad.

require("track").setup({
  pad = { serial_map = true },
  pickers = {
    branches = { serial_map = true },
    views = { serial_map = true },
  },
})

How do I link another Root into my Branch?

Firstly, make sure you enable switch_directory option for pad and pickers.views.

require("track").setup({
  pad = { switch_directory = true },
  pickers = {
    views = { switch_directory = true },
  },
})

Run mkdir -p ~/Projects/{X,Y} && cd ~/Projects/X && nvim. Then run the following commands in Neovim.

:Mark ~/Projects/Y " currently on project X
:chdir ~/Projects/Y
:Mark ~/Projects/X " currently on project Y
:Track views

And, now select the ~/Project/X entry and it'll switch to that root. Now, note that you cannot go back to the previous if you haven't made a link to it manually before.

So, by default if you open :Track pad and press 3 then it should open the entry at that line number.

How to add custom mappings for telescope pickers?

Firstly, take a look at what functionalities require("telescope._extensions.track.actions") module provides.

Then pass attach_mappings into the setup function.

require("track").setup({
  pickers = {
    views = {
      attach_mappings = function(_, map)
        local actions = require("telescope.actions") -- telescope builtin
        map("n", "q", actions.close)
        map("n", "v", actions.select_all)

        local track_actions = require("telescope._extensions.track.actions") -- track.nvim builtin
        map("n", "D", actions.select_all + track_actions.delete_view)
        map("n", "dd", track_actions.delete_view)
        map("n", "s", track_actions.change_mark_view)
        map("n", "<C-b>", track_actions.delete_buffer)
        map("n", "<C-j>", track_actions.move_view_next)
        map("n", "<C-k>", track_actions.move_view_previous)
        return true -- compulsory
      end,
    },
  },
})