marko.nvim - GitLite

KO | EN

gitlite — search

#security #agents #bash #agent #redis #editor #tensorflow #terminal #cross-platform #mysql

marko.nvim

(★ 16)

Behind the scene, project based mark management 🪝

File Explorer

ZIP Download

- - lint.yaml
  - tests.yaml
- pull_request_template.md
- - config.lua
  - file.lua
  - globals.lua
  - init.lua
  - parser.lua
  - utils.lua
  - yaml.lua
- marko.lua
- init.lua
- basic_test.lua
- config_spec.lua
- file_spec.lua
- init.lua
- integration_spec.lua
- run.lua
- utils.lua
.gitignore
.luacheckrc
.stylua.toml
CHANGELOG.md
debug_module.lua
IMPLEMENTATION.md
LICENSE
MIGRATION.md
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`git clone`

View Details ▼

Clone an existing repository.

git clone {{remote_repository_location}} {{path/to/directory}}

Clone an existing repository into a new directory (the default directory is the repository name):

git clone --recursive {{remote_repository_location}}

Clone an existing repository and its submodules:

git clone {{[-n|--no-checkout]}} {{remote_repository_location}}

Clone only the `.git` directory of an existing repository:

🔍

`lua`

View Details ▼

A powerful, light-weight embeddable programming language.

lua

Start an interactive Lua shell:

lua {{path/to/script.lua}} {{--optional-argument}}

Execute a Lua script:

lua -e '{{print("Hello World")}}'

Execute a Lua expression:

# Project Badges

Tests Visit
Lint Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A project-aware global marks manager for Neovim. Marko automatically isolates global marks per project using Neovim's native ShaDa (shared data) system, ensuring marks from different projects don't interfere with each other.

## Features ✨

- **Project-Scoped Global Marks**: Each project directory gets its own isolated set of global marks
- **Persistent Global Marks**: Marks are automatically saved when you exit Neovim and restored when you return to the same project
- **Leverages Native ShaDa**: Works with Neovim's built-in shared data system
- **Zero Configuration**: Just install and it works automatically
- **Simple Commands**: Easy-to-use commands for managing and inspecting your marks

## Installation 🚀

