416

I find git hard to understand as I could not find the meaning of the words used for the actions. I have checked the dictionary for the meaning of 'stage' and none of the meanings were related to source control concepts.

What does 'stage' mean in the context of git?

Kamil Naja
  • 103
  • 3
000
  • 4,525
  • 4
  • 16
  • 16
  • related: [What is the benefit of git's two-stage commit process (staging)?](http://programmers.stackexchange.com/questions/69178/what-is-the-benefit-of-gits-two-stage-commit-process-staging) – gnat Apr 07 '16 at 10:02
  • 22
    Git does indeed have its own vocabulary. And since every instruction is formulated in the special vocabulary it is hard to get started. To "stage" is to do `git add file.ext` for a specific file, or `git add .` to affect all modified and untracked files. Files that have been added in this way are said to be "staged" and they will be included in the next "commit". The commit is a snapshot of your work created e.g. with `git commit -m "I wrote something"`. – Jonatan Öström Dec 15 '16 at 17:47
  • 19
    Git is hard to understand because there is no conceptual tutorial out there. All go through unnecessary details. – Xaqron Jun 12 '17 at 08:31
  • 3
    Did you mean to remove the "terminology" tag from this question? It seems a perfectly valid tag to me. – Philip Kendall Jan 29 '18 at 12:08
  • 1
    For some reason, the best way I could understand the importance of staging is from this answer in Quora: http://qr.ae/TbSK2I – Lamar Feb 25 '18 at 08:11
  • 1
    One thing that was not clear to me from other answers was that if you only want to do a partial commit of your local repo, you stage the files you want to commit. Leave the others alone (like local testing config). When you commit, you commit your staged files. For example, in visual studio https://docs.microsoft.com/en-us/azure/devops/repos/git/gitquickstart?view=azure-devops&tabs=visual-studio. This is described in the purple box there. – mminneman Dec 26 '19 at 17:55
  • 1
    What does "unstaged" then ? reference https://www.atlassian.com/git/tutorials/saving-changes/git-stash, "...git stash command takes your uncommitted changes (both staged and unstaged), ..." – vikramvi Feb 25 '21 at 10:24
  • @000 - Don't worry if you don't understand Git. Git is the incarnation of the concept "Why make it simple when you can make it complicated". It is like a backup system that allows you to f*** up your backups big time (and also screw up the work of everybody working in parallel with you). It is developed by minds that also like low-level, over-complicated things that want to be simple and powerful but all they manage to do is to be really dangerous (things like gun powder, C, Linux, etc). – Gabriel Jun 27 '23 at 09:31
  • 1
    @Xaqron - I agree with you. I still haven't seen a good/solid (but without all the unnecessary and gory details) out there. All tutorials explain how different parts of Git work, but never the general concept. Usually, they show a picture like the one in Rook's answer. Actually, if you google Git and look at images, the internet is flooded with pictures like that. – Gabriel Jun 27 '23 at 09:41

8 Answers8

390

To stage a file is simply to prepare it finely for a commit. Git, with its index allows you to commit only certain parts of the changes you've done since the last commit. Say you're working on two features - one is finished, and one still needs some work done. You'd like to make a commit and go home (5 o'clock, finally!) but wouldn't like to commit the parts of the second feature, which is not done yet. You stage the parts you know belong to the first feature, and commit. Now your commit is your project with the first feature done, while the second is still in work-in-progress in your working directory.

