git-dashboard-nvim

Your git contributions heatmap chart inside your favorite nvim dashboard.

⇁ TOC

• Intro
• Installation
• Getting Started
• Config
• Style Variations
• Contribution
• Social

⇁ Intro

git-dashboard-nvim is a modular solution to display your git commit contributions as an nvim heatmap dashboard that adapts to the current branch and repository. It uses vimdev/dashboard-nvim or goolord/alpha-nvim as the base for the dashboard and this plugin generates the header dynamically that we can pass to dashboard-nvim or alpha-nvim. It allows you to track project based progress in a visual way, making your nvim dashboard look cool while still being useful by showcasing the current git branch and project. I've mainly developed this plugin for myself, so to make sure it looks well for you, check the Style Variations section, to see some fun styling configurations. Take into accout that this plugin is in alpha version and you may encounter some unexpected edge cases.

⇁ Installation

• neovim 0.8.0+ required
• install using your favorite plugin manager (i am using Lazy in this case)
• install using lazy.nvim
• Install nvimdev/dashboard-nvim or goolord/alpha-nvim

{
    'nvimdev/dashboard-nvim',
    event = 'VimEnter',
    dependencies = {
      { 'juansalvatore/git-dashboard-nvim', dependencies = { 'nvim-lua/plenary.nvim' } },
    },
    opts = function()
      local git_dashboard = require('git-dashboard-nvim').setup {}

      local opts = {
        theme = 'doom',
        config = {
          header = git_dashboard,
          center = {
            { action = '', desc = '', icon = '', key = 'n' },
          },
          footer = function()
            return {}
          end,
        },
      }

      -- extra dashboard nvim config ...

      return opts
    end,
}

⇁ Getting Started

The dashboard by default will show a heatmap for the repo in which you are opening nvim and it will track the branch you are currently at (switching branches will change the heatmap to show commits in the respective branch). By default it tracks all commits, but you can specify an author to just track their commits.

⇁ Config

This is the default config, feel free to change things around (some things like chaning months or day labels may look bad if more characters are added)

