head.nvim

Neovim plugin for adding and auto updating file headers.

I'm aware that file headers is probably a solved problem as far as plugins go, but I wanted to make my own for fun, and wanted to practice Lua and Neovim plugin dev more on a project idea I actually thought up working in Xcode. This is a work in progress, and there are some known issues and features not yet implemented.

Features

• Automatically add and update file headers (later).
• Customizable header formats for different file types.
• Dynamic header values with pre-defined symbols.
• Git integration (sort-of). More to be done here.

---

Image to be added here :(

---

⚠️ NOTICE, Known Issues, Missing Features and TODOs (for now):

• auto_update and auto_add are not tested yet, and I'm slightly wary about those function at the moment. I need to actually finish them.

• Removing a header from a file doesn't take into account the current header format vs the header in a file. Example: a 5 line long header could be in a file, but if the format changes and the new header is shorter OR longer, it could add/remove too many lines, messing up the area around the header.

• No default keymaps are set up yet.

• Git "integration" doesn't really exist, yet. It only gets the user name and email from the git config, and doesn't do anything else with git. I want to add more features here, like getting the last commit date, and maybe even the commit message.

• More dynamic values could be added to the header format, these were planned but not implemented yet:

  • @%ma - margin: would handle open space between lines and allow of lines to be all the same max len, creating a full box.
  • @%rs(s) and @%rc(s,n) - similar to margin, but repeats a give character s to either fill the line or repeat n times.
  • @%g... - various git values, like last commit date, commit message, etc.

Install

Requirements

• Neovim >= 0.9.2

{ -- lazy.nvim"956MB/head.nvim",
config=function()
require('head').setup({
-- configuration here
})
end,
}

Default Configuration

{
-- Automatically updates info within the header when saving the fileauto_update=false,
-- Automatically adds a header to a new file when creating it or when opening a file without a headerauto_add=false,
-- Format used for the `@%dc` and `@%dm` symbols (date_created and date_modified)date_format='%m/%d/%y', -- other formats: '%m/%d/%y %H:%M:%S', '%Y-%m-%d %H:%M:%S'-- 'Backup' or manually set username, name, and emailuser='username',
name='name',
email='e@mail.com',
-- Used later for calling the git command and getting various infosgit= {
enabled=true,
bin='git',
},
-- Object containing the default header format and ones for each filetypeheader= {
-- `default` used as the fallback for all filetypes, other files types can be added here with `ft = { ... }` -> `lua = { ... }`default= {
'',
' @%fi',
' @%pr',
'',
' Created by @%na on @%dc',
'',
},
},
}

Keymaps

-- You can set up keymaps in the most basic way like this, or however you prefer:vim.keymap.set('n', '<leader>hu', '<cmd>HeadUpdate<cr>', { desc='[U]pdate [H]eader (add if missing)' })
vim.keymap.set('n', '<leader>hr', '<cmd>HeadRemove<cr>', { desc='[R]emove [H]eader' })
vim.keymap.set('n', '<leader>hc', '<cmd>HeadCheck<cr>', { desc='[C]heck if current file has a [H]eader' })
-- The other commands don't really need keymaps, but you can set them up if you want:-- vim.keymap.set('n', '<leader>hg', '<cmd>HeadGet<cr>', { desc = '[G]et current file [H]eader' })-- vim.keymap.set('n', '<leader>hs', '<cmd>HeadSymbols<cr>', { desc = '[S]how [H]eader symbols list' })-- vim.keymap.set('n', '<leader>hc', '<cmd>HeadConfig<cr>', { desc = 'Get [H]eader [C]onfig (all)' })-- vim.keymap.set('n', '<leader>hc', '<cmd>HeadConfigCurrent<cr>', { desc = 'Get [H]eader [C]onfig (current file type)' })

Usage

Commands

Command	Action
:HeadUpdate	Updates header or adds a new one to the current file
:HeadRemove	Removes the header currently in the file, if it has one
:HeadCheck	Checks if the current file has a header
:HeadGet	Displays the header in the current file, if it has one
:HeadConfig	Prints all defined header formats in your plugin config
:HeadConfigCurrent	Prints the header format for the current file type
:HeadSymbols	Prints the symbol key for header formats

Header Symbols

These symbols correspond to the following dymanic values that can be updated inside the header:

Symbol	Description	Example
@%na	name	First Last
@%us	username	username
@%em	email	e@mail.com
@%fi	file name	file.txt
@%fp	first parent folder	folder/
@%pr	project root	project/
@%pa	path	project/folder/file.txt
@%dc	created date	01/01/01
@%dm	modified date	01/01/01

Use :HeadSymbols command to view this list in Neovim.

Customizing Headers

You can customize headers for specific file types in your configuration, and layout the symbols as you want:

require('head').setup({
header= {
default= { ... },
rs= {
'+ ----------------- +',
'+ @%fi +',
'+ @%pr +',
'',
'+ Created: @%dc +',
'+ Modified: @%dm +',
'+ ----------------- +',
},
-- Add more file type specific headers here
},
})

More examples of header formats (generated by Claude 3.5 Sonnet:

{
minimal= {
'@%fi',
'Created: @%dc',
},
standard= {
'----------------------------------------',
'File: @%fi',
'Author: @%na (@%us)',
'Created: @%dc',
'Modified: @%dm',
'----------------------------------------',
},
detailed= {
'/*',
' * File: @%fi',
' * Path: @%pa',
' * Project: @%pr',
' * Author: @%na <@%em>',
' * Created: @%dc',
' * Last Modified: @%dm',
' */',
},
simple_box= {
'+------------------+',
'| File: @%fi',
'| Author: @%na',
'| Created: @%dc',
'+------------------+',
},
compact= {
'// @%fi | @%us | @%dc | @%pr',
},
markdown_style= {
'# @%fi',
'',
'- **Author:** @%na',
'- **Created:** @%dc',
'- **Modified:** @%dm',
'- **Project:** @%pr',
'',
'## Description',
'',
'[Your file description here]',
},
code_block= {
'/**',
' * File : @%fi',
' * Author : @%na (@%us)',
' * Created : @%dc',
' * Modified : @%dm',
' * Project : @%pr',
' */',
},
hash_style= {
'###########################',
'# File : @%fi',
'# Author : @%us',
'# Created : @%dc',
'# Project : @%pr',
'###########################',
},
simple_lines= {
'------------------------',
'@%fi',
'By: @%na',
'On: @%dc',
'In: @%pr',
'------------------------',
},
minimal_info= {
'@%fi - @%us - @%dc',
'----------------------',
},
}

License

MIT