$ git remote -v
origin  https://codeberg.org/spxy/spica.git (fetch)
origin  https://codeberg.org/spxy/spica.git (push)
$ sed '/remote/,$!d' .git/config
[remote "origin"]
        url = https://codeberg.org/spxy/spica.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
        remote = origin
        merge = refs/heads/main

A perhaps less known detail is that we can set multiple URLs for a remote. For example:

$ git remote set-url origin --add https://github.com/spxy/spica.git
$ git remote -v
origin  https://codeberg.org/spxy/spica.git (fetch)
origin  https://codeberg.org/spxy/spica.git (push)
origin  https://github.com/spxy/spica.git (push)
$ sed '/remote/,$!d' .git/config
[remote "origin"]
        url = https://codeberg.org/spxy/spica.git
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = https://github.com/spxy/spica.git
[branch "main"]
        remote = origin
        merge = refs/heads/main

As evident from the above output, with multiple URLs for the same remote, the first one becomes the fetch URL whereas all URLs become push URLs. For example:

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 327 bytes | 109.00 KiB/s, done.
From https://codeberg.org/spxy/spica
   d473dde..31db503  main       -> origin/main
Updating d473dde..31db503
Fast-forward
 README.md | 1 +
 1 file changed, 1 insertion(+)
$ git log --oneline
31db503 (HEAD -> main, origin/main, origin/HEAD) Explain that Spica is a binary star system
d473dde Create README.md

The output above confirms that the fetch was performed from the first remote URL. Although the output shows that origin contains commit 31db503, it is possible that not all remote locations for origin have received this commit yet. Since we have not configured a pushurl, pushes are sent to all remote URLs by default. For example:

$ echo 'It is about 250 light years away from the Sun.' >> README.md
$ git add README.md
$ git commit -m 'Mention distance from the Sun'
[main 816998d] Mention distance from the Sun
 1 file changed, 1 insertion(+)
$ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 10 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 325 bytes | 325.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
To https://codeberg.org/spxy/spica.git
   31db503..816998d  main -> main
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 10 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (9/9), 791 bytes | 791.00 KiB/s, done.
Total 9 (delta 2), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (2/2), done.
To https://github.com/spxy/spica.git
 * [new branch]      main -> main
$ git log --oneline
816998d (HEAD -> main, origin/main, origin/HEAD) Mention distance from the Sun
31db503 Explain that Spica is a binary star system
d473dde Create README.md

A pushurl can be set as follows:

$ git remote set-url --push origin https://github.com/spxy/spica.git
$ git remote -v
origin  https://codeberg.org/spxy/spica.git (fetch)
origin  https://github.com/spxy/spica.git (push)
$ sed '/remote/,$!d' .git/config
[remote "origin"]
        url = https://codeberg.org/spxy/spica.git
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = https://github.com/spxy/spica.git
        pushurl = https://github.com/spxy/spica.git
[branch "main"]
        remote = origin
        merge = refs/heads/main

When one or more pushurl locations are set, pushes are sent to only those locations. Fetches continue to occur from the first URL as before.

$ echo 'Its two stars orbit each other roughly every four days.' >> README.md
$ git add README.md
$ git commit -m 'Mention the four-day orbital period'
[main 2e9f4e8] Mention the four-day orbital period
 1 file changed, 1 insertion(+)
$ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 10 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 342 bytes | 342.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/spxy/spica.git
   816998d..2e9f4e8  main -> main
$ git log --oneline
2e9f4e8 (HEAD -> main, origin/main, origin/HEAD) Mention the four-day orbital period
816998d Mention distance from the Sun
31db503 Explain that Spica is a binary star system
d473dde Create README.md

Note that in this case, the new commit has been pushed only to the second remote URL. If we perform a pull, Git will fetch changes from the first remote URL and will move origin/main back to the latest commit available there. For example:

$ git pull
From https://codeberg.org/spxy/spica
 + 2e9f4e8...816998d main       -> origin/main  (forced update)
Already up to date.
$ git log --oneline
2e9f4e8 (HEAD -> main) Mention the four-day orbital period
816998d (origin/main, origin/HEAD) Mention distance from the Sun
31db503 Explain that Spica is a binary star system
d473dde Create README.md

