719

I am having some difficulty understanding how to use tags versus branches in .

I just moved the current version of our code from to , and now I'm going to be working on a subset of that code for a particular feature. A few other developers will be working on this as well, but not all developers in our group are going to care about this feature. Should I be creating a branch or a tag? In what situations should I be using one versus the other?

Nae
  • 14,209
  • 7
  • 52
  • 79
Bialecki
  • 30,061
  • 36
  • 87
  • 109
  • 12
    Since web search for how to use git tag brought me to that link first, I add that there is a better (IMHO) answer about a tag here: https://stackoverflow.com/questions/35979642/what-is-git-tag-how-to-create-tags-how-to-checkout-git-remote-tags – Alex Martian Dec 28 '18 at 11:44

14 Answers14

601

From the theoretical point of view:

  • tags are symbolic names for a given revision. They always point to the same object (usually: to the same revision); they do not change.
  • branches are symbolic names for line of development. New commits are created on top of branch. The branch pointer naturally advances, pointing to newer and newer commits.

From the technical point of view:

  • tags reside in refs/tags/ namespace, and can point to tag objects (annotated and optionally GPG signed tags) or directly to commit object (less used lightweight tag for local names), or in very rare cases even to tree object or blob object (e.g. GPG signature).
  • branches reside in refs/heads/ namespace, and can point only to commit objects. The HEAD pointer must refer to a branch (symbolic reference) or directly to a commit (detached HEAD or unnamed branch).
  • remote-tracking branches reside in refs/remotes/<remote>/ namespace, and follow ordinary branches in remote repository <remote>.

See also gitglossary manpage:

branch

A "branch" is an active line of development. The most recent commit on a branch is referred to as the tip of that branch. The tip of the branch is referenced by a branch head, which moves forward as additional development is done on the branch. A single git repository can track an arbitrary number of branches, but your working tree is associated with just one of them (the "current" or "checked out" branch), and HEAD points to that branch.

tag

A ref pointing to a tag or commit object. In contrast to a head, a tag is not changed by a commit. Tags (not tag objects) are stored in $GIT_DIR/refs/tags/. [...]. A tag is most typically used to mark a particular point in the commit ancestry chain.

tag object

An object containing a ref pointing to another object, which can contain a message just like a commit object. It can also contain a (PGP) signature, in which case it is called a "signed tag object".

jskroch
  • 333
  • 2
  • 8
Jakub Narębski
  • 309,089
  • 65
  • 217
  • 230
  • 44
    Question: if you treat a branch like a tag (that is, you create it, then never update it), is there any real difference? – Steve Bennett Feb 16 '12 at 03:22
  • 38
    @SteveBennett absolutely. There contains different informations (you can sign a tag, you can add a description to a branch). You can move a branch (so even if you never update it, you can still rebase it.). You cannot move a tag (it is linked to a specific commit). You can choose to push a branch. Tags aren't pushed by default. You should never use one for the other (unless you are really in an SVN mindset, in which case you need to "un-learn" that fast if you want to go on with git). – VonC Feb 16 '12 at 05:00
  • 22
    @SteveBennett: There is a difference how Git treats branches vs how it treat tags. Besides what VonC said, you cannot advance tag by mistake: "`git checkout `" would generate anonymous unnamed branch (so called 'detached HEAD') and select _state_ of tag. Creating a new commit does it on this unnamed branch, and does not change what tag points to. – Jakub Narębski Feb 16 '12 at 14:04
  • 73
    IMO, branches are separated timelines (parallel world), and tags are specific moments at a timeline. – eonil Jul 21 '12 at 16:00
  • 28
    No one here has mentioned it yet but you can use a tag as the point to start a branch: `git checkout -b ` –  Dec 08 '12 at 23:45
  • 4
    @KenStailey: You can use _any_ commit (any revision) as a starting point for a branch; using tag is just a special case of this situation. – Jakub Narębski Dec 09 '12 at 10:32
  • 2
    @VonC i find your comment more usefull/concise than your first answer, that is, branches are moved when rebased, when tags aren't. – 131 Feb 28 '14 at 07:57
  • Is it GPG instead of PGP signature? – Gerald May 21 '15 at 04:16
595

A tag represents a version of a particular branch at a moment in time. A branch represents a separate thread of development that may run concurrently with other development efforts on the same code base. Changes to a branch may eventually be merged back into another branch to unify them.

