feat(dependencies): support pinning of tags / revs when using .gitmodules with foundry.lock

[yash-atreya]

Motivation

Closes #7225

• git submodule doesn't have support for pinning to tags/revisions, only branches in .gitmodules
• This creates unintended behavior in forge when updating deps.
• Reproduction of unintended behaviour

1. Install oz with tag forge install OpenZeppelin/[email protected].
2. git submodule status shows the oz dep checked out at OpenZeppelin/openzeppelin-contracts@69c8def
3. Run forge update
4. oz dep is now checked out at the most recent commit of the master branch instead of the commit of the tag.

Solution

Introduce a basic lockfile foundry.lock that consists of a mapping from relative lib_path to DepIdentifier.

Every time forge update is run, this file is inferred to correctly check out the dep and maintain tag or rev pinning if specified.

In case we want to override a dep and set a new tag, this can be done like so: forge update owner/dep@new-tag

TODO

• account for foundry.lock generation the first time.
• migration tests
• monorepo test
• forge remove

[grandizzy]

I think this makes sense overall, 2 scenarios was thinking of

1. update deps of dependencies

• forge init and then install specific tag forge install OpenZeppelin/openzeppelin-contracts@tag=v4.9.4. This will result in 2 deps in lib/openzeppelin-contracts/lib:

erc4626-tests
forge-std

• forge update updates dependencies of Oz dependency, resulting in 3 deps

erc4626-tests
forge-std
halmos-cheatcodes

This probably cannot be fixed even when openzeppelin-contracts contracts will add its own forge-submodule-info.json?

2. updating dependency to a different version

• cd in lib/openzeppelin-contracts/ and git checkout v5.0.2
• forge update silently checks out v4.9.4
• in order to persist then forge-submodule-info.json should be manually edited and "lib/openzeppelin-contracts":{"Tag":"v4.9.4"} updated to "lib/openzeppelin-contracts":{"Tag":"v5.0.2"}

Maybe on forge update we should print out versions (and should follow up with docs / book update).

[yash-atreya]

I think this makes sense overall, 2 scenarios was thinking of

1. update deps of dependencies

• forge init and then install specific tag forge install OpenZeppelin/openzeppelin-contracts@tag=v4.9.4. This will result in 2 deps in lib/openzeppelin-contracts/lib:

erc4626-tests
forge-std

• forge update updates dependencies of Oz dependency, resulting in 3 deps

erc4626-tests
forge-std
halmos-cheatcodes

This probably cannot be fixed even when openzeppelin-contracts contracts will add its own forge-submodule-info.json?

2. updating dependency to a different version

• cd in lib/openzeppelin-contracts/ and git checkout v5.0.2
• forge update silently checks out v4.9.4
• in order to persist then forge-submodule-info.json should be manually edited and "lib/openzeppelin-contracts":{"Tag":"v4.9.4"} updated to "lib/openzeppelin-contracts":{"Tag":"v5.0.2"}

Maybe on forge update we should print out versions (and should follow up with docs / book update).

(1). Yeah, this is because we run git submodule update --remote as before, and checkout to the correct tag/rev after the updates have been downloaded. EDIT: On second thought, we could remove the --remote flag for deps that specify a tag/rev, this should fix it. Now this is as good as not running update for these deps as --remote flag is only intended for modules pinned to a branch.

(2) Deps can be updated along with the values in foundry.lock like so forge update OpenZeppelin/[email protected] no need to manually checkout any lib or edit forge-submodule-info.json

[zerosnacks]

Some minor nits, implementation and tests I performed all look good

Updated the title

[yash-atreya]

Would be great if this PR was accompanied by an update to the book to document the forge update owner/dep@new-tag behavior as it will be a common question

@grandizzy @zerosnacks

Related book PR: foundry-rs/book#1494

[grandizzy]

left some preliminary comments, could be I am missing some context so looking more into. thanks!

[grandizzy]

is this a safe assumption? git.tag_for_commit returns the first tag the commit was included, but that doesn't necessarily mean that tag was done at specified rev? e.g. if abc1234 rev included in v0.1.0 but v0.1.0 tagged at subsequent rev xyz1234 wouldn't then the identified tag point to xyz1234 rev? (and wrongly add dep as DepIdentifier::Tag instead DepIdentifier::Rev)

[yash-atreya]

Yeah, this has always been an unsafe assumption. Initially, I started with getting the latest tag for a commit, which is not right, and it can pull a bunch of changes from the lib that the user did not intend.

Defered to getting the earliest tag for a commit, so that the changes (if any) pulled are minimal.

But it is surely a footgun, resolved this by always pinning to a rev in 98223b0

[grandizzy]

lgtm. @zerosnacks do you want to have another look since things changed?

[yash-atreya]

@zerosnacks conflicts resolved, rfr