Rook
  • 19,861
  • 9
  • 53
  • 96
  • 7
    Good explanation. Note that git, being distributed, obviously allows you to commit *both* features, since commits are local (at first). Still, you might want to put split the modifications into one commit per feature, and again staging comes in handy. – sleske Nov 15 '11 at 09:08
  • 97
    I don't understand why you need staging for this. I can do this with HG or even SVN by only committing the relevant files. It feels like this feature is primarily designed to aid people who insist on working with the command line where it's harder to check boxes on what you are committing. – jiggy Sep 19 '12 at 17:55
  • 99
    @jiggy git allows you to stage _part_ of a file. You can also stage a file, make further modifications, then commit the state it was in at staging. You can't do that in subversion. – Izkata Apr 30 '14 at 00:47
  • 1
    @Izkata even SVN allows committing only a part of a file now, or at least the TSVN client does. This has been true for at least 6 months at this point. – Vaibhav Garg Aug 08 '14 at 09:34
  • 4
    @jiggy In SVN, there is something, between the time that you select which files/parts of files to commit and when you finish writing your commit message, that records which files/parts you selected to commit. It might never be explicitly mentioned, it might be implemented in the SVN client rather than an actual part of the repository, it might just be some flags in memory, but that is SVN's stage. I haven't looked at HG, but I suspect it does the same thing. The difference with git is that git acknowledges that it is a thing, records it to disk, and lets the user get to it directly. – 8bittree Aug 08 '14 at 20:13
  • 1
    @8bittree The difference between git and any sensible VCS is that you don't need to know what it's doing for it to just work. If SVN is staging my commits seamlessly without my knowledge, then why can't git do it? – jiggy Aug 08 '14 at 22:36
  • 1
    @jiggy It can, just use `git commit -a` (for "all") to skip having to stage files, and commit all changes – Izkata Aug 10 '14 at 06:22
  • @Izkata You can also pass (as far as I'm aware) the same arguments you'd pass to `git add` to `git commit` - eg `git commit file1 file2`, `git commit --interactive .` and so forth. – Lexi Aug 18 '14 at 21:39
  • @LexiR `--interactive` is newer on commit; it's not on the version we have installed at work – Izkata Aug 18 '14 at 23:04
  • 8
    The second arrow "stage files" in the figure might be misleading. "stage hunks" might be more accurate? – Ida Oct 10 '14 at 13:44
  • @Ida - You have a point. Unfortunatelly, I don't have the time at the moment to make a better picture, but much appreciate pointing that out. Maybe one day I'll redo it... – Rook Oct 10 '14 at 14:53
  • 2
    This answer would be much easier to understand with an example command sequence showing how to stage and commit only parts of a modified file vs. the (usual) direct committing of a whole file. – fnl Jun 29 '17 at 09:32
  • 1
    (for reference, c.f. `git add --patch` and/or `git add --interactive`) – fnl Jun 29 '17 at 09:38
  • @jiggy Your `SVN` client (e.g. TortoiseSVN) does the staging. You can install `git` clients (e.g. TortoiseGit if you want a similar experience) that do the same for you, so you can also check boxes instead. – CodeMonkey Aug 11 '17 at 12:51
  • TFS rules...... ! – Legends Jun 20 '18 at 11:49
  • @Izkata Mercurial allows committing a selection of the current changes, including parts of files. – cja Feb 01 '20 at 20:30
  • 1
    This answer doesn't explain why the staging step is required. It could be rephrased as "you commit the parts you know belong to the first feature" and not suggest a need for an intermediate step – cja Feb 01 '20 at 20:32
162

Since everyone so far has answered it the "formal" way, let me do this with alternatives to enhance learning with the power of metaphors.

So the staging area is like:

  • a cache of files that you want to commit
  • not a series of tubes but actually a dump truck, ready to move the work you load it with, in to the repository
  • a magical place where selected files will be turned into stone with your wizardry and can be magically transported to the repository at your whim
  • the yellow brick road for the files to go happily to the repository (or fall off if you want to revert)
  • the fictional place at the sea port where files are received a pair of cement shoes and then thrown into the repository sea
  • the receptions desk at the library, you put the files there for the librarian to prepare for filing into the library
  • a box where you put things in before shoving it under your bed, where your bed is a repository of boxes you've previously have shoved in
  • the loading bay of files before it goes into the repository warehouse with the power loader
  • the filter of an electric drip coffee maker, if the files are like the coffee powder, then the committed files are the brewed coffee
  • the Scrooge McDuck's office next to the vault, the files are like the coins before they go into the vault of his massive Money Bin
  • the pet store, once you bring a pet home you're committed

It's magical!

alan
  • 103
  • 4
Spoike
  • 14,765
  • 4
  • 43
  • 58
  • Love the analogies; way to go bud ^_^ – Musa Al-hassy Feb 22 '19 at 14:58
  • Love the final analogy. – meTchaikovsky Apr 09 '19 at 00:49
  • This answer was "DESPERATELY" needed among the space of common attempts to explain the metaphysics of the git index = git staging. Frankly, I'd also like to know what Linus was thinking when he decided he wanted an index area. I like it, but I simply want to better appreciate why it's good to have it and how to use it most effectively. – Thom Ives Dec 02 '20 at 03:56
54

Staging is a step before the commit process in git. That is, a commit in git is performed in two steps: staging and actual commit.

As long as a changeset is in the staging area, git allows you to edit it as you like (replace staged files with other versions of staged files, remove changes from staging, etc.).

Broken metaphor time:

Consider a scenario where you call the movers to get your stuff from your old appartment to your new appartment. Before you do that, you will go through your stuff, decide what you take with you and what you throw away, pack it in bags and leave it in the main hallway. The movers simply come, get the (already packed) bags from the hallway and transport them. In this example, everything until the movers get your stuff, is staging: you decide what goes where, how to pack it and so on (e.g. you may decide that half your stuff will be thrown away before the movers even get there - that's part of staging).

From a technical point of view, staging also supports transactional commits, by splitting all operations into what can fail (staging) and what cannot fail (commit):

The commit in git is implemented transactionally, after the staging is sucessfull. Several steps in the staging can fail (for example, you need to commit, but your HDD is 99.9999% full, and git has no space to perform a commit). This will fail in staging (your repository will not be corrupted by a partial commit) and the staging process doesn't affect your commit history (it doesn't corrupt your repository in case of an error).

utnapistim
  • 5,285
  • 16
  • 25
30

To stage a file is to prepare it for a commit. Because git exposes this action to the users control it allows you to create partial commits, or to modify a file, stage it, modify it again, and only commit or revert to the original modification.

Staging allows you finer control over exactly how you want to approach version control.

Josh K
  • 23,019
  • 10
  • 65
  • 100
24

To add to the other excellent answers, here's where the name for "stage" comes from:

I checked the dictionary for the meaning of stage and none of the meanings was related to source control concepts.

In English, "to stage" can mean

organize and participate in (a public event): UDF supporters staged a demonstration in Sofia

(from http://oxforddictionaries.com/definition/stage )

The name "staging" for the git feature derives from this meaning: When staging, you are preparing and organizing a commit. Of course a commit is not quite the same as a performance, but it is an important event in a VCS :-).

sleske
  • 10,095
  • 3
  • 29
  • 44
  • 4
    I'd have thought it more closely matched the use in [staging post](https://en.wikipedia.org/wiki/Staging_area) – Useless Apr 30 '14 at 16:21
  • 2
    Ditto. Also, "a point, period, or step in a process or development." – Darien Aug 08 '14 at 23:05
  • Also 'staging server' is a pretty common term used to describe a server that's between development and production. – Eternal21 May 02 '17 at 19:15
8

The "stage" is a technically required intermediate step in the process of checking in a file, namely collecting the changes to be added to the repository. Git's authors chose to make this step visible and persistent where other VCS make it a transient part of the commit process. So it's just an option that git gives you because it can so why not?

The way I see it, the main thing the git "stage" gives you that other VCS don't is that you can use it to checkpoint a file. It's effectively an unnamed, uncommented local commit that gives you an intermediate step between being done with all your work and committing it to the repository permanently and having nothing saved in your local repo at all.

For example, let's say you have a feature partially finished. It's in a stable state, passes all the tests, and could go into production, but you have more work to do on it. You could stage all your changes and then continue to work on the feature.

Later, you'll have the option to just commit what you staged (and push that commit to the remote repository) or to add your new changes to your staging area and then commit that all at once, or to undo just your new changes and revert your working directory to the state it was in when you staged your changes.

It's completely possible to practically skip the staging area altogether and just use the -a option to git commit if you don't find the staging area a helpful concept. Lots of people skip staging and GUI tools usually allow for this, too.

Old Pro
  • 793
  • 6
  • 11
  • _"other VCS don't"_ -- what makes you think so? Shelving at Perforce appears to be doing what you describe, and even with few additional bells and whistles – gnat Apr 29 '14 at 20:39
  • 1
    @gnat yes, of course many other VCS give you something like staging. By "other VCS" I mean other VCS that don't have something like git's stage, since that is what the OP was referring to. – Old Pro Apr 29 '14 at 21:18
  • 2
    I found this answer to be immensely better than all the above, since it's the only one that clarifies why Staging exists at all (being _technically required_), an explanation of its origin (_Git's authors chose to make this step visible and persistent_), adding what I personally find to be a good definition for it (_an intermediate, unnamed, uncommented local commit_). However, I think it could be improved by quoting a source for the statement about the origin of Staging, and elaborate some more on why it's _technically required_. @OldPro – alelom Aug 13 '19 at 15:58
  • Were git being designed from scratch, this could have just been part of a generalized "branch" concept, local and unseen by others in this case. Likewise "stash" could have just been implemented (and understood!) as a specific instance of the generalized concept of "branch." You could then have any number of levels of "staging" you prefer. – Ron Burk Apr 29 '20 at 17:49