Usually you'll tag a particular version so that you can recreate it, e.g., this is the version we shipped to XYZ Corp. A branch is more of a strategy to provide on-going updates on a particular version of the code while continuing to do development on it. You'll make a branch of the delivered version, continue development on the main line, but make bug fixes to the branch that represents the delivered version. Eventually, you'll merge these bug fixes back into the main line. Often you'll use both branching and tagging together. You'll have various tags that may apply both to the main line and its branches marking particular versions (those delivered to customers, for instance) along each branch that you may want to recreate -- for delivery, bug diagnosis, etc.

It's actually more complicated than this -- or as complicated as you want to make it -- but these examples should give you an idea of the differences.

StackzOfZtuff
  • 2,534
  • 1
  • 28
  • 25
tvanfosson
  • 524,688
  • 99
  • 697
  • 795
  • 45
    in his case he wants to use branches, maybe you should also note this in your answer ;) – knittl Sep 22 '09 at 06:27
  • 14
    AFAIK, tags are not unique per branch. So yo can't give same names for different commits in separate branches. – M.Y. May 29 '12 at 09:25
  • 5
    @M.Y. Certainly not a bad thing, IMHO. Especially in the way described by tvanfosson, having more than one tag with the same name across different branches could become difficult to maintain. Given the example, I would think that if you *could* have tags with the same name across different branches, it would quickly be established as a bad practice. Good to know that you can't, though. Thanks M.Y.! – Swivel Aug 18 '13 at 04:28
  • 36
    A tag is just an alias for a commit hash. Same as you can checkout a commit with `git checkout 88c9f229f` you can do something like `git checkout your_tag` and you will checkout the commit that was aliased by the tag. – jterm Mar 15 '16 at 19:36
  • 11
    @jterm, aren't branches aliases too? The only difference is that a branch-alias automatically repoints itself to the most recent commit in the chain. – Viktor Molokostov Aug 26 '16 at 14:53
  • Considering all the comments, it seems like most use cases for tags are to just tag stuff...mark them for easier recognition (of a specific release version for example). Then, it seems that only `lightweight tags` are useful, what's a real use case for a heavy `annotated tag`? The official Git docs actually recommend using the `annotated tags` in most cases. Is it because they are checksummed? – iBobb Mar 17 '22 at 09:47
167

No metaphor is perfect, but you can picture your repository as a book that chronicles progress on your project.

Branches

You can think of a branch as one of those sticky bookmarks:

enter image description here

A brand new repository has only one of those (called master main), which automatically moves to the latest page (think commit) you've written. However, you're free to create and use more bookmarks, in order to mark other points of interest in the book, so you can return to them quickly.

Also, you can always move a particular bookmark to some other page of the book (using git-reset, for instance); points of interest typically vary over time.

Tags

You can think of tags as chapter headings.

bookmarks

It may contain a title (think annotated tags) or not. A tag is similar but different to a branch, in that it marks a point of historical interest in the book. To maintain its historical aspect, once you've shared a tag (i.e. pushed it to a shared remote), you're not supposed to move it to some other place in the book.

