--include-priority merely negates --exclude

[devtooligan]

Thank you for creating this wonderful tool which I use often.

Does the --include-priority flag actually do anything?

From my testing all it does is negate the --exclude so you would get the same result if you didn't use --exclude and you didn't use --include-priority. But maybe I'm missing something?

[ODAncona]

Hi @devtooligan,

The include-priority helps when you have a file that is matched by the include glob and the exclude glob.
I detailed the explanation in the documentation

Can you come up with a minimal reproducible example if the feature doesn't work as intended ?

Thank you

[devtooligan]

Hmm, well maybe I'm just not thinking clearly but here's an example:

code2prompt . --i "*.py,*.md" -e "DONTINCLUDEMEBRO.md" --include-priority

I believe is the same as:

code2prompt . --i "*.py,*.md"

I'm probably missing something. Can you give an example of using --include-priority where you couldn't accomplish the same by removing the -e option?

[ODAncona]

Hi,

Just to clarify, these commands have the same outcomes but the logic is not exactly the same. (And as a quick note: you probably meant to use --include or -i instead of --i.)

Clarification

---

When both include and exclude patterns match a file, the exclude pattern takes precedence by default.

---

So if a file matches both, it will be excluded, unless you add --include-priority, which tells the tool to prefer the include pattern in case of overlap.

Let’s look at your examples:

• code2prompt . -i "*.py,*.md" -e "DONTINCLUDEMEBRO.md" --include-priority
  → Includes DONTINCLUDEMEBRO.md (because --include-priority is set)

• code2prompt . -i "*.py,*.md"
  → Includes DONTINCLUDEMEBRO.md (because there’s no exclude pattern at all)

However, if you run:

• code2prompt . -i "*.py,*.md" -e "DONTINCLUDEMEBRO.md" (without --include-priority)
  → Excludes DONTINCLUDEMEBRO.md (because exclude takes precedence by default)

When is --include-priority needed?

Now, let's change the scenario where --include-priority is useful. Let's say we want to make sure to include a file even though he match exclude glob. It’s useful when a file matches both include and exclude patterns and you want to include it anyway. For example:

code2prompt . -e "*.py,*.md" -i "PLZINCLUDEMEANYWAYBRO.md" --include-priority

Here, PLZINCLUDEMEANYWAYBRO.md matches both patterns. By default, it would be excluded, but with --include-priority, it will be included.

Hope this clears things up!

[devtooligan]

Sorry, maybe I'm being dense here but what is the difference between your example above:

code2prompt . -e "*.py,*.md" -i "PLZINCLUDEMEANYWAYBRO.md" --include-priority

and

code2prompt . -i "PLZINCLUDEMEANYWAYBRO.md"

This is what I don't understand

[ODAncona]

Hi @devtooligan 👋

Thanks for your question, it challenged me and I spent a while to justify the design of this feature.

TL;DR

--include-priority adds ergonomic shorthand: lets you keep large “blacklist” globs and punch tiny “whitelist”
holes in them without writing gigantic include patterns. For miniature demos it looks redundant; for big repos it saves a lot of typing and mental overhead.

Here's the detailed explanation !

---

You’re absolutely right, in this example the flag looks useless and the outcomes are the same. If A (the include set) already spells out exactly the files you need, you can just drop -e and achieve the same result.

The reason --include-priority exists is convenience and maintainability when the project tree and the globs get large.

---

1. Design of the Glob Pattern Tool

Let

• A = files that match at least one include pattern
• B = files that match at least one exclude pattern
• Ω = every file in the tree
• C = A ∩ B = files that match both lists
• D = Ω \ (A ∪ B) = “the rest” (matches neither)

Include list	Exclude list	Result (no flag)	Result (--include-priority)
A = ∅	B = ∅	Ω	Ω
A = ∅	B ≠ ∅	Ω \ B	Ω \ B
A ≠ ∅	B = ∅	A	A
A ≠ ∅	B ≠ ∅	A \ B	A

So the flag influences only C (the overlap).
Zone D is never included once an include list exists. Otherwise the “include list” would no longer be a real whitelist. In the opposite case, "blacklist" logic would invalidate the include list (the options are exposed later).

---

2. Why the --include-priority flag ?

In a small directory you can, indeed, remove -e and get the same list. On the condition that you select all the relevant files with the include glob.

In a real repository we usually have:

