Alt

alt is a command line utility that finds the "alternate paths" for the provided path.

alt [OPTIONS] PATH

alt finds alternate file paths for the given PATH based on a similarity ranking. For example, if you were in a Ruby project and ran alt spec/app/queues/fee/user_fee_submission_spec.rb the output would include ranked at the top app/queues/fee/user_fee_submission.rb. In this case the alternate for the test file is the implementation file. It is important to understand that alternate files are simply filenames and paths that rank high in similarity.

alt by default outputs all possible alternate paths in ranked order. In older major versions the behavior was to only output the highest ranked file path. To retain this behavior simply use the truncate option with a value of 1.

This is primarily intended for developers. It is written in Rust. Hence, it is compiled and distributed as a binary.

It was originally written to alternate files in vim, but has no dependency on vim at all and can be used in many other scenarios as it is just a command line utility.

Its interface is as simple as they come.

• Pass it a path as the first argument
• It will print the alternate paths in ranked order on separate lines via standard out

For example:

$ alt spec/app/queues/fee/user_fee_submission_spec.rb
app/queues/fee/user_fee_submission.rb
app/bar/car/user_goal.rb
app/queues/modification/vehicle.rb

For advanced usage & full reference of the command line interface, please refer to the man page via man alt.

Installation

If you are on a platform other than macOS or Arch Linux you will have to build your own version from source.

macOS

To install on macOS we provide a Homebrew tap which provides the alt formula. You can use it by doing the following:

Add the Tap

brew tap "uptech/homebrew-oss"

brew install

brew install uptech/oss/alt

Arch Linux

Install from the AUR:

git clone https://aur.archlinux.org/alt.git
cd alt
makepkg -si

Build from Source

If you are on another platform you will have to build from source. Given that alt is managed via Rust's Cargo. It can build as follows:

$ cargo build --release

Once you have built it successfully you should relocate the target/release/alt binary to a location that exists in your PATH so that you can easily use it. You should also relocate the doc/alt.1 man page to the appropriate location.

Note: The above requires of course that you have rust and Cargo.

Use with NeoVim

There's no NeoVim or Vim plugin. It may not end up needing one; we will see. The snippet below is a basic setup I use in my NeoVim to tie alt into telescope so that I can fuzzy select the ranked alternate paths. For now, you can just stick the code below in your init.lua to invoke alt with <leader>. Note that alt and the NeoVim Lua example below work in both the terminal based NeoVim and GUI based NeoVim.

-- ----------------------------------------------
-- Alternate File Switching
-- ----------------------------------------------
local pickers = require "telescope.pickers"
local finders = require "telescope.finders"
local conf = require("telescope.config").values

local alternates_picker = function(alternates, opts)
  opts = opts or {}
  pickers.new(opts, {
	prompt_title = "alternates",
	finder = finders.new_table {
	  results = alternates
	},
	sorter = conf.generic_sorter(opts),
  }):find()
end

function alt(path)
  local function isempty(s)
	return s == nil or s == ''
  end

  -- This is where you can configure it with CLI options so
  -- it behaves how you want it to.
  local alternates = vim.fn.system("some/path/alt " .. path)
  if isempty(alternates) then
	return nil
  else
	local alternates_table = {}
	for s in alternates:gmatch("[^\r\n]+") do
	  table.insert(alternates_table, s)
	end
	return alternates_table
  end
end

function alt_command(path, alt_handler)
  local current_file_path = vim.fn.expand('%')
  local alternate_file_paths = alt(current_file_path)
  if alternate_file_paths == nil then
	print("No alternate files found for " .. current_file_path .. "!")
  else
	alt_handler(current_file_path, alternate_file_paths)
  end
end

function alt_handler(current_file_path, alternate_file_paths)
  alternates_picker(alternate_file_paths)
end

vim.keymap.set('n', '<leader>.', function()
  alt_command(vim.fn.expand('%'), alt_handler)
end)

Ignoring Things

alt by default ignores hidden directory entries, globs defined in a .ignore file and globs defined in your project's .gitignore and your global .gitignore. It does this because in our experience that is generally the behavior you want. If however you want for example to be able to alternate between hidden files for some reason, you can always use the -a option. If you want to have alt ignore some specific paths/files that you don't want Git to ignore. You can simply define them in the .ignore file at the root of your project.

Contributing

If you interested at all in contributing. Please do. We are a welcoming group and are willing to provide guidance whenever possible.

Please see CONTRIBUTING.md for more details on contributing.

License

alt is Copyright © 2016 - 2023 UpTech Works, LLC. It is free software, and may be redistributed under the terms specified in the LICENSE file.

About Uptech Studio

alt is maintained and funded by Uptech Studio, a software design & development studio.

We love open source software. See our other projects or hire us to design, develop, and grow your product.