jub0bs
  • 60,866
  • 25
  • 183
  • 186
  • 32
    I would image that a branch would be a book, and bookmarks are tags. You can continue writing a book, but you cannot edit it. Tag is just a fixed moment in the book. – Mārtiņš Briedis Feb 13 '15 at 13:20
  • @MārtiņšBriedis In my metaphor, the commit DAG is the book. Since a Git branch is nothing more than a "pointer" to a commit, I think the bookmark analogy is appropriate, here. – jub0bs Feb 13 '15 at 17:04
  • 6
    @Jubobs I liked the branch explanation as a line of development. A book would be a branch. You can start a new book based on the place where left the main branch. You can write them paralel and then try to merge in to a one book/branch. – Mārtiņš Briedis Feb 16 '15 at 08:55
  • 3
    @MārtiņšBriedis I understand the way you like to think of a branch, but I find that, in Git, that's actually misleading. See http://stackoverflow.com/questions/25068543/what-exactly-do-we-mean-by-branch – jub0bs Feb 16 '15 at 09:17
  • 2
    this one is really a time saver answer – Ali Foroughi Dec 09 '15 at 08:38
  • 2
    If you start writing a book and you have first 50 pages, you can copy it (create a new branch from it) and continue writing two books simultaneously (or give the book copy to some other writer - developer) and finally you can merge the changes from the other book to your book. – barell Feb 22 '17 at 23:18
  • 1
    This answer is conveying a very wrong idea. Branches are not part of one linear history like a book is. And your bookmarks are more like tags, pointing to specific points in the story. – Hubert Grzeskowiak Jan 05 '18 at 00:43
  • 1
    @HubertGrzeskowiak I concede that the linear aspect of a book makes my analogy somewhat misleading. However, it is useful and I stand by it. Branches _can_ be moved (hence bookmarks) whereas tags can't/shouldn't (hence chapter headings). An idea that I've encountered many times and is misleading is to think of a branch as a line of development or a series of commits. – jub0bs Jan 05 '18 at 06:03
  • A "line of development" or "series of commits" is exactly what a branch is. – Hubert Grzeskowiak Jan 12 '18 at 03:11
  • @HubertGrzeskowiak I beg to differ; [it's not as simple as that](https://stackoverflow.com/questions/25068543/what-exactly-do-we-mean-by-branch). – jub0bs Jan 12 '18 at 03:22
  • I like Chris' answer in your linked question: "the commits that are reachable from the commit pointed to by the branch". By following the parent's parent of a branch's HEAD recursively you eventually end up with a series of commits that represent a line of development. My problem with the book analogy is that you can't simply add new text at the end of a chapter or at any bookmarks, and you can't copy a whole chapter in order to try out some different endings. Also all chapters are linear, making a sequence, whereas branches are part of a directed acyclic graph. – Hubert Grzeskowiak Jan 12 '18 at 03:33
  • 1
    @HubertGrzeskowiak I like Chris's answer too, but "the commits that are reachable from the commit pointed to by the branch" form a DAG, not _a line_, in the general case. Moreover, there is no one-to-one mapping between 1) the commits that are reachable from the commit pointed to by a branch and 2) those branches. A simple example of this is a repo containing a single commit, with two branches—`master` and `develop`, say—both pointing at that commit. You can't unambiguously refer, in speech, to that commit as `master` or `develop`. – jub0bs Jan 12 '18 at 03:40
  • @HubertGrzeskowiak A branch is more than what it can reach; it has a name, a reflog, etc. – jub0bs Jan 12 '18 at 03:42
  • Agree with Tag explanation but not with Branch (as its again Tag).. Branch is actually a parallel world/time line which can merge at some point later.. – Anvesh Yalamarthy Jul 15 '19 at 14:37
  • 1
    @AnveshYalamarthy Whatever metaphor works for you, but be aware that thinking of a branch as a line of development or a sequence of commits is misleading. See https://stackoverflow.com/questions/25068543/what-exactly-do-we-mean-by-branch – jub0bs Jul 15 '19 at 14:50
  • @jub0bs, agreed, that is my point too.. !! Writing/traversing a book is similar to sequence of commits.. – Anvesh Yalamarthy Jul 17 '19 at 14:49
45

What you need to realize, coming from CVS, is that you no longer create directories when setting up a branch.
No more "sticky tag" (which can be applied to just one file), or "branch tag".
Branch and tags are two different objects in Git, and they always apply to the all repo.

You would no longer (with SVN this time) have to explicitly structure your repository with:

branches
   myFirstBranch
     myProject
       mySubDirs
   mySecondBranch
     ...
tags
   myFirstTag
     myProject
       mySubDirs
   mySecondTag
   ...

That structure comes from the fact CVS is a revision system and not a version system (see Source control vs. Revision Control?).
That means branches are emulated through tags for CVS, directory copies for SVN.

Your question makes senses if you are used to checkout a tag, and start working in it.
Which you shouldn't ;)
A tag is supposed to represent an immutable content, used only to access it with the guarantee to get the same content every time.

In Git, the history of revisions is a series of commits, forming a graph.
A branch is one path of that graph

x--x--x--x--x # one branch
    \ 
     --y----y # another branch
       1.1
        ^
        |
        # a tag pointing to a commit
  • If you checkout a tag, you will need to create a branch to start working from it.
  • If you checkout a branch, you will directly see the latest commit it('HEAD') of that branch.

See Jakub Narębski's answer for all the technicalities, but frankly, at this point, you do not need (yet) all the details ;)

The main point is: a tag being a simple pointer to a commit, you will never be able to modify its content. You need a branch.

In your case, each developer working on a specific feature:

  • should create their own branch in their respective repository
  • track branches from their colleague's repositories (the one working on the same feature)
  • pulling/pushing in order to share your work with your peers.

Instead of tracking directly the branches of your colleagues, you could track only the branch of one "official" central repository to which everyone pushes his/her work in order to integrate and share everyone's work for this particular feature.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • 3
    @VonC: I think you mean "SVN" in your answer and not "CVS". CVS does not have the directory structure; SVN does. In fact, tagging in git reminds me much more of tagging in RCS/CVS than tagging in SVN (where tag == degenerate branch). – Chris Cleeland Aug 16 '12 at 16:06
  • 1
    @ChrisCleeland good point. I have tried to separate a bit more CVS and SVN points in the (edited) answer. – VonC Aug 16 '12 at 18:08
43

Branches are made of wood and grow from the trunk of the tree. Tags are made of paper (derivative of wood) and hang like Christmas Ornaments from various places in the tree.

Your project is the tree, and your feature that will be added to the project will grow on a branch. The answer is branch.

Jason
  • 431
  • 4
  • 2
19

I like to think of branches as where you're going, tags as where you've been.

A tag feels like a bookmark of a particular important point in the past, such as a version release.

Whereas a branch is a particular path the project is going down, and thus the branch marker advances with you. When you're done you merge/delete the branch (i.e. the marker). Of course, at that point you could choose to tag that commit.

Gazzer
  • 4,524
  • 10
  • 39
  • 49
17

It looks like the best way to explain is that tags act as read only branches. You can use a branch as a tag, but you may inadvertently update it with new commits. Tags are guaranteed to point to the same commit as long as they exist.

Vassili Gorshkov
  • 179
  • 1
  • 2
  • 11
    *Tags are guaranteed to point to the same commit as long as they exist.* Not completely true. You can actually move a tag with `git tag -f`. – jub0bs Feb 13 '15 at 17:08
16

Tags can be either signed or unsigned; branches are never signed.

Signed tags can never move because they are cryptographically bound (with a signature) to a particular commit. Unsigned tags are not bound and it is possible to move them (but moving tags is not a normal use case).

Branches can not only move to a different commit but are expected to do so. You should use a branch for your local development project. It doesn't quite make sense to commit work to a Git repository "on a tag".

Greg Hewgill
  • 951,095
  • 183
  • 1,149
  • 1,285
13

the simple answer is:

branch: the current branch pointer moves with every commit to the repository

but

tag: the commit that a tag points doesn't change, in fact the tag is a snapshot of that commit.

jsina
  • 4,433
  • 1
  • 30
  • 28
11

The Git Parable explains how a typical DVCS gets created and why their creators did what they did. Also, you might want to take a look at Git for Computer Scientist; it explains what each type of object in Git does, including branches and tags.

jub0bs
  • 60,866
  • 25
  • 183
  • 186
Bombe
  • 81,643
  • 20
  • 123
  • 127
6

A tag is used to mark a version, more specifically it references a point in time on a branch. A branch is typically used to add features to a project.

Number45
  • 139
  • 3
  • 9
6

simple:

Tags are expected to always point at the same version of a project, while heads are expected to advance as development progresses.

Git User Manual

Adeel
  • 2,901
  • 7
  • 24
  • 34
Bar Horing
  • 5,337
  • 3
  • 30
  • 26
0

We use

  • branches in the dev environment for feature development or bug fix
  • lightweight tags for the test environment on feature branches
  • annotated tags for the release/prd (main branch)

After each annotated tags, all feature branches rebase from the main branch.

As said by others, a branch is a line of development and the head moves forward as newer commits arrive. This is ideal for the feature development.

Lightweight tag is fixed to a specific commit, which makes it ideal to create an internal version and let qa team to test a feature after dev is completed.

Annotated tag is ideal for the release to production, as we can add a formal message and other annotations when merging the tested feature branch to the main branch (stable).

Release Management with Git

Ali Khosro
  • 1,580
  • 18
  • 25
0

neovim on github:

v0.3 is a branch enter image description here

v0.3.1 ... v0.3.4 ... are tags

enter image description here

nightly and stable are tags, not branches

enter image description here

Good Pen
  • 625
  • 6
  • 10