For this reason, configuring a separate pushurl should be done with care. It is useful only in a narrow range of scenarios such as fetching from a primary repository that we want to treat as read-only while pushing changes to a mirror.

The difference between pushurl and a normal remote URL is explained in man git-fetch as well as man git-push of Git 2.54.0 as follows:

The <pushurl> is used for pushes only. It is optional and defaults to <URL>. Pushing to a remote affects all defined pushurls or all defined urls if no pushurls are defined. Fetch, however, will only fetch from the first defined url if multiple urls are defined.

Read on website | #git | #technology

Contents

• Experimental Setup
• Reset the Working Tree
• Reset the Index
• Reset the Working Tree and Index
• Summary

Experimental Setup

To experiment quickly, we first create an example Git repository.

mkdir foo/; cd foo/; touch a b c
git init; git add a b c; git commit -m hello

Now we make changes to the files and stage some of the changes. We then add more unstaged changes to one of the staged files.

date | tee a b c d; git add a b d; echo > b

At this point, the working tree and index look like this:

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   a
        modified:   b
        new file:   d

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   b
        modified:   c

File a has staged changes. File b has both staged and unstaged changes. File c has only unstaged changes. File d is a new staged file. In each experiment below, we will work with this setup.

All results discussed in this post were obtained using Git 2.47.3 on Debian 13.2 (Trixie).

Reset the Working Tree

As a reminder, we will always use the following command between experiments to ensure that we restore the experimental setup each time:

date | tee a b c d; git add a b d; echo > b

To discard the changes in the working tree and reset the files in the working tree from the index, I typically run:

git checkout .

However, the modern way to do this is to use the following command:

git restore .

Both commands leave the working tree and the index in the following state:

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   a
        modified:   b
        new file:   d

Both commands operate only on the working tree. They do not alter the index. Therefore the staged changes remain intact in the index.

Reset the Index

Another common situation is when we have staged some changes but want to unstage them. First, we restore the experimental setup:

date | tee a b c d; git add a b d; echo > b

I normally run the following command to do so:

git reset

The modern way to do this is:

git restore -S .

Both commands leave the working tree and the index in the following state:

$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   a
        modified:   b
        modified:   c

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        d

no changes added to commit (use "git add" and/or "git commit -a")

The -S (--staged) option tells git restore to operate on the index (not the working tree) and reset the index entries for the specified files to match the version in HEAD. The unstaged changes remain intact as modified files in the working tree. With the -S option, no changes are made to the working tree.

From the arguments we can see that the old and new commands are not exactly equivalent. Without any arguments, the git reset command resets the entire index to HEAD, so all staged changes become unstaged. Similarly, when we run git restore -S without specifying a commit, branch or tag using the -s (--source) option, it defaults to resetting the index from HEAD. The . at the end ensures that all paths under the current directory are affected. When we run the command at the top-level directory of the repository, all paths are affected and the entire index gets reset. As a result, both the old and the new commands accomplish the same result.

Reset the Working Tree and Index

Once again, we restore the experimental setup.

date | tee a b c d; git add a b d; echo > b

This time we not only want to unstage the changes but also discard the changes in the working tree. In other words, we want to reset both the working tree and the index from HEAD. This is a dangerous operation because any uncommitted changes discarded in this manner cannot be restored using Git.

git reset --hard

The modern way to do this is:

git restore -WS .

The working tree is now clean:

$ git status
On branch main
nothing to commit, working tree clean

The -W (--worktree) option makes the command operate on the working tree. The -S (--staged) option resets the index as described in the previous section. As a result, this command unstages any changes and discards any modifications in the working tree.

Note that when neither of these options is specified, -W is implied by default. That's why the bare git restore . command in the previous section discards the changes in the working tree.

Summary

The following table summarises how the three pairs of commands discussed above affect the working tree and the index, assuming the commands are run at the top-level directory of a repository.

The git restore command is meant to provide a clearer interface for resetting the working tree and the index. I still use the older commands out of habit. Perhaps I will adopt the new ones in another six years, but at least I have the mapping written down now.

Read on website | #git | #technology | #how-to