7

With most other version control systems, there’s 2 places to store data: your working copy (the folders/files that you’re currently using) and the datastore (where the version control decides how to pack and store your changes). In Git there’s a third option: the staging area (or index). It’s basically a loading dock where you get to determine what changes get shipped away.

source: http://gitready.com/beginner/2009/01/18/the-staging-area.html

Mostafiz Rahman
  • 181
  • 1
  • 3
  • 1
    this doesn't seem to add anything substantial over prior 6 answers – gnat Jul 11 '14 at 04:13
  • It mentions Index. And references to a very thorough article. Upvoting. BTW, some answers above are merely jokes. – Gangnus Jan 19 '18 at 21:46
-1

My understanding is, suppose i am developing login feature and required 5 consecutive steps to complete. So here staging will help you to work on steps like
done with step 1 stage it.
done with step 2 , now step 1 and step 2 both are correct stage it.
mess up with step 3 no problem checkout latest staged step that is step 2
same way once you done with all 5 steps that means feature is complete now perform commit.

palash140
  • 145
  • 2
  • this doesn't seem to add anything substantial over points made and explained in prior 9 answers – gnat Aug 25 '16 at 12:30
  • yes you are right, i just tried to make explanation simple and sweet – palash140 Aug 25 '16 at 15:37
  • And what i feel like to use this concept practically i tried to explain that – palash140 Aug 25 '16 at 15:39
  • consider taking a look at discussion here: [Are second TL;DR answers acceptable?](http://meta.programmers.stackexchange.com/q/8128/31260) (FWIW compared to prior answers this one doesn't look simple nor sweet to me) – gnat Aug 25 '16 at 15:41
  • thank you sir, i have a question to ask. I have come across many answers and most of them are too complex yes those are correct but difficult to digest at once, I do believe if you can't explain anything in simple way then you have not learned it properly or don't know how to use it. So is it bad now to put summary or simple way to answer ?? – palash140 Aug 25 '16 at 15:56