How to change the remote repository for a git submodule?

Question

I've created a git repository with a submodule in it. I'm able to tell the submodule itself to change its remote repository path, but I'm not sure how to tell the parent repository how to change the remote repository path for the submodule.

I wouldn't be surprised if I'm somewhat out of luck and have to do things manually, as even deleting submodules isn't easy.

Alcove

Note: Git 2.25 (Q1 2020) comes with a new command": git submodule set-url [--] <path> <newurl> – Skillet

There's an answer for that below. Please upvote it! – Festa

Answer 1

You should just be able to edit the .gitmodules file to update the URL and then run git submodule sync --recursive to reflect that change to the superproject and your working copy.

Then you need to go to the .git/modules/path_to_submodule dir and change its config file to update git path.

If repo history is different then you need to checkout new branch manually:

git submodule sync --recursive
cd <submodule_dir> 

git fetch
git checkout origin/master
git branch master -f
git checkout master

Badr

What affect should git submodule sync have? Am I doing it incorrectly in gist.github.com/120723 , or am I incorrect in expecting .git/config to be changed by git submodule sync? – Alcove

This doesn't seem to update .git/config, at least in 1.7.1 or 1.7.3. – Renaud

does this update the submodule url configuration for the previous commits also? ex if i checkout a older commit, will it point to new submodule urls? – Pianist

Use git submodule foreach -q git config remote.origin.url to see "actual" submodule urls – Cursive

@Skillet and so it possible to have more than one remote git repo for a submodule? if so how do i do it? – Gluttonize

@Gluttonize not that I know of. Each submodule is associated with one, and only one, git repo. – Skillet

It didn't update .git/config for me using git 2.1.0. I had to update both .gitmodules and .git/config manually before running a git submodule sync --recursive to have my submodule remote be updated. – Chinkiang

How do I then commit this change in the .gitmodules file? what happens if I checkout a branch/commit earlier than this change? What happens if the old repo and the new repo aren't exactly the same? What will I have in the .git of the submodule? in the working directory of the submodule? – Deuce

You can add multiple remotes from inside a subrepo using TortoiseGit so you must be able to do it on the command line. Those extra remotes are local-only, they won't get pushed with the rest of the settings. The extra remotes information ends up in the parent repo's .git\modules\submodules\name_of_submodule\config file. – Epitomize

I had to 'touch' the .gitmodule file to make this work correctly. – Solid

I don't recommend this approach if the path is also changing, as it will leave stale references to the old submodule path inside .git that are difficult/impossible to clean up manually. It's cleaner to run git submodule deinit modulename followed by git submodule init git@server/path/to/repo.git modulename. – Skylar

This appears to be missing the key step of git submodule update --init --recursive --remote which actually changes the repository to the new remote – Papism

Since this is the highest-voted answer, it should probably be updated; see this answer – Boon

None of these worked for me. I had to cd mymodulename then git remote --set-url origin <url> – Indigene

In case you are in a "linked working tree" (attached worktree), the config file is not in .git/modules/path_to_submodule , but in path_to_main_working_tree/.git/worktrees/worktree_name/modules/path_to_submodule. – Photoreceptor

Answer 2

With Git 2.25 (Q1 2020), you can modify it.
See "Git submodule url changed" and the new command

git submodule set-url [--] <path> <newurl>

(On the -- separator, see "double hyphen as a signal to stop option interpretation and treat all following arguments literally")

WARNING: Hi-Angel mentions in the comments (tested even with Git 2.31.1):

One should be careful with git submodule set-url because it has a bug:

If, inside your .gitmodules file, the path looks like this some-path, and then you execute a:

# Usually causes unexpected behavior
git submodule set-url some-path/ new-url

(note the trailing slash / in some-path/), then, instead of modifying existing submodule, the command will add another one. Instead run:

# Good
git submodule set-url some-path new-url

---

Original answer (May 2009, fourteen years ago)

Actually, a patch has been submitted in April 2009 to clarify gitmodule role.

So now the gitmodule documentation does not yet include:

The .gitmodules file, located in the top-level directory of a git working tree, is a text file with a syntax matching the requirements -of linkgit:git-config4.
[NEW]:
As this file is managed by Git, it tracks the +records of a project's submodules.
Information stored in this file is used as a hint to prime the authoritative version of the record stored in the project configuration file.
User specific record changes (e.g. to account for differences in submodule URLs due to networking situations) should be made to the configuration file, while record changes to be propagated (e.g. +due to a relocation of the submodule source) should be made to this file.