Default config

      local git_dashboard = require('git-dashboard-nvim').setup {
        fallback_header = '',
        top_padding = 0,
        bottom_padding = 0,
        use_git_username_as_author = false,
        author = '',
        branch = 'main',
        gap = ' ',
        centered = true,
        day_label_gap = ' ',
        empty = ' ',
        empty_square = '□',
        filled_squares = { '■', '■', '■', '■', '■', '■' },
        hide_cursor = true,
        is_horizontal = true,
        show_contributions_count = true,
        show_only_weeks_with_commits = false,
        title = 'repo_name',
        show_current_branch = true,
        days = { 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' },
        months = { 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' },
        use_current_branch = true,
        basepoints = { "master", "main" },
        colors = {
          days_and_months_labels = '#7eac6f',
          empty_square_highlight = '#54734a',
          filled_square_highlights = { '#2a3925', '#54734a', '#7eac6f', '#98c689', '#afd2a3', '#bad9b0' },
          branch_highlight = '#8DC07C',
          dashboard_title = '#a3cc96',
        },
      }

      local opts = {
        theme = 'doom',
        config = {
          header = git_dashboard,
          center = {
            { action = '', desc = '', icon = '', key = 'n' },
          },
          footer = function()
            return {}
          end,
        },
      }

Config Definition

---@class Colors
---@field days_and_months_labels string
---@field empty_square_highlight string
---@field filled_square_highlights string[]
---@field branch_highlight string
---@field dashboard_title string

---@class Config
---@field fallback_header string
---@field top_padding number
---@field bottom_padding number
---@field use_git_username_as_author boolean
---@field author string ignored if use_git_username_as_author is true
---@field is_horizontal boolean
---@field branch string
---@field centered boolean
---@field gap string
---@field day_label_gap string
---@field empty string
---@field hide_cursor boolean
---@field empty_square string
---@field show_contributions_count boolean
---@field show_only_weeks_with_commits boolean
---@field filled_squares string[]
---@field title "owner_with_repo_name" | "repo_name" | "none"
---@field show_current_branch boolean
---@field days string[]
---@field months string[]
---@field use_current_branch boolean
---@field basepoints string[] remove commits from base branch, empty array to disable and show all commits
---@field colors Colors

If you want to have an icons show (Eg. branch icon) install a nerd font and set the following global in your init.lua:

vim.g.have_nerd_font = true

⇁ Style Variations

These are some suggested styles and dashboard variations. If you decide to create your own feel free to commit your config with a screen capture and code!

Default

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {}

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Only weeks with commits

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

With repo owner

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      title = 'owner_with_repo_name',
      show_only_weeks_with_commits = true,
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Updated day labels

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Updated empty square

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      days = { 'в', 'п', 'в', 'с', 'ч', 'п', 'с' },
      show_only_weeks_with_commits = true,
      empty_square = ' ',
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Updated filled squares with different characters

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      days = { 'в', 'п', 'в', 'с', 'ч', 'п', 'с' },
      show_only_weeks_with_commits = true,
      empty_square = ' ',
      filled_squares = { '', '', '', '', '', '' },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Vertical with weekly commits

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      is_horizontal = false,
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Vertical without weekly commits

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      is_horizontal = false,
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Catppuccin theme

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      colors = {
        --catpuccin theme
        days_and_months_labels = '#8FBCBB',
        empty_square_highlight = '#3B4252',
        filled_square_highlights = { '#88C0D0', '#88C0D0', '#88C0D0', '#88C0D0', '#88C0D0', '#88C0D0', '#88C0D0' },
        branch_highlight = '#88C0D0',
        dashboard_title = '#88C0D0',
      },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Different ascii characters

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      filled_squares = { '', '', '', '', '', '' },
      empty_square = '',
      colors = {
        -- tokionight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Different gap and fill ascii

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      filled_squares = { '█', '█', '█', '█', '█', '█' },
      empty_square = ' ',
      gap = '',
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Vertical with different filled and empty squares, and different gap

Code

    local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      is_horizontal = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      filled_squares = { '█', '█', '█', '█', '█', '█' },
      empty_square = ' ',
      gap = '',
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local opts = {
      theme = 'doom',
      config = {
        header = ascii_heatmap,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Tracking more than one branch

Code

        local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      use_current_branch = false,
      branch = 'main',
      title = 'owner_with_repo_name',
      top_padding = 15,
      centered = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local ascii_heatmap2 = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      use_current_branch = true,
      branch = 'main',
      centered = false,
      title = 'none',
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local header = {}

    for _, line in ipairs(ascii_heatmap) do
      table.insert(header, line)
    end

    for _, line in ipairs(ascii_heatmap2) do
      table.insert(header, line)
    end

    local opts = {
      theme = 'doom',
      config = {
        header = header,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Fallback header for when you are not inside a git repository

Code

        local ascii_heatmap = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      use_current_branch = false,
      branch = 'main',
      title = 'owner_with_repo_name',
      top_padding = 15,
      centered = false,
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local ascii_heatmap2 = require('git-dashboard-nvim').setup {
      show_only_weeks_with_commits = true,
      show_contributions_count = false,
      use_current_branch = true,
      branch = 'main',
      centered = false,
      title = 'none',
      days = { 's', 'm', 't', 'w', 't', 'f', 's' },
      colors = {
        -- tokinight colors
        days_and_months_labels = '#61afef',
        empty_square_highlight = '#3e4452',
        filled_square_highlights = { '#61afef', '#61afef', '#61afef', '#61afef', '#61afef', '#61afef' },
        branch_highlight = '#61afef',
        dashboard_title = '#61afef',
      },
    }

    local header = {}

    for _, line in ipairs(ascii_heatmap) do
      table.insert(header, line)
    end

    for _, line in ipairs(ascii_heatmap2) do
      table.insert(header, line)
    end

    local opts = {
      theme = 'doom',
      config = {
        header = header,
        center = {
          { action = '', desc = '', icon = '', key = 'n' },
        },
        footer = function()
          return {}
        end,
      },
    }

Showing a center section

Code

    local git_dashboard = require('git-dashboard-nvim').setup {
      centered = false,
      top_padding = 19,
      bottom_padding = 2,
    }

    local opts = {
      theme = 'doom',
      config = {
        header = git_dashboard,
        center = {
          { action = 'ene | startinsert', desc = ' New File', icon = ' ', key = 'n' },
          { action = 'Telescope oldfiles', desc = ' Recent Files', icon = ' ', key = 'r' },
          { action = 'Telescope live_grep', desc = ' Find Text', icon = ' ', key = 'g' },
          { action = 'Lazy', desc = ' Lazy', icon = '󰒲 ', key = 'l' },
          { action = 'qa', desc = ' Quit', icon = ' ', key = 'q' },
        },
        footer = function()
          return {}
        end,
      },
    }

⇁ Contribution

This project open source, so feel free to fork if you want very specific functionality. If you wish to contribute I am totally willing for PRs, as long as your PR leaves the default look and functionality intact I will accept features that build on top or improve things. I started using nvim around two months ago along with lua, so this is a project I mainly built for myself and to learn a bit more about lua and nvim, but given that I think someone else may enjoy having this as their dashboard I decided to make it open source.

Current loading speed

Tests I'm using plenary and for now I'm just running them using <Plug>PlenaryTestFile %

⇁ Social

• Twitter