430

I have some old branches in my git repository that are no longer under active development. I would like to archive the branches so that they don't show up by default when running git branch -l -r. I don't want to delete them, because I want to keep the history. How can I do this?

I know that it's possible to create a ref outside of refs/heads. For example, refs/archive/old_branch. Are there any consequences of doing that?

1

16 Answers 16

580

I believe the proper way to do this is to tag the branch. If you delete the branch after you have tagged it then you've effectively kept the branch around but it won't clutter your branch list.

If you need to go back to the branch just check out the tag. It will effectively restore the branch from the tag.

To archive and delete the branch:

git tag archive/<branchname> <branchname>
git branch -d <branchname>

To restore the branch some time later:

git checkout -b <branchname> archive/<branchname>

The history of the branch will be preserved exactly as it was when you tagged it.

18
  • 10
    Is there any reason not to use an object-tag in this case ? Being able to see who archived the branch and when could be interesting. Commented May 22, 2012 at 10:17
  • 12
    @GrégoryJoseph: That's a so-called "annotated tag". And yes, using that can make a lot of sense, I'd say.
    – onnodb
    Commented Dec 13, 2013 at 15:09
  • 35
    small note, you probably want branch -D since it's likely not to be fully merged if you are archiving it in this way Commented Mar 21, 2014 at 16:08
  • 10
    More general, and more meaningful imho git tag [-a -m "some description maybe"] archive/<any_name_you_like> <branchname or commit>. I did this when I was working on a branch and it was decided I had to take another course. I continue on the same branch, but with major changes. The work I did is now stored in that archive tag with a good name and description.
    – eigil
    Commented Mar 14, 2019 at 13:42
  • 18
    2 important commands missing: git push --tags (newly created archive tag pushed to server). git push origin :<branchname> (delete <branchname> from server).
    – jerrymouse
    Commented Jul 2, 2019 at 10:53
188

Jeremy's answer is correct in principle, but IMHO the commands he specifies are not quite right.

Here's how to archive a branch to a tag without having to checkout the branch (and, therefore, without having to checkout to another branch before you can delete that branch):

> git tag archive/<branchname> <branchname>
> git push origin archive/<branchname>
> git branch -D <branchname>

And here's how to restore a branch:

> git checkout -b <branchname> archive/<branchname>
2
  • 2
    git push origin archive/<branchname> to push the tag
    – Nearoo
    Commented Apr 4, 2023 at 10:25
  • I was able to push all my tags at once using git push --tags Commented Sep 8 at 16:52
57

Extending Steve's answer to reflect the changes on the remote, I did

# Create a tag named similarly to the branch but with the 'archive/' prefix
# Point it to the latest commit of the branch
git tag archive/<branchname> <branchname>

# Delete the branch locally
git branch -D <branchname>

# Delete the local reference of remote branch ("forget" the remote branch)
git branch -d -r origin/<branchname>

# Push local tags to remote
git push --tags

# Delete the remote branch
git push -d origin <branchname>
# or, similarly, 'git push origin :<branchname>'

To restore from the remote, see this question.

2
  • 2
    The last line can also be git push origin --delete <branchname> for Git v1.7.0+. Source: git-scm.com/book/en/v2/Git-Internals-The-Refspec
    – jslatane
    Commented Jan 13, 2023 at 17:56
  • 2
    This answer would be better with some explanation of the commands. At a glance they appear to be deleting the remote branch twice. I doubt that's true, but I'd have to research each command to know.
    – isherwood
    Commented Feb 16, 2023 at 15:10
46

Yes, you can create a ref with some non-standard prefix using git update-ref. e.g.

  • Archive the branch: git update-ref refs/archive/old-topic topic && git branch -D topic
  • Restore the branch (if needed): git branch topic refs/archive/old-topic

Refs with non-standard prefix (here refs/archive) won't show up on usual git branch, git log nor git tag. Still, you can list them with git for-each-ref.

I'm using following aliases:

[alias]
    add-archive = "!git update-ref refs/archive/$(date '+%Y%m%d-%s')"
    list-archive = for-each-ref --sort=-authordate --format='%(refname) %(objectname:short) %(contents:subject)' refs/archive/
    rem = !git add-archive
    lsrem = !git list-archive