Using [packer.nvim](https://github.com/wbthomason/packer.nvim):

```lua
use {
  "mohseenrm/marko.nvim",
  priority = 1000,
  lazy = false,
  config = function()
    require("marko").setup()
  end
}
```

Using [lazy.nvim](https://github.com/folke/lazy.nvim):

```lua
{
  "mohseenrm/marko.nvim",
  priority = 1000,
  lazy = false,
  config = function()
    require("marko").setup()
  end
}
```

Or with configuration options using lazy.nvim's `opts` feature:

```lua
{
  "mohseenrm/marko.nvim",
  priority = 1000,
  lazy = false,
  opts = {
    debug = false  -- Set to true for verbose logging
  }
}
```

The `opts` table will be automatically passed to the setup function by lazy.nvim.

## Usage 🪝

### Setting Marks

Marko works with Neovim's uppercase global marks (A-Z). Set marks as you normally would:

```
mA  # Set mark A at current cursor position
mB  # Set mark B at current cursor position
```

### Navigating to Marks

Navigate to marks using the standard Neovim commands:

```
'A  # Jump to the line of mark A
`A  # Jump to the exact position of mark A
```

### Commands

Marko provides the following commands:

- `:MarkoInfo` - Display current project directory, ShaDa file location, and all active global marks
- `:MarkoList` - List all project-specific ShaDa files managed by Marko
- `:MarkoClean` - Delete the ShaDa file for current project (clears all marks, with confirmation)
- `:MarkoSave` - Manually save ShaDa for the current project
- `:MarkoMark {A-Z}` - Set a global mark at the current cursor position (e.g., `:MarkoMark A` sets mark A)

### Configuration

Setup with default options:

```lua
require("marko").setup()
```

Setup with custom options:

```lua
require("marko").setup({
  debug = false  -- Set to true for verbose logging
})
```

## How It Works

Marko leverages Neovim's native ShaDa (shared data) system to isolate marks per project. When you start Neovim:

1. Marko detects your current working directory (absolute path)
2. Sets Neovim's `shadafile` option to a project-specific ShaDa file in `~/.local/state/nvim/marko/`
3. Loads the ShaDa file for that project, restoring all marks from your last session

When you exit Neovim:

1. Neovim automatically saves the current state (marks, registers, history) to the project-specific ShaDa file
2. Next time you open that project, your marks are exactly as you left them

**Key benefit**: Each project directory has completely isolated marks. Opening project A won't show marks from project B, and vice versa. This works with Neovim's native systems instead of trying to override them.

## Features Explained

### Project-Based Isolation

Each project (identified by its absolute working directory path) gets its own ShaDa file stored in `~/.local/state/nvim/marko/`. The filename is generated from the project path to ensure uniqueness.

For example:

- `/home/user/projects/app1` → `~/.local/state/nvim/marko/marko__home_user_projects_app1.shada`
- `/home/user/projects/app2` → `~/.local/state/nvim/marko/marko__home_user_projects_app2.shada`

### ShaDa Files

ShaDa files are Neovim's native format for storing session data. They use MessagePack encoding and handle merging, timestamps, and error recovery automatically. By using ShaDa, Marko benefits from all of Neovim's built-in persistence features without reinventing the wheel.

## Development

Want to contribute to marko.nvim? Here's how to set up your local development environment:

### Prerequisites

- Neovim (version 0.7.0 or higher)
- Lua (5.1 or higher)

### Setup

1. Fork the repository
2. Clone your fork:
   ```bash
   git clone https://github.com/yourusername/marko.nvim
   cd marko.nvim
   ```

### Plugin Structure

- `lua/marko/init.lua`: Main entry point, ShaDa management
- `lua/marko/globals.lua`: Global variable definitions for luacheck
- `plugin/init.lua`: Plugin initialization
- `tests/`: Test suite (needs updating for new approach)

### Running Tests

Tests are written in a simple test framework:

```bash
# Run the full test suite
lua tests/run.lua
```

**Note**: Tests need to be updated to reflect the new ShaDa-based approach.

### Linting

The project uses `luacheck` for static code analysis:

```bash
# Install luacheck via LuaRocks
luarocks install luacheck
export PATH=~/.luarocks/bin:$PATH

# Run luacheck on the entire project
luacheck lua/

# Run luacheck on a specific file
luacheck lua/marko/init.lua
```

Luacheck configuration is managed via the `.luacheckrc` file at the project root.

### Guidelines for Contributing

1. **Create a Feature Branch**: Always work on a feature branch, not directly on `main`
2. **Follow Code Style**: Match the existing style (snake_case for functions and variables, tabs for indentation)
3. **Add Tests**: Add tests for any new functionality
4. **Test Before Pushing**: Run the test suite before submitting a PR
5. **Document Changes**: Update this README.md if adding new features or changing behavior

### Testing Your Changes Locally

To test the plugin in your Neovim environment while developing:

#### With packer.nvim:

```lua
use {
  "~/path/to/marko.nvim",
  config = function()
    require("marko").setup({
      debug = true -- Enable debug logging during development
    })
  end
}
```

Then run `:PackerSync` to load the local version

#### With lazy.nvim:

```lua
{
  dir = "~/path/to/marko.nvim",
  dev = true,
  priority = 1000,
  lazy = false,
  opts = {
    debug = true -- Enable debug logging during development
  }
}
```

Then restart Neovim or run `:Lazy sync` to load the local version

### Debugging

Set the `debug` option to `true` in your setup to enable verbose logging:

```lua
require("marko").setup({
  debug = true
})
```

Messages will be displayed using `vim.notify()` and can be viewed in Neovim.

## License

MIT