1. a broad include pattern (e.g. “all *.md” or “all *.py”)
2. a broad exclude pattern to cut down size (e.g. node_modules/**,
   target/**, docs/private/**, …)
3. a few files inside the excluded area that we still need

Without the flag you have two unpleasant options:

• Drop the exclude: you drag thousands of files back into the prompt.
• Enumerate everything you do want: you end up with a monster include
  list that is hard to write and harder to maintain.

--include-priority gives you the neat one-liner:

code2prompt . \
  -i "**/*.md,node_modules/**/LICENSE" \
  -e "node_modules/**" \
  --include-priority

---

3. The “C and D” view

With both lists present (A ≠ ∅, B ≠ ∅) you have four logical possibilities
for the overlap C and the rest D.

Want C?	Want D?	Reasonable?
No	No	default behaviour (A \ B)
Yes	No	--include-priority
No	Yes	surprising (“discard what I asked for, keep what I didn’t”)
Yes	Yes	same as “no exclude” – defeats the point of having -e

We therefore expose only the two sensible modes:

• keep C (flag on)
• drop C (flag off)

D is never kept when an include list is present.

---

Hope that clarifies why the flag exists and when it’s handy! 🚀

[devtooligan]

Thanks for the explanation. I could see that for programatically globs it's nice to be able to override it. Thanks for taking the time -- I love your tool and I just wanted to make sure I wasn't missing something about the functionality.

Thanks again for building and maintaining this!

[ODAncona]

@devtooligan my pleasure !

The more I think about this, the more I believe you are right.

Include list	Exclude list	Result (no flag)	Result (--include-priority)
A ≠ ∅	B = ∅	A	A
A ≠ ∅	B ≠ ∅	A \ B	A

These two commands are functionally equivalent:

A ≠ ∅
code2prompt . -i "**/*.md,node_modules/**/LICENSE"

A ≠ ∅ & B ≠ ∅ & include-priority
code2prompt . -i "**/*.md,node_modules/**/LICENSE" -e "node_modules/**" --include-priority

if someone want to use --include-priority, it means he wants to keep C. Because C is included into A, it's simply A. That's it.

Here's the relevant part in the code:

let result = match (included, excluded) {
    (true, true) => include_priority,  // If both match, use the flag
    (true, false) => true,             // If only included, include it
    (false, true) => false,            // If only excluded, exclude it
    (false, false) => include_globset.is_empty(), // If neither, include if no include patterns
};

Therefore, my explanation is simply not correct.

When I designed this functionality it made sense because it gave the ability to the user to choose about the file that were matched with both pattern. I just didn't expected that if the user want to keep C it was simply A.

The question now is more about what about the two last cases ?

Want C?	Want D?	Reasonable?
No	No	default behaviour (A \ B)
Yes	No	--include-priority
No	Yes	surprising (“discard what I asked for, keep what I didn’t”)
Yes	Yes	same as “no exclude” – defeats the point of having -e

Does it make sense to just remove this flag and force user to "think properly" ?

What's your take on this ?

[devtooligan]

@devtooligan my pleasure !

The more I think about this, the more I believe you are right.

What's your take on this ?

Personally I think it would be cleaner if you removed it.

But it's not that big of a deal, maybe we could just add a comment in the docs in case someone else like me goes down that rabbit hole!

[ODAncona]

@devtooligan

Completely, I agree.

I'll remove it on the next release and update the documentation accordingly. Just to make clear for user what's really happening.

Thanks for getting deep ! That was interesting and I had to dig until the bottom to really get it.

[ODAncona]

Hi @devtooligan,

This problem has been following me since I work on the Terminal User Interface. As you already know, we have:

A: Include list
B: Exclude list

But for the TUI, the user should be able to manually select files and folder. With this new context, I introduced two more list A' and B' which are respectively explicit include and exclude from user.

and came up with this truth table:

A,A',B,B' 	| Output 		
0000		| Ω			
0001		| Ω \ B'		
0010		| Ω \ B			
0011		| Ω \ (B' ∪ B)		
0100		| A'			
0101		| A' \ B'		
0110		| A' \ B		
0111		| A' \ (B' ∪ B)		
1000		| A			
1001		| A \ B'		
1010		| A \ B			
1011		| A \ (B' ∪ B)		
1100		| (A ∪ A')		
1101		| (A ∪ A') \ B'	
1110		| (A ∪ A') \ B		
1111		| (A ∪ A') \ (B ∪ B')	

However, I found a case where --include-priority would make sense! Because we introduce actions that could potentially be contradictory.

Example

We have this folder:

src/
├── args.rs
├── clipboard.rs
├── config.rs
├── main.rs
├── token_map.rs
├── tui.rs
└── util.rs

1. The user initialize with code2prompt src -i "*.rs"
2. The user unselect the folder src
3. The user select manually the files: config.rs and main.rs

In this situation, the user expect to only have the two files. We have:

A = ".rs"
B' = "**/src/"
A' = "/src/config.rs,/src/main.rs"

According to the truth table we should have:
(A ∪ A') \ B' which will simply unselect every file in the folder src !

Problem Identification

What changed this time ? The user expected the folder to be unselected, however the logic under-the hood made it more complex. The logic with A include list and B exclude list only work if you apply one pass.

In other words, Order and Specificity Matter

Proposition

After few iterations, Claude proposed to come with an Action-Based Model

Instead of modeling A' and B' as glob pattern sets, we should model them as ordered lists of user actions with specificity levels:

#[derive(Debug, Clone)]
pub struct UserAction {
    pub path: PathBuf,
    pub action: SelectionAction,
    pub specificity: SpecificityLevel,
    pub timestamp: u64, // or sequence number
}

#[derive(Debug, Clone)]
pub enum SelectionAction {
    Include,
    Exclude,
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum SpecificityLevel {
    File,      // Most specific
    Directory, // Less specific
}

What do you think of this idea ? The more I think about it the more I believe:

1. Initialization should be performed with A include list and B exclude list with the previous logic
2. File can be selected or not
3. When the user toggle a file => toggle a file
4. When a user toggle a folder => Selects // Deselect all files inside the folder

Basic as this.

Thank you