Skip to content

Commit 893cc20

Browse files
adia-devadia-dev
committed
readme: Added the ADVANCED section
1 parent 85b8abd commit 893cc20

File tree

2 files changed

+185
-0
lines changed

2 files changed

+185
-0
lines changed

‎ADVANCED.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Advanced Usage
2+
3+
This document covers the more advanced features and configuration options available in **CpyBuffers.nvim**, including:
4+
5+
- Customizing file search behavior (hidden files, advanced `rg` options, etc.)
6+
- Adjusting display and labeling
7+
- Using advanced keymaps and commands
8+
- Configuring sorting behavior
9+
- Integrating with custom Telescope sorters and extensions
10+
11+
## Table of Contents
12+
13+
- [Advanced File Filtering](#advanced-file-filtering)
14+
- [Custom Labeling and Display Formatting](#custom-labeling-and-display-formatting)
15+
- [Sorting and Custom Scoring](#sorting-and-custom-scoring)
16+
- [Programmatic Control and Commands](#programmatic-control-and-commands)
17+
- [Integration with Other Plugins](#integration-with-other-plugins)
18+
- [Performance Tips](#performance-tips)
19+
- [Debugging and Logging](#debugging-and-logging)
20+
21+
## Advanced File Filtering
22+
23+
### Toggling Hidden Files
24+
25+
By default, `CpyBuffers.nvim` hides certain files (like `.git`, `node_modules`, `vendor` directories) to streamline the search results. You can toggle the display of hidden files on the fly:
26+
27+
- Press the configured toggle hidden files key (default: `<leader>g`) to switch between showing and hiding hidden files.
28+
29+
**In your config:**
30+
31+
```lua
32+
file_search = {
33+
hide_hidden_files = true, -- Start with hidden files excluded
34+
exclude_patterns = { "node_modules/*", "vendor/*", ".git/*" },
35+
include_extensions = { ".lua", ".js", ".ts" }, -- Only show certain extensions if desired
36+
additional_rg_options = "", -- Add more rg flags (e.g., "--type lua --glob=!test")
37+
},
38+
```
39+
40+
You can also modify the ripgrep (`rg`) command options at runtime using `:CpyBufChangeRgCommand`.
41+
42+
### Dynamically Adjusting `rg` Options
43+
44+
1. Run `:CpyBufChangeRgCommand`.
45+
2. Enter new additional `rg` options (e.g. `--type-add 'mylang:*.mylang' --type mylang`).
46+
3. Re-open the picker and the new options will take effect.
47+
48+
This allows you to refine your search patterns without changing your plugin configuration file.
49+
50+
## Custom Labeling and Display Formatting
51+
52+
When copying multiple files at once, `CpyBuffers.nvim` can insert labels before each file’s content. These labels can be fully customized.
53+
54+
**Key fields:**
55+
56+
- `display.label_buffers`: Enable or disable labeling of file contents.
57+
- `display.label_format`: Define how labels appear.
58+
- `"%c"` is replaced by the file’s short name.
59+
- `"%a"` is replaced by the absolute path.
60+
- `"%f"` is replaced by the relative path to the current working directory.
61+
62+
**Example:**
63+
64+
```lua
65+
display = {
66+
label_buffers = true,
67+
label_format = "## File: %f",
68+
content_separator = "\n\n", -- Separate file contents with blank lines
69+
show_icons = true,
70+
}
71+
```
72+
73+
If you want to change the label format on-the-fly, use `:CpyBufChangeLabelFormat`.
74+
75+
## Sorting and Custom Scoring
76+
77+
**CpyBuffers.nvim** leverages Telescope’s sorting infrastructure. By default, it uses `telescope.config.values.generic_sorter`, but you can enable a custom sorter that implements your own scoring logic.
78+
79+
**Example enabling custom sorter:**
80+
81+
```lua
82+
sorting = {
83+
use_custom_sorter = true,
84+
}
85+
```
86+
87+
**Custom Scoring Logic (from `utils.lua`):**
88+
89+
- Boost exact matches.
90+
- Prioritize files with matching extensions.
91+
92+
You can expand this logic to support more complex scoring in `utils.lua`.
93+
94+
## Programmatic Control and Commands
95+
96+
### Built-in Commands
97+
98+
- `:CpyBufChangeRgCommand` – Change `rg` options interactively.
99+
- `:CpyBufToggleGitignore` – Toggle hidden files.
100+
- `:CpyBufChangeLabelFormat` – Change label format interactively.
101+
102+
These commands let you modify the behavior of the plugin without editing your config and reloading Neovim.
103+
104+
### Copying to Buffers and Files Programmatically
105+
106+
You can use the integrated keymaps to copy selected file contents into a new buffer (`<C-b>` by default) or save them to a file (`<C-s>`).
107+
108+
**Example workflow:**
109+
110+
1. Open the file picker (`<leader>cb`).
111+
2. Select multiple files.
112+
3. Press `<C-b>` to paste them into a new buffer or `<C-s>` to save them into a single file.
113+
114+
This workflow speeds up tasks like assembling a report from multiple source files or aggregating code snippets.
115+
116+
## Integration with Other Plugins
117+
118+
### nvim-web-devicons
119+
120+
If `nvim-web-devicons` is installed, you’ll see file-type icons in the picker. If not, a fallback icon is used.
121+
122+
**Ensure `show_icons` is enabled:**
123+
124+
```lua
125+
display = {
126+
show_icons = true,
127+
}
128+
```
129+
130+
### Other Telescope Extensions
131+
132+
Because `CpyBuffers.nvim` integrates seamlessly with Telescope’s ecosystem, you can combine it with other Telescope extensions. For example, you could:
133+
134+
- Use Telescope’s `fzy_native` sorter or `fzf` extension for advanced sorting and filtering.
135+
- Integrate with `telescope-project` or `telescope-file-browser` to jump between directories before running `CpyBuffers`.
136+
137+
Adjusting or chaining commands might involve writing small wrapper functions in your config.
138+
139+
## Performance Tips
140+
141+
- Exclude large directories: If you often encounter performance issues, extend the `exclude_patterns` list to skip directories known to contain large or irrelevant files.
142+
- Avoid previewing very large files: `CpyBuffers.nvim` automatically disables previews for files larger than 1MB by default. Adjust this limit in `utils.lua` if needed.
143+
- Use additional `rg` options to narrow your search, for example `--type` flags to limit the search space.
144+
145+
## Debugging and Logging
146+
147+
**CpyBuffers.nvim** integrates with Neovim’s built-in logging. Increase the log level to see more detailed information:
148+
149+
```lua
150+
log = {
151+
use_notify = true, -- Use `vim.notify` for in-editor popups
152+
level = vim.log.levels.DEBUG,
153+
}
154+
```
155+
156+
**Levels:**
157+
158+
- `vim.log.levels.ERROR`
159+
- `vim.log.levels.WARN`
160+
- `vim.log.levels.INFO`
161+
- `vim.log.levels.DEBUG`
162+
- `vim.log.levels.TRACE`
163+
164+
When debugging issues, set the level to `DEBUG` or `TRACE` and review the logs or notifications.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 @adia-dev
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

0 commit comments

Comments
 (0)