Working with multiple remote repositories in your git config file

[wrongkindofdoctor]

When you clone a Github repository to your local machine, there is a file called "config" in the .git directory that contains information about the origin repository. When you create or check out branches, they are are added to the config file, too. ETA: the branches in the config file are the tracking branches, not every branch that exists in the local and remote repos.

If you want to work with branches in different remotes (usually your repository fork and the base repository), you can add the remote repository to your config file with the following command:

git remote add <some_name> https://github.com/user/repo_name

"some_name" can be anything, and you can substitute the ssh path for the https address of the repo if you have ssh configured, and plan on pushing to both repositories (note that it is easy to accidentally push to/pull from the wrong remote, so be sure to double check that your branches and the remote repositories are correct).

Note that you can also open .git/config in a text editor and add the lines manually, using the origin information as template; just be sure to replace "origin" with "some_name" in the fetch line: fetch = +refs/heads/*:refs/remotes/some_name/*. However, as @underwoo points out in the following reply, this a risky endeavor prone to error; use git remote add to ensure that the information in the config file is correct (and be sure to read beyond this post for more great info).

Once you've added the remote, type git fetch -u some_name to get a list of the branches on the some_name remote, or
git remote update to update the list of branches in all of the remote repos in the config file.

To check out a new branch in your local repository from a branch on the new remote, type:
git checkout -b <new branch name> some_name/branch_name

To push the new branch to your remote fork, type: git push -u origin new_branch_name (unless you have write access to the new repo, trying to push to "some_name" will give you an error message).

Since I have to test branches in my MDTF-diagnostics fork and the NOAA-GFDL fork, the .git/config files on my local machines (I test on multiple platforms) looks something like this:

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	url = [email protected]:wrongkindofdoctor/MDTF-diagnostics.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main
[branch "feature/test_branch"]
	remote = origin
	merge = refs/heads/feature/test_branch
[branch "develop"]
	remote = origin
	merge = refs/heads/develop
[remote "gfdl"]
	url = [email protected]:NOAA-GFDL/MDTF-diagnostics.git
	fetch = +refs/heads/*:refs/remotes/gfdl/*
[branch "develop"]
	remote = gfdl
	merge = refs/heads/develop

My fork is designated as the "origin" by default, and I've checked out the "main", "develop", and "feature/test_branch" branches on my local machine. I've named the NOAA-GFDL remote "gfdl" and have checked out the develop branch on my local machine.

Having the NOAA-GFDL repo in my config file allows me to sync the develop branches with NOAA-GFDL/develop in my local repo and remote fork using the command line:

git checkout gfdl/develop
git fetch
git pull
git checkout develop
git merge gfdl/develop
git push -u origin develop

I can then update my test branch with latest changes in the develop branch. I recommend using the interactive rebase rather than a merge to keep all of the commits in my feature/test branch together at the "tip" of the branch, resulting in a cleaner history:

git checkout feature/test_branch
git rebase -i develop

I squash any commits if necessary after the editor (Vim by default) opens, save the changes, close the text editor, rebase, and resolve merge conflicts (explaining the rebase process will be a separate topic, and will be added to the documentation).
When the rebase is done, I push the feature/test_branch updates to my remote fork:
git push -u origin feature/test_branch --force (--force is necessary because rebasing modifies the commit history)

If you want to remove the "some_name" remote repository from your config file, type:

git remote remove <some_name>

The command doesn't generate any feedback, so type git remote -v to display all repositories that are connected to your local repository, and confirm that "some_name" is no longer listed.

[bitterbark]

Thanks, @wrongkindofdoctor , this is super helpful.

[underwoo]

@wrongkindofdoctor, this information is very useful. However, some of it is not entirely correct.

The branches listed in the .git/config file are your tracking branches, not all your branches. All branches for both your local working repository and remotes are kept in the .git/refs directory. (Please note different versions of git may store the information in different formats.)

I strongly suggest to not modify the .git/config or the global ~/.gitconfig files by hand. Adding incorrect information in the config file can lead to unwanted side effects.

If you would like to track a branch, you can run the command:

git branch -u <remote>/<branch_name>

Note, this is mostly identical to the push command offered:

git push -u <remote> <branch_name>

both set the current branch to track the <branch_name> on the remote <remote>.

To view your branches, and if they are tracked or only local, use the git branch command with the -vv options:

> git branch -vv
branch1   12345678 [upstream/branch_a] last commit on branch1
branch2   fedcba09 last commit on branch2
branch3   a1b2c3d4 [origin/branch3] last commit on branch3

In the above example, branch1 and branch3 are tracking branches on remotes upstream and origin respectively. This also indicates the remote branch name does not need to match the local branch name.

In most cases, there are git commands to get you the information you need without looking at any of the files in the .git directory. I cannot stress enough to not modify the .git directory's contents directly.

Lastly, be very careful with the --force option to git push. As @wrongkindofdoctor indicated this may modify the history of your git repository, and is not reversible. You should also know that squashing commits into one can cause problems if you are collaborating with others. It can also lose merging information (knowledge that two branches were merged). I suggest making a backup of your local repository (cp -r is more than sufficient) until you are comfortable with these two git techniques.

Happy git-ing

[wrongkindofdoctor]

Thanks @underwoo. As you point out, using the appropriate git commands is preferable to editing config files by hand. I've modified the post to emphasize this point, and clarify the contents of the config file.

[bitterbark]

I appreciate the concerns about editing config files, but (as the person whose question motivated this post) I really appreciate knowing how to look at these files myself rather than hope the command returns what I think I had asked for. On the topic of the usefulness of the GH discussion boards, I like that @wrongkindofdoctor edited the original post, so someone doesn't have to read down the thread for all the information. I recommend this practice for our participants.

…

On Fri, Jan 8, 2021 at 8:10 AM Jess ***@***.***> wrote: Thanks @underwoo <https://github.com/underwoo>. As you point out, using the appropriate git commands is preferable to editing config files by hand. I've modified the post to emphasize this point, and clarify the contents of the config file. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#96 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHLJVQHXOGPCC7N76FQG5ZTSY4N6FANCNFSM4VZCXEFA> .