That pretty much confirm Jim's answer.

---

If you follow this git submodule tutorial, you see you need a "git submodule init" to add the submodule repository URLs to .git/config.

"git submodule sync" has been added in August 2008 precisely to make that task easier when URL changes (especially if the number of submodules is important).
The associate script with that command is straightforward enough:

module_list "$@" |
while read mode sha1 stage path
do
    name=$(module_name "$path")
    url=$(git config -f .gitmodules --get submodule."$name".url)
    if test -e "$path"/.git
    then
    (
        unset GIT_DIR
        cd "$path"
        remote=$(get_default_remote)
        say "Synchronizing submodule url for '$name'"
        git config remote."$remote".url "$url"
    )
    fi
done

The goal remains: git config remote."$remote".url "$url"

---

Note:

Git 2.40 (Q1 2023) clarifies git config remote.<remote>.url:

See commit d390e08 (07 Feb 2023) by Calvin Wan (CalvinWan0101).
^{(Merged by Junio C Hamano -- gitster -- in commit 59397e9, 15 Feb 2023)}

Documentation: clarify multiple pushurls vs urls

^{Signed-off-by: Calvin Wan}

In a remote with multiple configured URLs, git remote -v^(man) shows the correct url that fetch uses.

However, git config remote.<remote>.url^(man) returns the last defined url instead.

This discrepancy can cause confusion for users with a remote defined as such, since any url defined after the first essentially acts as a pushurl.

Add documentation to clarify how fetch interacts with multiple urls and how push interacts with multiple pushurls and urls.

urls-remotes now includes in its man page:

The <pushurl> is used for pushes only.

It is optional and defaults to <URL>.

Pushing to a remote affects all defined pushurls or to all defined urls if no pushurls are defined.
Fetch, however, will only fetch from the first defined url if muliple urls are defined.

---

Git 2.44 (Q1 2024), batch 10, tightens URL checks fsck makes in a URL recorded for submodules.

So when you change the URL, the URL validity check is now more robust.

See commit 8430b43, commit 7e2fc39, commit 6af2c4a, commit 13320ff (18 Jan 2024) by Victoria Dye (vdye).
^{(Merged by Junio C Hamano -- gitster -- in commit 76bd129, 26 Jan 2024)}

submodule-config.c: strengthen URL fsck check

^{Signed-off-by: Victoria Dye}

Update the validation of "curl URL" submodule URLs (i.e.
those that specify an "http[s]" or "ftp[s]" protocol) in 'check_submodule_url()' to catch more invalid URLs.
The existing validation using 'credential_from_url_gently()' parses certain URLs incorrectly, leading to invalid submodule URLs passing 'git fsck'^(man) checks.
Conversely, 'url_normalize()' - used to validate remote URLs in 'remote_get()' - correctly identifies the invalid URLs missed by 'credential_from_url_gently()'.

To catch more invalid cases, replace 'credential_from_url_gently()' with 'url_normalize()' followed by a 'url_decode()' and a check for newlines (mirroring 'check_url_component()' in the 'credential_from_url_gently()' validation).

Skillet

I wanted to change the submodule's URL only on this machine. From the parent project I could modify the record in .git/config by doing: git config submodule."$submodule_name".url "$new_url" which is also described here. – Shaefer

What does the optional double dashes in git submodule set-url [--] <path> <newurl> do? – Stead

@Stead They help separate options from parameters: see https://mcmap.net/q/11419/-deleting-a-badly-named-git-branch – Skillet

Note that for Ubuntu users with an older version git you can use this PPA to update: launchpad.net/~git-core/+archive/ubuntu/ppa – Reive

This should be the preferred answer now. One simple command for everything. – Photoreceptor

What does [--] mean? Can you give an example? – Kellner

@Kellner It separates options from file parameters. I have documented the double-hyphen syntax in 2009, twelve years ago: https://mcmap.net/q/11419/-deleting-a-badly-named-git-branch – Skillet

I would also be interested to know what the [--] mean – Miksen

@Miksen That is what I describe/explain in https://mcmap.net/q/11419/-deleting-a-badly-named-git-branch – Skillet

I think that ` -- ` allows you to have a preceding - or -- in the arguments that follow and not have them interpreted as options. Chances are, if you are doing direct work on the command line, you won't need this because you are probably not a maniac who puts - or -- at the beginning of things. But it might happen for some reason and so for more robust scripts, you can use the ` -- ` to signal to the command line parser to no longer interpret dashes specially. It's confusing until you think of it as a script-writing tool, mainly. – Fortuitism

