Documentation missing in "The [patch] section"

[tliron]

Problem

Currently "The [patch] section" mentions how you can override dependencies in Config.toml. Below, under "paths overrides" an alternative approach is documented for config.toml.

However, what the documentation does not make very clear is that you can also put a [patch] section in config.toml.

What the documentation does have is this tiny note:

Note: The [patch] table can also be specified as a configuration option, such as in a .cargo/config.toml file or a CLI option like --config 'patch.crates-io.rand.path="rand"'. This can be useful for local-only changes that you don’t want to commit, or temporarily testing a patch.

I think this could be made more prominent, and indeed made clear at the top of the section that [patch] can appear in either Cargo.toml or config.toml. I've referred to this documentation many times without noticing this tiny note revealing this important option!

Also, worth noting that the advantage of using config.toml over a CLI option is that IDEs and other tooling would also be able to pick up on the local-only patches, whereas a CLI option would not allow this.

Steps

No response

Possible Solution(s)

I think the option of using config.toml for [patch] should absolutely be mentioned at the very top of "The [patch] section" documentation!

Notes

No response

Version

[epage]

Note that the issue original said that it didn't mention .cargo/config.toml support. in my quick look, I also missed that. However, after my examination of this feature (see below), I think that level of prominence is likely sufficient due to the trade offs of this feature.

Config supported was added later in #5539 and this was likely missed. However, looking at the discussion starting at #5539 (comment), this seems to be geared more towards build systems dynamically patching dependencies rather than the average user putting patches in .cargo/config.toml and doing so has negative side effects (#15130, #11782). De-emphasizing the use of config might lead to users being more successful. However, those issues seem more focused on ~/.cargo/config.toml. Looking over this issue, it seems more about temporary patches for development purposes without touching a tracked file. That ends up being a project-to-project concern over because some projects do commit their .cargo/config.toml. To guarantee it to work generally, you'd need to put each repo in its own parent folder so you can add any config you want. #9306 might offer an alternative, depending on how it gets resolved.

Also, worth noting that the advantage of using config.toml over a CLI option is that IDEs and other tooling would also be able to pick up on the local-only patches, whereas a CLI option would not allow this.

--config is only relevant for .cargo/config.toml so if you know something works for one, then it should work for the other.

[tliron]

Sorry for all the edits of my original issue, I will stop doing that. I didn't expect such a quick response. Thanks. :)

In my workflow this feature (patching in config.toml) is an absolute lifesaver, which is why I opened this issue. I imagine others with similar workflows would also benefit ... if they knew about it.

My situation is that I work with several git repositories with various inter-dependencies. I do not want to publish changes in any of them to crates.io until I'm certain the work is good across the repositories. Thus I often use [patch.crates-io] to override the published versions with local paths (local repository clones). When everything tests well I then publish crates one at a time, from the inner dependencies outwards.

The problem is that if these patches are in Cargo.toml it is very problematic to commit them upstream: other devs would have to duplicate my path structure or would generally be confused about how to build from a repository clone.

Once I discovered that I could use config.toml instead, this issue was solved! My IDE (Zed) immediately picked up on the config.toml patches and everything worked exactly the same as using Cargo.toml without any configuration necessary for Zed or any other cargo tools I use.

Is my workflow really so rare? I doubt it.

Otherwise, the issue here I think is not just about prominence of this feature but also to remove ambiguity from the documentation. The section currently starts with this:

| The [patch] section of Cargo.toml can be used to override dependencies with other copies.

That is true, but ambiguous in that it may be interpreted to mean (as I first understood it) that the [patch] section can only be there. This ambiguity is increased due to the "paths override" section below, which talks about config.toml without mentioning the possibility of using [patches]. I think it's just too easy to misunderstand.

My proposal is thus simple. Let's change the opening line to something like this:

| The [patch] section, in either Cargo.toml or the various config.toml instances, can be used to override dependencies with other copies.

The "note" below can then be reworked a bit to avoid repeating that.

[weihanglo]

this seems to be geared more towards build systems dynamically patching dependencies rather than the average user putting patches in .cargo/config.toml and doing so has negative side effects (#15130, #11782)

Yes, I knew the history of why it was proposed and added. It is actually annoying that there are some random patches applied from config.toml you didn't even notice until you realized there was a "spooky action at a distance" messing up your lockfile. In one way we should emphasize it so when debugging people will know it may be the cause; In another we de-emphasize it so people won't misuse it.

But to me, the note is more prominent than the first line of the paragraph.

[tliron]

@weihanglo Is my use case not a good use (opposite of "misuse") of this feature? Is there a better way for me to allow for local dev patches outside of Cargo.toml?

[epage]

Its a reasonable use but not a universal one because .cargo/config.toml may also be checked in. For myself (and any recommendations I'd make to documentation and tool authors like cargo-override) would be consistent pain over inconsistent pain because the latter can lead to complacency making you more likely to miss things. Others may make a different call though.

[tliron]

@epage It doesn't have to be the .cargo/config.toml inside the project. It could be in your projects directory, home directory, etc., places that would never be checked in.

Can you elaborate on what "things" you think might be missed due to complacency? Reminder that cargo publish ignores any patches, and I imagine other (good) deployment tools would do, too.

And if this is a bad practice, then what should I be using instead for local dev patches?

[weihanglo]

Its a reasonable use but not a universal one because .cargo/config.toml may also be checked in.

epage It doesn't have to be the .cargo/config.toml inside the project. It could be in your projects directory, home directory, etc., places that would never be checked in.

Slightly related. I feel like config-include (#7723) is a good fit of this use case, if it supports optional includes.

[epage]

It doesn't have to be the .cargo/config.toml inside the project. It could be in your projects directory, home directory, etc., places that would never be checked in.

I acknowledged that in my previous response (#15948 (comment)).

If your config is overly broad, you'll have worse problems (#15130, #11782).

A workaround to keep the scope narrow is to have a project-specific parent directory, so you could do

clap/
    .cargo/config.toml # users
    clap/
      .git/**
      .cargo/config.toml  # checked in
      src/lib.rs
      **

that isn't ideal and that is where some kind of multi-config file solution would come in handy so we could have both committed and user configs inside the repo, with the user config mentioned in .gitignore.

Can you elaborate on what "things" you think might be missed due to complacency? Reminder that cargo publish ignores any patches, and I imagine other (good) deployment tools would do, too.

Say you take the stance of using .cargo/config.toml for patches so consistently, you have cargo override exclusively use it.

Then you go into your projects, run cargo override, make your changes, and do git commit -a, all is well.

You then switch over to clap and try to do the same, you'll commit a local edit just as you would if you did this to Cargo.toml but because you are used to it "just working", you don't notice.

Like I said, I would prefer a consistent solution. I recognize others might be fine with an inconsistent solution.

[epage]

Slightly related. I feel like config-include (#7723) is a good fit of this use case, if it supports optional includes.

Can't remember where that is at and we'd need to build up a convention around it.

If this idea is compatible with that, I wonder if we should just add support for config.untracked.toml , have cargo new ignore it, and advertise this as a convention.