From 6dd68240ac8c33f6142ff5008730fca3299159cd Mon Sep 17 00:00:00 2001
From: Squibid <me@zacharyscheiman.com>
Date: Fri, 25 Apr 2025 16:20:45 -0500
Subject: [PATCH] update README

---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f7865f9..24e5728 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,10 @@ liking.
 2. `declarative` - packages are declared using simple Lua tables.
 3. `correct` - packages are always loaded in a correct and consistent order.
 
+In addition to the above dep has been built to be completely in control of you,
+the user. With the help of lazy loading you can choose when your plugin loads
+down to the finest detail (examples may be found below).
+
 See also squibid's [neovim-configs][10] for an example of how dep can be used in
 practice.
 
@@ -291,6 +295,60 @@ require "dep" {
 }
 ```
 
+## Lazy loading
+
+Imagine you're using [telescope.nvim][7] and you need to pull it up with a keybind,
+but you don't want to have it load before that moment. With lazy loading you may
+choose to only load it when needed using the built in lazy utils which are made
+available to you as soon as you start using the lazy option.
+
+```lua
+require "dep" {
+  { "nvim-telescope/telescope.nvim",
+    lazy = function(load)
+      load:keymap("n", "<leader>f")
+    end,
+    load = function()
+      require("telescope").setup {}
+      vim.keymap.set("n", "<leader>f", require("telescope.builtin").find_files, {})
+    end
+  }
+}
+```
+
+Say you wanted to use [gitsigns.nvim][9], but only wanted to load it when
+in a git directory OR when you call the Gitsigns command. With the power of lazy
+loading this can be accomplished by simply defining an auto command like so:
+
+```lua
+require "dep" {
+  {
+    "lewis6991/gitsigns.nvim",
+    lazy = function(load)
+      -- load gitsigns if we're in a git repository
+      load:auto({ "BufEnter", "BufNew" }, {
+        callback = function()
+          local paths = vim.fs.find({ ".git", }, { upward = true })
+          if #paths > 0 then
+            load:cleanup()
+          end
+        end
+      })
+
+      -- load gitsigns if the user trys to run the command
+      load:cmd("Gitsigns")
+    end,
+    load = function()
+      require("gitsigns").setup {}
+    end
+  }
+}
+
+```
+
+If you're in the need of a deeper understanding of how the utils work go check
+out `lua/lazy/utils.lua` for the source code.
+
 ## Separating code into modules
 
 Suppose you split your `init.lua` into two files `packages/search.lua` and
@@ -419,5 +477,5 @@ dep is licensed under the [MIT License](LICENSE).
 [6]: https://git-scm.com/
 [7]: https://github.com/nvim-telescope/telescope.nvim
 [8]: https://github.com/tpope/vim-fugitive
-[9]: https://GitHub.com/chiyadev/dep/issues
+[9]: https://github.com/lewis6991/gitsigns.nvim
 [10]: https://git.squi.bid/nvim