@DanielRussell Good point. I really like to use --, precisely to not worry about what follows. Everything before are options, everything after, aguments. – Skillet

Answer 3

These commands will do the work on command prompt without altering any files on local repository

git config --file=.gitmodules submodule.Submod.url https://github.com/username/ABC.git
git config --file=.gitmodules submodule.Submod.branch Development
git submodule sync
git submodule update --init --recursive --remote

Please look at the blog for screenshots: Changing GIT submodules URL/Branch to other URL/branch of same repository

Siva

This worked but I had to remember to push the changes to the remote. git add .gitmodules git commit -m "modified submodule URL" git push origin master – Searles

Well, that created a terrible mess for me. Commands went down quietly, but the actual submodule repository still thinks its remote is the old one (the old URL). Maybe these commands should be accompanied with other commands within the submodule's repository? – Deuce

The last command is a bit extreme... If you have submodules with submodules inside, this will remotely update the sub-submodules as well, which is unlikely what you need. – Keely

Note that you need replace Submod with name of your submodule! – Willingham

This is less risky than going into your .gitmodules file manually. thx 👍 – Risley

reply for other question about submodule url https://mcmap.net/q/13655/-how-to-change-git-submodules-url-locally helpful description for command semantic – Jeunesse

Answer 4

In simple terms, you just need to edit the .gitmodules file, then resync and update:

Edit the file, either via a git command or directly:

git config --file=.gitmodules -e

or just:

vim .gitmodules

then resync and update:

git submodule sync
git submodule update --init --recursive --remote

Nazarite

git submodule update --init worked for me, --remote seems to tie it to the HEAD of the remote repo. – Autoerotic

Answer 5

What worked for me (on Windows, using git version 1.8.3.msysgit.0):

• Update .gitmodules with the URL to the new repository
• Remove the corresponding line from the ".git/config" file
• Delete the corresponding directory in the ".git/modules/external" directory (".git/modules" for recent git versions)
• Delete the checked out submodule directory itself (unsure if this is necessary)
• Run git submodule init and git submodule update
• Make sure the checked out submodule is at the correct commit, and commit that, since it's likely that the hash will be different

After doing all that, everything is in the state I would expect. I imagine other users of the repository will have similar pain when they come to update though - it would be wise to explain these steps in your commit message!

Sideman

Thank you so much for this. This is the only one that worked for me after I had already run a git submodule update. Following the other answers wouldn't change what was in the ./git/modules/external dir so attempting to update would result in it still pulling the incorrect url. – Dandelion

this seems to be a bit dangerous, and I'm not sure it preserves the history of the previous submodule. If, for instance, you want to check out an old commit or branch of your main-repository (the one containing the submodule) I'm not sure it will know to pull the OLD submodule attached and related to that old commit of the main. – Deuce

No, it almost certainly won't know - you'll have to do all the steps after the first one again. This is just what I found worked for nuking the current state of the submodule. I don't know if the state of things has changed since I wrote this, mind :) – Sideman

@MottiShneor that seems dangerous indeed if you need to keep the previous submodule history, though I'm not sure about it. In my case it's the only solution that worked, what I wanted was basically replace the original submodule with my own fork – Tattoo

Followed these steps and found that the "Delete the checked out submodule directory itself (unsure if this is necessary)" is necessary otherwise you will encounter "fatal: Not a git repository: ..." when running git submodule update – Ravioli

Answer 6

Just edit your .git/config file. For example; if you have a "common" submodule you can do this in the super-module:

git config submodule.common.url /data/my_local_common

Migrate

This is only the best way if you are trying to change the URL for a one time use, not permanently in the super project. E.g. you want to clone submodules from local copies on disk. – Passivism

Answer 7

git config --file=.gitmodules -e opens the default editor in which you can update the path

Calycle

Answer 8

A brute force approach:

• update the .gitmodules file in the supermodule to point to the new submodule url,
• add and commit the changes to supermodule/.gitmodules,
• make a new clone of the supermodule somewhere else on your computer (making sure that the latest changes to the .gitmodules file are reflected in the clone),
• change your working directory to the new clone of the supermodule,
• run git submodule update --init --remote path-to-submodule on the submodule,

et voilà! The submodule in the new clone of the supermodule is properly configured!

Tentacle