Also, you may want to configure remotes like push = +refs/archive/*:refs/archive/* to push archived branches automatically (or just specify on push like git push origin refs/archive/*:refs/archive/* for one-shot ).

Another way is to writing down SHA1 somewhere before deleting branch, but it has limitations. Commits without any ref will be GC'd after 3 months (or a couple of weeks without reflog), let alone manual git gc --prune. Commits pointed by refs are safe from GC.

Edit: Found a perl implementation of the same idea by @ap: git-attic

Edit^2: Found a blog post where Gitster himself using the same technique. He named it git hold.

10
  • 7
    Excellent, apart from everyone else on this thread, you actually answered the question.
    – tzrlk
    Commented Feb 3, 2017 at 0:52
  • 1
    Last but not least, I'm not sure what params should be passed to these alias commands. I love the approach, but would love some more detail! Commented Feb 6, 2021 at 23:55
  • 1
    Thanks for the comment. Adding more aliases to operate on archive (git grep-archive, git fetch-archive, git push-archive?) sounds like a nice idea. I'll update the answer along with some synopsis. rem stands for remember for me, but you'll rename it as you like anyway. It's just a shortcut :) Commented Feb 8, 2021 at 2:54
  • 1
    This perl implementation (git-attic) has list, save, rm, fetch, and push Commented Aug 27, 2021 at 18:32
  • 1
    I believe seconds is not very useful/important for the timestamp, therefore makes the ref name feel cluttered to me. It does ensure some unique-ness, though. Here is a version I wrote here: gist.github.com/devinrhode2/6e370ddfe824b1f49515f56e6314a434 Commented Jun 23, 2022 at 20:00
20

You could archive the branches in another repository. Not quite as elegant, but I'd say it's a viable alternative.

git push git://yourthing.com/myproject-archive-branches.git yourbranch
git branch -d yourbranch
3
  • 5
    You can create git-bundle instead of separate repository. Commented Aug 20, 2009 at 17:15
  • Forks are really great. @JakubNarębski what is git-bundle? Commented Feb 6, 2021 at 1:18
  • 1
    @DevinGRhode : git bundle is a way to create a file that contains selected portion of the project history, that can be used to fetch or clone from. It was originally intended, AFAIK, for "sneakernet" transport. Commented Feb 7, 2021 at 9:09
15

Here is an alias for that:

arc    = "! f() { git tag archive/$1 $1 && git branch -D $1;}; f"

Add it like this:

git config --global alias.arc '! f() { git tag archive/$1 $1 && git branch -D $1;}; f'

Bear in mind there is git archive command already so you cannot use archive as an alias name.

Also you can define alias to view the list of the 'archived' branches:

arcl   = "! f() { git tag | grep '^archive/';}; f"

about adding aliases

2
  • 5
    With newer versions of git (as suggested here), this alias gives completion: !git tag archive/$1 $1 && git branch -D
    – Lack
    Commented Jul 27, 2017 at 21:33
  • 2
    For the curious ones, git archive is for, like, creating .tar archives, according to my 5 seconds skimming the docs page. Commented Oct 11, 2020 at 1:33
7

I am using following aliases to hide archived branches:

[alias]
    br = branch --no-merge master # show only branches not merged into master
    bra = branch                  # show all branches

So git br to show actively developed branches and git bra to show all branches including "archived" ones.

1
  • 6
    Whether a branch has been merged into master has nothing to do with its archive state. For instance, in my dev team we have a few branches which were created specifically to test stuff. We want to keep those branches in our archive, but we definitely don't want to merge them into master.
    – Bart
    Commented May 23, 2016 at 20:17
6

I would not archive branches. Put another way, branches archive themselves. What you want is to ensure the information relevant to archeologists can be found by reliable means. Reliable in that they aid daily development and doesn't add an extra step to the process of getting work done. That is, I don't believe people will remember to add a tag once they're done with a branch.

Here's two simple steps that will greatly help archeology and development.

  1. Link each task branch with an associated issue in the issue tracker using a simple naming convention.
  2. Always use git merge --no-ff to merge task branches; you want that merge commit and history bubble, even for just one commit.

That's it. Why? Because as a code archeologist, rarely do I start with wanting to know what work was done on a branch. Far more often it's why in all the screaming nine hells is the code written this way?! I need to change code, but it has some odd features, and I need to puzzle them out to avoid breaking something important.

The next step is git blame to find the associated commits and then hope the log message is explanatory. If I need to dig deeper, I'll find out if the work was done in a branch and read the branch as a whole (along with its commentary in the issue tracker).

Let's say git blame points at commit XYZ. I open up a Git history browser (gitk, GitX, git log --decorate --graph, etc...), find commit XYZ and see...

AA - BB - CC - DD - EE - FF - GG - II ...
     \                       /
      QQ - UU - XYZ - JJ - MM

There's my branch! I know QQ, UU, XYZ, JJ and MM are all part of the same branch and I should look at their log messages for details. I know GG will be a merge commit and have the name of the branch which hopefully is associated with an issue in the tracker.

If, for some reason, I want to find an old branch I can run git log and search for the branch name in the merge commit. It is fast enough even on very large repositories.

That is what I mean when I say that branches archives themselves.

Tagging every branch adds unnecessary work to getting things done (a critical process which should be ruthlessly streamlined), gums up the tag list (not speaking of performance, but human readability) with hundreds of tags that are only very occasionally useful, and isn't even very useful for archeology.

11
  • 3
    But what about the clutter? Perhaps if there were a way to hide the old branches under 10 cubic yards of dirt.
    – bvj
    Commented Mar 6, 2018 at 20:52
  • 4
    This is useful, but it isn't applicable to unmerged branches. Sometimes an experiment was done on a branch and you want to keep the content in case some of it becomes useful later. Commented Mar 30, 2019 at 0:18
  • 2
    @bvj I think this answer is suggesting you should always delete merged branches, because you can always get back to them via the merge commit. I agree with this. Commented Mar 30, 2019 at 0:19
  • @NeilMayhew Yes, I have about 10 unmerged branches like that open myself. Each are associated with an open task so I can remember what it was I was doing. I'll either do something with them, or they become so out of date they're no longer relevant and I'll delete them. I worked on a project absolutely drowning in "I might need it later" branches so we could hardly see what we were doing. It was really an excuse for some devs not to have to clean up after themselves. A bit of leeway is fine, but don't let it get out of control.
    – Schwern
    Commented Mar 30, 2019 at 2:42
  • @Schwern I agree. I've been on projects like that too. I think converting the branches to tags is a good way to get rid of the clutter, because the list of tags is always going to grow whereas the list of branches shouldn't (because it represents the amount of work that's ongoing). Using namespacing for tags makes the list more manageable, but packrat tendencies definitely need to be resisted. A developer should retain the commits on their own machine unless there's a good chance someone else will use them eventually. Commented Mar 30, 2019 at 15:15
4

I sometimes archive branches as follows:

  1. Generate patch files, e.g., format-patch <branchName> <firstHash>^..<lastHash> (get firstHash and lastHash using git log <branchName>.
  2. Move the generated patch files to directory on a file server.
  3. Delete the branch, e.g., git branch -D <branchName>

"Apply" the patch when you need to use the branch again; however, applying the patch files (see git am) can be challenging depending on the state of the target branch. On the plus side, this approach has the benefit of allowing the branch's commits to be garbage-collected and saving space in your repo.

2
  • Had to be patient & scroll all the way to the bottom to find the most useful answer for me & gladly give it a long overdue first upvote! :)
    – davmos
    Commented Apr 1, 2021 at 16:36
  • “can be challenging depending on the state of the target branch.” Hmm. The commit message of the patch should say what commit it was based on (the parent of firstHash). Commented Apr 28, 2023 at 11:03
4

Step 0. Check to make sure that the working tree is clean so as to not lose any work:

git status

Step 1. From the root of the local repository, check out the branch and then tag it to be archived:

git checkout <branch_name> && git tag archive/<branch_name>

Step 2. Upload tags to remote and be sure to be in another branch before continuing, for example main:

git push origin --tags && git checkout main

Step 3. Delete the branch from the local and remote repositories:

git branch -D <branch_name> && git push origin -d <branch_name>

where you should replace <branch_name> with the name of the branch to archive, and origin with the name of the remote repository if other than origin.

Comments:

  • Before and after step 1 you may want to run git tag to notice the added tag.

  • Before and after step 3 you may want to watch https://github.com/<github-username>/<github-repository-name>/branches and/or run git branch -a to notice how the branch was deleted.

  • To restore a branch:

git checkout -b <branch_name> archive/<branch_name>

followed by

git push --set-upstream origin <branch_name>

References:
https://gist.github.com/zkiraly/c378a1a43d8be9c9a8f9
https://dev.to/clsource/archiving-git-branches-3k70

1
  • 2
    Late to the party but just for completeness' sake: You can tag a branch that you're not currently on, by doing git tag archive/<branch_name> remotes/origin/<branch_name> or similar. Then the only other commands needed are git push origin --tags and git push origin -d <branch_name> (Avoids potentially expensive checkout operations) Commented Jul 1, 2022 at 14:37
3

My approach is to rename all branches I don't care about with a "trash_" prefix, then use:

git branch | grep -v trash

(with a shell key binding)

To retain the coloring of the active branch, one would need:

git branch --color=always | grep --color=never --invert-match trash
2
  • 3
    If renaming branches, you might as well put them in a namespace "archive/"
    – qneill
    Commented Aug 2, 2018 at 17:56
  • I think this is much more simple. PS: my prefix is zzz_ Commented Apr 11, 2023 at 20:03
1

You can use a script that will archive the branch for you

archbranch

It creates a tag for you with the prefix archive/ and then deletes the branch. Make sure you understand what it does before you use it =)


Usage - $/your/location/of/script/archbranch [branchname] [defaultbranch]

If you want to run the script without writing the location to it add it to your path

Then you can call it by

$ archbranch [branchname] [defaultbranch]

The [defaultbranch] is the branch that it will go to when the archiving is done. There are some issues with the color coding but other than that it works. I've been using it in projects for a long time.

2
  • 2
    Per Stack Overflow Help, you need to disclose your affiliation with your product. Commented Jun 25, 2013 at 13:39
  • Oh, sorry, didn't know. I am the author of the script.
    – Banezaka
    Commented Jan 12, 2014 at 18:40
1

In Git a branch is just a pointer to some commit. So removing a branch will only remove a pointer, it won't remove the associated code even if the branch was never merged. So that "archiving" a local branch is as simple as remembering the pointer name (commit hash). You can find this information in ./git/refs/heads directory. Alternatively you can simply copy the branch-to-commit map into a text file like follows.

git branch -v > /path/to/backup/branches.txt

Once a branch has been removed you can restore it locally with the following command.

git branch <branch_name> <commit_hash>
1
  • 6
    If nothing is pointing the the SHA ref they could get purged so if braches are deleted some commits could be left dangling thus removd
    – Simson
    Commented Nov 10, 2022 at 1:45
1

To archive branches older than n months or years, run this bash script.

#!/bin/bash

# Average days in a month - 30.436875
# Hours in a day 24
# Minutes in an hour 60
# Seconds in a minute 60
months_in_year=12
days_in_month=30.436875
hours_in_day=24
minutes_in_hour=60
seconds_in_minute=60

# Input is x months or x years
# $1 an integer
# $2 a time metric

# Name of the script, follows through simlinks
script_name="$(basename "$(test -L "$0" && readlink "$0" || echo "$0")")"

if [ $# -le 1 ]; then
    echo "Usage: ./${script_name} [1-9] [month(s)/year(s)]"
    exit 1
fi

time_period=$1
time_metric=$2

if [[ ${time_metric} =~ "month" ]]; then minimum_branch_age_in_seconds=$( echo "scale=4; $time_period * $days_in_month * $hours_in_day * $minutes_in_hour * $seconds_in_minute" | bc); fi
if [[ ${time_metric} =~ "year" ]]; then minimum_branch_age_in_seconds=$( echo "scale=4; $time_period * $months_in_year * $days_in_month * $hours_in_day * $minutes_in_hour * $seconds_in_minute" | bc); fi

echo "minimum_branch_age: $1 $2"
echo "minimum_branch_age_in_seconds: ${minimum_branch_age_in_seconds%.*}"

git for-each-ref refs/remotes | while read commit type ref;do
    current=$(date +%s)
    headcd=$(git log -1 --pretty=%cd --date=format:%s ${commit})
    age_in_seconds=$((current-headcd))
    if [[ ${age_in_seconds} -ge ${minimum_branch_age_in_seconds%.*} ]];then
        branch=$(echo $ref | sed 's=refs/remotes/origin/==g')
        age_in_months=$( echo "scale=4; $age_in_seconds / $days_in_month / $hours_in_day / $minutes_in_hour / $seconds_in_minute" | bc)
        echo "archiving $branch - age in seconds - $age_in_seconds - age in months - $age_in_months "
        git tag archive/${branch} ${branch}
        git push -d origin ${branch}
        git branch -D ${branch}
        echo "Unarchive with: git checkout -b ${branch} archive/${branch}"
    fi
done

Thanks to Jeremy for the meat to this stew.

0

With secure situation if you are on other branch locally:

git tag archive/{branchname}  origin/{branchname} 
git tag archive/{branchname}   {branchname} 
git branch -D {branchname} 
git branch -d -r origin/{branchname} 
git push --tags
git push origin :{branchname} 
2
  • 1
    can you clarify what do you mean by "secure situation", please? Commented Jul 21, 2023 at 10:13
  • 1
    Accidental deletion of branch before archiving.
    – Wolvverine
    Commented Aug 20, 2023 at 10:49
0

Here is an alias for archiving all old branches except 10 newest ones.

[alias]
  archiveoldbranches = "!git branch --sort=-committerdate | tail -n +10 | awk '{$1=$1};1' | xargs -L1 -I {} sh -c 'git tag archive/{} {}; git branch -D {}'"

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.