Definition of downstream and upstream

Question

I ve started playing with Git and have come across the terms  upstream  and  downstream    I ve seen these before but never understood them fully   What do these terms mean in the context of SCMs  Software Configuration Management tools  and source code

User · Answer

Upstream  as related to  Tracking  The term upstream also has some unambiguous meaning as comes to the suite of GIT tools  especially relative to tracking  For example         git rev-list --count --left-right    upstream     HEAD     gt 4   12       will print  the last cached value of  the number of commits behind  left  and ahead  right  of your current working branch  relative to the  if any  currently tracking remote branch for this local branch  It will print an error message otherwise        gt error  No upstream branch found for        As has already been said  you may have any number of remotes for one local repository  for example  if you fork a repository from github  then issue a  pull request   you most certainly have at least two  origin  your forked repo on github  and upstream  the repo on github you forked from   Those are just interchangeable names  only the  git      url identifies them       Your  git configreads        remote  origin          fetch    refs heads   refs remotes origin          url   git github com myusername reponame git     remote  upstream          fetch    refs heads   refs remotes upstream          url   git github com authorname reponame git     On the other hand    upstream  s meaning for GIT is unique         it is  the branch   if any  on  said remote   which is tracking the  current branch  on your  local repository         It s the branch you fetch pull from whenever you issue a plain git fetch git pull  without arguments    Let s say want to set the remote branch origin master to be the tracking branch for the local master branch you ve checked out  Just issue          git branch --set-upstream  master origin master     gt  Branch master set up to track remote branch master from origin        This adds 2 parameters in  git config        branch  master          remote   origin        merge   refs heads master       now try  provided  upstream  remote has a  dev  branch        git branch --set-upstream  master upstream dev     gt  Branch master set up to track remote branch dev from upstream         git config now reads       branch  master          remote   upstream        merge   refs heads dev       git-push 1  Manual Page       -u    --set-upstream       For every branch that is up to date or successfully pushed  add upstream  tracking  reference  used by argument-less git-pull 1  and other commands  For more information  see branch  lt name gt  merge in git-config 1        git-config 1  Manual Page       branch  lt name gt  merge       Defines  together with branch  lt name gt  remote  the upstream branch for the given branch  It tells git fetch git pull git rebase which branch to merge and can also affect git push  see push default                    branch  lt name gt  remote       When in branch  lt  name    it tells git fetch and git push which remote to fetch from push to  It defaults to origin if no remote is configured  origin is also used if you are not on any branch    Upstream and Push  Gotcha   take a look at git-config 1  Manual Page      git config --global push default upstream    git config --global push default tracking   deprecated        This is to prevent accidental pushes to branches which you   re not ready to push yet

User · Answer

Upstream Called Harmful  There is  alas  another use of  upstream  that the other answers here are not getting at  namely to refer to the parent-child relationship of commits within a repo  Scott Chacon in the Pro Git book is particularly prone to this  and the results are unfortunate  Do not imitate this way of speaking   For example  he says of a merge resulting a fast-forward that this happens because     the commit pointed to by the branch you merged in was directly   upstream of the commit you   re on   He wants to say that commit B is the only child of the only child of     of the only child of commit A  so to merge B into A it is sufficient to move the ref A to point to commit B  Why this direction should be called  upstream  rather than  downstream   or why the geometry of such a pure straight-line graph should be described  directly upstream   is completely unclear and probably arbitrary   The man page for git-merge does a far better job of explaining this relationship when it says that  the current branch head is an ancestor of the named commit   That is the sort of thing Chacon should have said    Indeed  Chacon himself appears to use  downstream  later to mean exactly the same thing  when he speaks of rewriting all child commits of a deleted commit      You must rewrite all the commits downstream from 6df76 to fully remove   this file from your Git history   Basically he seems not to have any clear idea what he means by  upstream  and  downstream  when referring to the history of commits over time  This use is informal  then  and not to be encouraged  as it is just confusing   It is perfectly clear that every commit  except one  has at least one parent  and that parents of parents are thus ancestors  and in the other direction  commits have children and descendants  That s accepted terminology  and describes the directionality of the graph unambiguously  so that s the way to talk when you want to describe how commits relate to one another within the graph geometry of a repo  Do not use  upstream  or  downstream  loosely in this situation    Additional note  I ve been thinking about the relationship between the first Chacon sentence I cite above and the git-merge man page  and it occurs to me that the former may be based on a misunderstanding of the latter  The man page does go on to describe a situation where the use of  upstream  is legitimate  fast-forwarding often happens when  you are tracking an upstream repository  you have committed no local changes  and now you want to update to a newer upstream revision   So perhaps Chacon used  upstream  because he saw it here in the man page  But in the man page there is a remote repository  there is no remote repository in Chacon s cited example of fast-forwarding  just a couple of locally created branches

User · Answer

In terms of source control  you re  downstream  when you copy  clone  checkout  etc  from a repository  Information flowed  downstream  to you   When you make changes  you usually want to send them back  upstream  so they make it into that repository so that everyone pulling from the same source is working with all the same changes  This is mostly a social issue of how everyone can coordinate their work rather than a technical requirement of source control  You want to get your changes into the main project so you re not tracking divergent lines of development   Sometimes you ll read about package or release managers  the people  not the tool  talking about submitting changes to  upstream   That usually means they had to adjust the original sources so they could create a package for their system  They don t want to keep making those changes  so if they send them  upstream  to the original source  they shouldn t have to deal with the same issue in the next release

User · Answer

When you read in git tag man page      One important aspect of git is it is distributed  and being distributed largely means there is no inherent  upstream  or  downstream  in the system      that simply means there is no absolute upstream repo or downstream repo  Those notions are always relative between two repos and depends on the way data flows   If  yourRepo  has declared  otherRepo  as a remote one  then    you are pulling from upstream  otherRepo    otherRepo  is  upstream from you   and you are  downstream for otherRepo    you are pushing to upstream   otherRepo  is still  upstream   where the information now goes back to     Note the  from  and  for   you are not just  downstream   you are  downstream from for   hence the relative aspect     The DVCS  Distributed Version Control System  twist is  you have no idea what downstream actually is  beside your own repo relative to the remote repos you have declared    you know what upstream is  the repos you are pulling from or pushing to  you don t know what downstream is made of  the other repos pulling from or pushing to your repo     Basically   In term of  flow of data   your repo is at the bottom   downstream   of a flow coming from upstream repos   pull from   and going back to  the same or other  upstream repos   push to       You can see an illustration in the git-rebase man page with the paragraph  RECOVERING FROM UPSTREAM REBASE    It means you are pulling from an  upstream  repo where a rebase took place  and you  the  downstream  repo  is stuck with the consequence  lots of duplicate commits  because the branch rebased upstream recreated the commits of the same branch you have locally      That is bad because for one  upstream  repo  there can be many downstream repos  i e  repos pulling from the upstream one  with the rebased branch   all of them having potentially to deal with the duplicate commits   Again  with the  flow of data  analogy  in a DVCS  one bad command  upstream  can have a  ripple effect  downstream     Note  this is not limited to data  It also applies to parameters  as git commands  like the  porcelain  ones  often call internally other git commands  the  plumbing  ones   See rev-parse man page      Many git porcelainish commands take mixture of flags  i e  parameters that begin with a dash  -   and parameters meant for the underlying git rev-list command they use internally and flags and parameters for the other commands they use downstream of git rev-list  This command is used to distinguish between them

User · Answer

That s a bit of informal terminology   As far as Git is concerned  every other repository is just a remote   Generally speaking  upstream is where you cloned from  the origin   Downstream is any project that integrates your work with other works   The terms are not restricted to Git repositories   For instance  Ubuntu is a Debian derivative  so Debian is upstream for Ubuntu

[git] Definition of "downstream" and "upstream"

Upstream (as related to) Tracking

Upstream and Push (Gotcha)

Examples related to git

Examples related to version-control

Examples related to versioning

Examples related to terminology

Examples related to definition