Branches are pointers to a commit and that pointer is refreshed when a new commit is created. One could say they are a wandering tag (without explaining a tag for now).

The actual chain of commits that represent what we see as branch comes from the commits themselves. Those commits point back to their parent commit.

And then one can see why no branch has any special meaning: It is a chain of related commits with a named entrypoint. Once you delete a branch (i.e. the named wandering pointer to a commit), you cannot identify a branch as such anymore. It is just a chain of related commits without a named label now. And nothing besides the name distinguished the branch from other commit chains before.

The master/dev/release branches are then a convention to keep an updated commit pointer on the chain of commits containing changes of interest.

Git was actually designed initially for email based workflows where there was no central remote at all. Basically, that works by exporting patches and then applying them to your local branch. The branch name isn't even part of the patch.

A git patch is just a textualized form of the list of commits you created locally. You can apply them to any branch you like. As long as you and whomever applies the patch has a common ancestor commit in common, the patch may merge cleanly. It's good hygiene to ensure it does by for example rebasing/merging/squashing before you email somebody your patches. If that somebody is called Linus Torvalds, he's going to be pretty strict about things like commit messages and things not being spaghetti ball of merges, reverts, forks, etc. Your mess, your problem. Linux development still works via mailing list. And forget about emailing him directly with a patch; you need to use the mailing lists like everybody else. And he works with a network of senior contributors that screen everything that comes in and that aggregate all the patches coming from upstream. So, he only gets involved at the end of the process.

Of course the rest of us use network protocols to sync our repositories. But the important distinction here is that this is a two step process. First you fetch content from remote. This is simply ensuring you have all the commit objects you need in your local git database. Any branches you have are simply text files with the commit content hash they point to as the content in .git/refs/heads. Remote branches are the same but live in your local .git/refs/remotes/. Those branches might be named something like origin/main to make it clear that that is a local branch from the origin remote. And then you rebase/merge between your local and "remote" (i.e. also local) branch as needed. Pull is just short hand for doing both steps in one go. All merges are local. Same with rebases.

Most of the conventions people project on git are kind of cultural and vary between people and companies. It's helpful to read up on the git internals in the Git book. Github is sort of an opinionated take on this that back in the day made people coming from centralized version systems like subversion feel at home by providing a central repository and allowing them to push their changes there or "share" branches there. Not necessarily a great idea for bigger projects and limiting write access is common on Github.

Not even branch. You can combine two unrelated repositories, and in theory you could cherry-pick commits from one of the original repositories to the other.

Of course, in practice this rarely works because the files mentioned in the commit don't exist in the other repository. But there's nothing in git's mechanisms that stops this: it's just a bunch of commits, which are actually just a bunch of file contents.

The whole "diff" or "patch" concept in git is just way of doing data presentation - rather than showing you the actual commit, which is generally not helpful, it shows you the difference between the contents of the commit, and the same files in the state referenced by the previous commit.

The reason is that a git patch is not merely a diff but an export of the actual commit objects and referred content (trees, blob diffs, hashes, etc.). Applying the patch recreates the exact commit objects on the other side. The end state is exactly the same as if you would have merged the commits from some branch. There is no difference.

Git diff, shows you a normal diff. It's not the same thing. You can indeed apply such diffs to your local work copy. But that's not the same thing as a git patch.

The commands you need are git format-patch (exports the patch) and git apply (applies it).

More generally, the branch name is not stored with commits; it has to be computed by walking back from the branch tips, and commits can have multiple possible branch names based on this. In other words, git does not preserve information about which branch was actually active when you made a particular commit. (Mercurial, by contrast, stores the branch that was active when a commit was made in the commit, so that information is preserved.) The article discusses some implications of this, although it doesn't phrase it quite the way I did above.

A good name for these "wandering tags" would be "heads", since it's what git calls them internally (for instance, when not packed, they're stored at the "refs/heads/" path in the repository). This also exposes a distinction between a "branch" and its "head", and that distinction can be useful.

Or are there such leaves which are not considered 'heads'?

Now nobody understands their VCS and nobody will ever understand it, as the explanations are either too detailed and miss the forest for the trees or too high level and skip over all the trees that kill you when you accidentally run into them.

I hope someone somewhere manages to convince us all to move to something sane.

SVN, branching that takes forever instead of a simple file with a commit hash in it? Are you serious?

Mercurial, when I had to use it for almost 2 years? The single thing I missed the most is the fact that "everything is just a label" (or pointer if you will).

Fossil I can't comment on with certainty, as I never really used it.

This is probably gonna get voted into oblivion, but most devs just don't get VCS, period (yes I'm a dev, so this is an inside perspective). Git or not. They didn't get it in CVS days, they didn't get it in SVN days and they didn't get various commercial ones either. Somehow most devs just don't grok version control trees.

But so far git is the single best VCS I have got to use. Everything that I actually need day to day follows from grokking the one simple rule: All those branches and tags are just labels/pointers/sticky notes and you can move them around at will and it's fast.

I do get that there are tricky situations with octopus merges and all that jazz and the Linux kernel and a few other open source projects are probably some of the trickier use cases to understand. For your run of the mill corporate situation? Keep `master`/`main`/`whateveryoucallit` history straight with one commit per feature/change by doing rebases and squashing and you will never have a single minute of misunderstanding what is going on. IFF you grok that "everything is just a label" and you've actually "created a branch" by just creating a file in `.git/refs/heads/` yourself!

And the second rule is: before you try anything, just: commit! And never close that terminal window. You might need that commit hash to reattach a label to it after you "destroyed" your branch (but git has not garbage collected yet and it's all actually still there). Or someone else still has your commits and you just get them from there and reattach a label. It's really so simple.

But what happens if you merge branch A into beanch B? A and B will both contain the commits of A, but in B there may be commits of B between the commits that were merged. Do the same commits of A then have different parents depending on which branch they are on?

    In git it's all just labels/pointers

Of course actual "branches" in the commit tree exist whether you label them or not. Until `git` does a garbage collection and gets rid of anything that doesn't have a pointer ultimately leading to it - something that a human would understand aka branch/tag. And that's why we call these labels "branches" as well but it's actually one word for two things here. The actual tree branch and the label that's called branch.

And a branch and a tag are basically the same exact thing underneath, just a file in the `.git` directory somewhere that contains a commit hash. All the meaning and differentiation of branch or tag is just in the human brain and how we and our tools treat them. Such as if you look at a particular commit in your tool of choice, it will tell you which branch it's part of. To create a branch you can literally just create a thousand randomly named files in the right part of the `.git` directory containing the same commit hash and suddenly this commit "is on all those branches". That's what git does and why creating a branch in git is so super fast.

1. Create a new merge commit with two parents: the commit pointed to by A and the commit pointed to by B.

2. Set branch B to point at the new merge commit.

This is a non-linear history; when comparing some commits there isn't a "before" or "after."

Other ordering is possible, e.g. --topo-order

Absolutely not. Commits are immutable (representing whole repo state, not a diff), and branches are just (mutable) pointers to them.

As the sibling already noted, a merge commit is just a regular commit. It simply points to multiple parents, "merging" them. Aside of the whole machinery to resolve conflicts etc. that's pretty much all there is to it.

When your graph topology allows it, you can also merge branches without generating a new commit (so called "fast forward" merges) - such a merge does nothing but rewrites the branch pointer. You can also create merge commits that point to more parents than two ("octopus" merges). Reconciling the commits' content can get quite complicated in such cases, but from the repo graph perspective it's nothing special.

To make things more clear: Repo state here is the contents of all files, and some metadata including a pointer to the previous commit.

So a commit hash uniquely identifies not only a set of files but the unique history leading up to it! That's why we some people like to call git the original block chain (there's no proof of work involved of course so it can never be used for payments or anything like that, but the merkle tree bit is similar enough).

And then I learned that git branches are branches in exactly the same way that the first element of a linked list in C “is” the linked list. Git was made by C people and they’re used to referring to entire data structures by way of some root element.

I mean that doesn’t make me dislike the name any less but at least now I see where they were coming from.

Without disregarding them, it's not a tree, but a DAG.

Try not to do this (imagine a 5-way merge conflict).

I haven't really seen specific guidelines as to when and why should anyone start a new repo. Are there some? Or is "mono-repo" the best solution, and when and for whom. Surely we need more than one git-repo in the whole world?!

This is why I think of branches as pointers. The file contents are literally just a pointer to a commit on the DAG.

In fact, Mercurial uses the term “bookmark” for its lightweight, git-like branching. Mercurial’s branches have slightly different semantics and can’t be deleted like bookmarks or git branches

Real natural tree branches grow.

If you move the branch to point somewhere else, then it's better/more accurately said that you changed the name to refer to a different branch. We can think of branches as the chains of commits; it's the names we give them that 'wander' both as we commit and if we move them to a different branch. But merging (as it were!) the concepts of branches and names for their tips is convenient, and often equivalent/inconsequential.

FWIW this is actually backwards. The word "branch" was already in common use (to refer to the same basic idea) in SCM systems going back decades, and in almost all of those a "branch" was indeed a first class object with its own data that acted as a "container" for commits, both semantically and physically.

The fact that a "branch" is just a pointer is in fact a git innovation on top of the former idea.

A commit points to it's parent(s). Since a branch is just a commit ID, you can follow the parent links backwards to find the whole history of that branch.

So a "branch point" is just where two chains of parent links converge.

The special part are merge commits. Those have multiple parents, indicating that two histories fused into one.

If, for example, you have a structure like

        |
        o
       / \
      o   o
   A  |   |  B
      o   o
       \ /        
        o
       / \
      o   o
   C  |   |  D
      o   o
       \ /
        o
        |

Looks like this also switches to a monospaced font, which makes it easier to draw ASCII art.

  This should be rendered using a monospaced font. 
  _____
  \   /
   \ /
    O

Uh... yes it can. Commits have a list of 0 or more parents. That creates a DAG. There are literal hordes of tools out there that reliably interpret this, from visualizer tools to practical mutators like git bisect.

Maybe you're trying to say that no single commit order exists that traverses the whole tree. That's true, because branches can merge together. But it remains a completely interpretable graph nonetheless.

But it's true that conventionally, a new branch tip should always have the previous branch tip as an ancestor. But not always as a direct parent, and even if so it might be a merge commit that joins two different branches. There is indeed no single spanning path through a DAG.

But trying to explain it as "git doesn't store enough information" to construct that spanning path seems confused to me. It's not about what git stores, it's just math: there is no such path in the general case, period.

Once more, that conception may be intuitive but it is wrong. A branch is emphatically NOT a line through the DAG, it's the whole DAG. There simply is no single list of patches to apply to get from one commit to another, even if both were at some point heads of the same branch, and even if one is an ancestor of the other.

And the reason it's wrong is that branches can merge together. You can have commit A descended from both the "main" branch and the "topic_a" branch, despite the fact that those two had diverged. This isn't a bug, it's a feature. You don't have to use it if you don't want to (lots of projects require linear commit histories in their main branch), but it's part of the tool nonetheless because some projects (Linux especially) use it heavily and to great effect.

This has nothing to do with lists of patches. Nevertheless, for any given path, it is always possible to compute a list of patches that would match that path. Just compute the diffs between all adjacent pairs of commits on that path. What you maybe mean is that you can’t replay just a single path and have it result in the same commit hash. That, of course, is correct, you need to replay the complete prefix DAG. However, I don’t see why you think that causes issues for the branches-as-paths conception.

Yes, branches can merge together. That just means that different paths can share nodes and edges. Just like two hiking trails can partially overlap. Again, I see no problem here.

If you have a branched structure like that, and dump each commit as a patch, and try to trace a "path through the DAG" by applying those patches, you will find that they don't apply after the first merge commit. There is no single list of patches, because that's not the structure of the history. The merge commit "patch" must be a different delta depending on where you came from.

  git log --graph --oneline

learngitbranching.js.org/

Which represents commits as circles with arrows pointing to their parents.

How do you undo a merge that you didn't mean to do/did wrongly?

    git reset --hard 

    git stash
    git checkout main
    git stash apply

(My git stash obsession is most likely just damage from years of using Perforce, which doesn't have a modified/staged distinction. The only way to commit only part of a changed file is via the equivalent of stash -> [restore half the file] -> commit -> stash pop.)

Prepares to be crucified...

You can checkout files and directories from completely unrelated commits and even unrelated repos!

I have used this to checkout specific useful files from other projects. It's a little nicer than just copying them in, because you can keep the repo tracking branch updated and keep checking out updates, and you can easily compare your file to theirs, and see what changes they have made to the file.

My preference is to use temporary branches and cherry-picking instead of stashing; I mostly use a gui* to work with git so it is easy to select the two or three commits to cherry-picking or see visually if an interactive rebase would work.

* https://gitextensions.github.io/

Your friends are unreasonable, unless you collaborate with them on the same branches and rewrite them after you shared them.

I usually used `switch` for this:

    # Check out the previous commit
    git switch -d HEAD~
    # Overwrite the branch
    git switch -C 

If you rewrite history on master… well… completely unreasonable.

Your strategy of seeing things as they are is a useful general purpose life skill.

Nothing wrong with this at all. Only people who don't understand and/or are scared of git don't like it.

You could also use cherry-pick to "donate" commits to other branches, instead of stash, of course. Magit has some great extra abstractions for this.

Some concept of "parent" and "child" branches would actually be pretty interesting. You do have to support multiple "parent" branches though for long term support branches.

Technically, there is special handling for both "master" and "main" in Git in fairly obvious, but I'd argue in a not very important way. When you merge two regular branches, the commit message is `Merge branch 'source' into destination`. But not if destination is `master` or `main` – the `into ...` part is omitted for those merge commits.

But this is just for backward compatibility. Git is very conservative in changing such user facing behavior as generated merge commit messages. To get Git to treat `master` and `main` truly without special handling, set empty value to config option `merge.suppressDest` [1]:

    $ git config merge.suppressDest ""

Source code:

For merge commit formatting: https://github.com/git/git/blob/2108fe4a1976f95821e13503fd33...

For default branch naming: https://github.com/git/git/blob/91e2ab1587d8ee18e3d2978f2b7b...

Git for Windows installer suggesting setting `init.defaultBranch`:

- https://github.com/git-for-windows/build-extra/blob/586c46ec...

- https://github.com/git-for-windows/build-extra/blob/586c46ec...

Footnotes:

[1] https://git-scm.com/docs/git-merge#Documentation/git-merge.t...

[2] https://git-scm.com/docs/git-init#Documentation/git-init.txt...

You probably mean this place in code: [1]. It uses function git_default_branch_name from refs.c [2], which uses config variable `init.defaultBranch` I've mentioned above. But if it and other look-ups fail, it does fall back to a hard-coded "refs/heads/master".

[1] https://github.com/git/git/blob/v2.43.0/remote.c#L2380-L2394

[2] https://github.com/git/git/blob/v2.43.0/refs.c#L671-L705

Edit: removed mention of a deprecated Git feature to avoid confusion.

https://github.com/gittuf/gittuf

So this is something that servers would certainly be able to use but it is also something that operates at the client level. And you could use it in environments where nobody uses the big hosted git platforms (github, gitlab, gitea, etc). So you could still use this in environments where you fetch changes to a project over ssh from a friend or cocontributor's dev machine. Or via basic, barebones read only https or ssh hosting.

i.e. this is access control that works independent of centralized servers.

This is worth an essay of its own.

To me, the opposite is a more worthy essay: why, with all the power to customize our tech, do we create things that consistently work differently than people's intuition?

The fact that it "mostly jibes" feels like a footgun, not a feature.

I get that for some, "git just works! It made sense from day one" but in my limited experience, 0% of people I've worked with have said that.

Sure, we can all learn the tech. And expert techniques in any field often don't jibe with naive expectations. But for me and the folks I work with, the tech industry feels like it's gliding more towards inscrutible tools vs ease of use.

We've hit a stage where many rely on code completion bots and answer-supplying bots instead of being able to directly embrace our tech. I wish the tech was more approachable on its own, but perhaps this is the natural evolution of things.

> A branch in Git is simply a lightweight movable pointer to one of these commits. The default branch name in Git is master. As you start making commits, you’re given a master branch that points to the last commit you made. Every time you commit, the master branch pointer moves forward automatically.

It has multiple diagrams explaining how commits point to their content and their parents, and branches point to commits. The Pro Git content has been there for at least 10 years (it's what I learned from 10 years ago).

Maybe the problem is just that the Internet is full of blogs that have incorrect diagrams (like those in the OP) and bad explanations, despite the main website having great documentation!

[0] https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-N...

What is your theory about why so many people are having difficulty creating a correct mental model about Git, and why so many people are writing incorrect blogs about it?

If you understand the basic design premise (commits are content-addressed immutable snapshots), the pointer stuff is kind of obvious. It has to work something like that for it to be able to be immutable if you want to be able to make branches/tags after the commit is created.

Git is not like that. It is very-very simple. If you learn basics of it, your intuition will align with git's "intuition" too, and you can do crazy things with total peace of mind, without googling or looking into source code of git to see how they had to make something "intuitive" in some definition of the word.

But I'm not sure git is a case of this. The DVCS that were created following people's intuitions were known to be slow and internally complex, but I have never heard about them failing. (And the slowness is obviously of a kind that can be optimized away.)

We just stuck with the worst UI ever devised in public for a VCS because of network effects.

Not this:

git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [--no-verify] [-s ] [-X ] [-S[]] [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m ] [-F ] [--into-name ] [… ]

I solve my own problems for my own reasons all the time and therefore other people's intuitions are immaterial in the process. It would just slow me down to think "how would other people use this" when I'm focused on some technical personal problem.

Commercial software developers solve problems with the clear purpose of selling the solution to others and where they know ahead of time roughly what their audience's intuitions are. This is why intuitive GUI applications exist - there are whole industries devoted to finding out what people expect, what lowers cognitive load etc. iOS and Android apps give you a good idea of what is possible with modern tech when the purposes are properly aligned.

The problem here is that git was expressly developed by Linus to solve his own problem in a way that made sense to him with no thought as to how other people would use it. There were no focus groups, early betas, feedback from users and so on. At best there has been slow fixes to the porcelain to fix the stuff that bothers the people who could make a PR to git. On the other hand there are also many front-end projects that attempt to align some other person's idea of how version control is supposed to work with the Git model.

Anyway - I am in the camp where I very seldom get confused about a git thing because the actual expressed model is really simple (in the way that x86 assembly is a "simpler" language than Java). I find most front-ends much more confusing because they don't seem to work the way I expect. But I am never surprised when someone's pet project is understandable only by themselves. Or indeed when a consumer product is consumer-friendly. The real surprise is when a lone programmer makes something for themselves that then goes on to have wide appeal.

There needs to be a balance between creating new, more powerful intuitions, and meeting people at the intuitions they already have.

Case in point, Git's branching model is pretty intuitive when you understand how Linux kernel development works. Perhaps 0% of the people you've worked with have looked into that. That's fine. Different cultures...

Another example that may be worth studying is mathematics and the hard sciences. Learning those is a lot about learning powerful intuitions.

Git (and sql) range from simple task to very complicated. Everyone likes to fantasize about making it easier but they’re only thinking about the fraction of functionality they use, rather than everything it currently does.

If someone could come up with a simpler solution they would, but they can’t because git can do extremely complicated things and is internally consistent. Most people underestimate that part

The intuition jvns meant is the idea that a branch only constitutes the commits since the point of divergence, but every branch actually contains the full history up to the root of its tree, and `git log` of course shows that. (If you want to only show the commits specific to a branch, you can do `git log parent..branch`. Note also that two branches need not have any common history, it's perfectly possible for a git graph to be disconnected.)

You probably know this, but since we are being pedantic we might as well get it right: That describes "git reset". "git checkout" does that and record that we are tracking branchname. So any commits will move both HEAD and the branchname reference.

  cat .git/HEAD

Intuition likely comes from how a tree (fir or oak, not binary) is structured. Generally a branch starts at the trunk or some other branch, not at the ground where the trunk gives way to roots.

Intuition is travelling down main path that has branches which diverge and re-merge into the main path.

That's why people seem to intuitively get "merging" back into main, whereas that doesn't generally make sense for physical trees.

I think a big issue with the presented intuition is that it's limited to wanting to merge the base/trunk/main branch into your feature branch. However, sometimes you want to merge a feature branch into another feature branch. With this in mind, you can form a better intuition, imo, where it's absolutely clear that you have to specify what branch you want to merge into another one.

You can optionally include the base commit when you send out “patches” to a mailing list.[2] Because it might not have been obvious that you based your changes on:

- The latest release

- The main development branch

- Some integration branch (probably an error)

You also need to keep the “base” in mind when you use `git range-diff` because that tool takes two ranges lik `main..previous` and `main..current`. And sometimes you can rely on just using `main..` and letting Git figure it out but in my experience passing an explicit value sometimes works better.

`git range-diff` is a super-cool but perhaps niche tool. But you basically have to use it on review round number 2 and higher when you are sending changes to the Git project.

[1] This has been discussed before and there was a patch series that implemented it. But that was basically a POC and done in the spirit of “this is useless IMO but here’s how you could do it”... and the implementation didn’t factor in all the shenanigans that you can do with `reset` and `rebase` so it couldn’t have been merged as-is. (Although to be fair: the bar was not set to work perfectly with any kind of branch reset etc., which I suspect is impossible in any case.)

[2] Patches after all are just commit messages plus the patches themselves and don’t tell you what they are based on.

for example: git merge my-branch will merge my-branch into the current one

while git rebase my-branch will rebase current one on top of my-branch

It's aimed at folks who know how to use `git add` and `git commit`, and would like to spend 15 minutes to form a mental model to help them understand what's going on.

In case it's useful to someone.

Warning, all text, no diagrams....

1. you don't change places often and thus git patterns.

2. you don't accidentally ship and commit a multi-GB file to your remote.

3. you don't change the git process on yourself and your colleagues without an extremely solid reason.

Document your chosen git patterns, even in 2023.

> “Wrong” models can be super useful.

This is used in usability and UX design a lot. Affording mental models that don't reflect the actual code, happens all the time.

It's the fundamental thing that makes UI work. I've always liked the title of Brenda Laurel's book - Computers as Theatre

All of the confusion expressed in the article stems from a misunderstanding that main should work in some special way.

Of course every branch's history goes all the way back to root and not to some arbitrary common commit of another branch like 'main'. Of course rebase and merge can work "backwards" from main onto some branch (because it's not "backwards" because main is not special - it just isn't done much in practice because keeping main straight helps with collaboration)

Furthermore, by realising that main isn't inherently special, it becomes obvious that the actions can be done between any two branches as needed.

The right mental model is - it's just commits, all the way down.

I didn't have that impression when reading that article.

To me it seems that the confusion comes from thinking in actual branches, and not from thinking anything special about main.

TLDR: Think of commits as snapshots, not diffs, and you'll be fine.

I had so much trouble trying to map my intuited/mental model of git onto pygit2 that I gave up and just used the git module.

I wanted to automate a fairly simple thing in Python as opposed to bash+commands. My reasoning being that I wanted to do it "right" and be a Big Programmer Real Boy(tm). I just wanted to create a branch remotely in Github, pull the repo, and checkout the new branch. I got stuck going in circles trying to figure out why I was always left in detached HEAD state because I didn't understand exactly what git was doing during a checkout.

    # repo has already been pulled
    if os.path.exists(repo_path):
        local_repo = git.Repo(path=repo_path)
        self.log.debug(f"current branch: {local_repo.active_branch.name}")
        local_repo.git.checkout(branch_name)

Of course, I've lost my poor implementation using pygit2, so I'll add that later if I find it. Thankfully there's a good discussion surrounding the issue I encountered in this excellent "roll your own git in Python", which doesn't use pygit2, but the concepts are the same: https://www.leshenko.net/p/ugit/#checkout-switch-branches

So something like this was what I expected to work, but leaves the repo in detached head state:

    import pygit2
    def checkout_branch(path, branch_name):
        repo = pygit2.Repository(path)

        branch_ref = repo.lookup_reference(f"refs/remotes/origin/{branch_name}")
        print(f"{branch_ref.name}")

        repo.checkout(branch_ref)

So I'm probably feeding the wrong thing into repo.checkout, but I'm honestly not sure what else it should be.

Funnily enough, git itself tries to do the right thing if pulled in a detached head state:

    From https://github.com/testorg/example
    * [new branch]          test       -> origin/test
    You are not currently on a branch.
    Please specify which branch you want to merge with.
    See git-pull(1) for details.

        git pull  

There always seems to be just one more stackoverflow thread to read that has the real answer: https://stackoverflow.com/questions/68435607/how-to-clone-ma... (found via Kagi which I wasn't using before, and the search "pygit2 detached head")

    def checkout_branch(path, branch_name):
        repo = pygit2.Repository(path)

        main_branch = repo.lookup_branch("main")
        print(f"Main branch upstream: {main_branch.upstream_name}")

        if branch_name not in repo.branches.local:
            print(f"Branch {branch_name} not found in local branches")
            remote_branch = "origin/" + branch_name
            if remote_branch not in repo.branches.remote:
                raise SystemExit(f"Branch {remote_branch} not found in remote branches")
            (commit, remote_ref) = repo.resolve_refish(remote_branch)
            repo.create_reference("refs/heads/" + branch_name, commit.hex)

        branch = repo.lookup_branch(branch_name)
        print(f"Branch name: {branch.name}")

        repo.checkout(branch)
        print(f"Is branch head? {branch.is_head()}")

        (commit, branch_remote) = repo.resolve_refish("origin/" + branch_name)
        print(f"Remote branch: {branch_remote.name}")
        branch.upstream = branch_remote

    d44aedc (HEAD -> test, origin/test) HEAD@{0}: checkout: moving from main to test

I wish there was a pair programmer AI that you had to explain stuff to. That would enable the "by explaining it, I solved it" phenomenon.

It's called rubber duck debugging, named for having an actual rubber duck at your desk you'd talk to.

One example that also bites people: moving files isn't stored in git - if you move files (even with `git mv`) and create a new commit, the moves aren't stored, but this is reconstructed later by the client based on similarity, which comes from the diff algorithm.

And git has multiple diff algorithms to pick from: https://git-scm.com/docs/git-config#Documentation/git-config...

And optionally to not detect renames in diff output with `diff.renames`: https://git-scm.com/docs/git-config#Documentation/git-config...

  commit 0123456789abcdef0123456789abcdef01234567
  parent fedcba9876543210fedcba9876543210fedcba98
  author Nemo  1234567890 +0000
  committer Nemo  1234567890 +0000
  rename-from path1.old
  rename-to path1.new
  rename-from path2.old
  rename-to path2.new

  Commit message

Of course, all of this assumes that moving a file is a meaningful operation. Perhaps ideally (for most languages and systems) you’d track this in far smaller chunks, so that you can track changes to a function even when it alone was moved to a different file. But things like Git aren’t interested in those kinds of semantics, and work technically at the file level, more or less, so I think it should track renames because in practice straightforward renames are super common, but often also involve other changes that thwart rename detection. Years ago Linus explained why he didn’t like storing moves (someone else has linked it), but I’m largely not sold with his reasoning—the theory of the perfect has hindered the useful, and file renames are commonly meaningful in ways more than he said.

is there an intuitive and enlightening explanation as to why it is this way?

As to why Linus doesn’t like storing file moves: https://public-inbox.org/git/Pine.LNX.4.58.0504150753440.721...

A few counter points:

- `hg` has `cp`, and I believe both Meta and Google's internal systems have that; - git has `mv`, which was added later, but it is really janky and git would forget files are moved which I think it is because git doesn't try to track that, likely because of the philosophy here; - as for storing file moves - nobody said you *have* to use this information, but you can certainly use this information to help with things.

The whole thread is an interesting read though and I will try going through it someday - maybe doing that would change my mind.

Having some sort of notion of "parent branch" would be very useful for a number of common operations, and a "renamed file" without having to rely on client dependent heuristics too. Empty files trip people up all the time so a "create file" would fit in perfectly.

These concepts would also be a good basis for more user friendly clients. Other version control systems do this the surprise factor should be low.

In short, Linus stance is that file renaming doesn’t matter, only the contents of files matter, and the moving of contents between files. Moved/renamed files then fall out as a special case of moving content.

Personally, I think this is a case of the better being the enemy of the good, and his “clearly superior algorithm” doesn’t work as well as claimed in practice. Or maybe tooling merely still isn’t up to snuff after 18 years.

Many people develop a bad mental model with commits as diffs, because that's what the UI makes them think commits are. It can work for a while, but inevitably leads to confusion later on.

Viewing the commit graph in terms of nodes (commits) or edges (diffs) is equivalent, these are dual views you can easily convert between. The internal representation is independent from that. Some VCSs use a mix of diffs and full revisions internally. Even Git uses delta compression when packing objects.

It stores a commit graph, and a tree at each of those commits. (A lossless compression algorithm deduplicates information.)

There's no need for the author to be concerned with what diffing information gets incorporated into the commit. Diffs are up to the viewer of the commit history.

  git show --diff-algorithm=...

I'm forever grateful for one of my early internships, where a guy from GitHub visited the office and gave us a one day workshop on Git. He started from the internals and explained how Git models your codebase. (He's also the one who introduced me to the idea of plumbing vs. porcelain.) Then once we had a common language, teaching the porcelain was a matter of starting from the plumbing and working upwards, rather than the other way around.

Another invaluable resource in learning Git is this interactive tutorial [0], which renders a tree diagram of start state and desired end state and makes you write the commands (for which there are often many options!) to get to that end state. This reinforces the idea that the best way of planning Git commands is to first visualize the end state you want, and then reason about how to get there.

Also: RTFM! Not just once. Go back to it. You'll learn something new every time. The docs [1] are really good.

[0] https://learngitbranching.js.org/

[1] https://git-scm.com/docs

  git pull
  git merge x
  git checkout [-b] foo
  git commit
  git push

objects: blobs, trees, commits, annotated tags

refs: branches (local, remote-tracking), tags, HEAD

other: working tree, index (aka cache aka staging area), remotes

There's lots of good guides out there: git from the bottom up, git for computer scientists, and the git parable are some that spring to mind. The Git Book is also excellent but it's more than 15 minutes of your time.

All the commands become way less mystifying when you understand what they are manipulating. You'll never get into a state where you want to `rm -rf` the entire repo and start with a new clone. There will hopefully be no more teeth grinding or keyboard mashing.

I've used a lot of VCSs over the years (rcs, sccs, cvs, subversion, clearcase, mercurial, git) and I swear git is the one I find least frustrating. The others may have had simpler interfaces, but they were either conceptually more complex, overly rigid in their design and behavior, or both (looking at you clearcase).

Look, I get it: a lot of folks see git as a necessary evil that's part of their day job. I disagree. I think it's really worth spending the time to learn well, probably like you invested some time in your editor and other tooling.

I mean, it's easier than C++. :-)

Most of the time, I'll humbly trade "overly rigid in their design and behavior" for "simpler interfaces". Please master VCS, discipline me !

So I usually do whatever I can to keep a single straight-line master history.

I branch off for a task, then after a while my branch isn't joined at the tip of master. So I rebase locally until it is. Then when the PR happens, master gets my changes added to the top, with no extra noise from merge commits.

Even if the local-rebase workflow is slightly more complicated, the payoff is a really clean history, making future reasoning about branches much easier. Not to mention merge conflicts are easier to solve when you rebase early & often.

This step is when newbies get confused because the diffs are the wrong way, and I've seen people often losing merge hunks from master when there are conflicts which can be disastrous (not a git issue, I've seen people do the same in SVN).

The proper solution IMO would be for git to have a "merge --reintegrate" which would do the opposite merge: take the main branch and merge the current feature branch to it... after success, you have a new feature branch.

This is why I also prefer rebase and cleaner history (but a common mistake here is to squash after PR approval... that should be done before, not after).

Consider finding peace by inverting your perspective: if your organization’s development process (for whatever reason, many of them legitimate) involves a crazy train-track of features being developed in parallel, isn’t it great that you're all at least using something that can keep track of it?

For a small team that should be unnecessary.

Frequent rebasing when you’re on a side branch of development is smart, but doesn’t conflict with my point.

Also, really, who looks back into the depths of history? There’s a reason a lot of backup schemes rotate a set of tapes over 30 or even 14 days. For that reason I am not a fan of rewriting history for “clarity”: I consider it wasted effort.

For the same reason I don’t care about branches for explorations that turned out to go nowhere — just mark the head abandoned and stop worrying about it.

Then there's of course `git log`, `git diff`, and `git status`, but I presume you know about those as well.

Unfucking thing is what of most of my knowledge of git goes to. Committing in the wrong branch, the wrong files, starting from the wrong commit, etc... Before you push, almost all mistakes are fixable, but it requires knowing a few more commands.

Then there are the project specific things. For instance, I worked on a project where we didn't have a central server we could push to and pull from (airgap). So we had to work with bundles. Git does that really well (it really is decentralized), but it is uncommon. Some people prefer a rebase-based workflow, some use cherry-picking extensively, some projects are more prone to conflicts than others, etc...

    git reset --hard

  git reset --soft HEAD~1

I throw in a `git reflog` once in a while, and the other day I patted myself on the back for my first use of `git tag -a mytag -m "This is my first tag!"` followed by `git push origin mytag`. I felt like god

now as much as I hate Xcode, its UI for looking at all my current changes and staging them by blocks of line for commit is like a superpower. as a solo developer working on brand new code, not all of my lines of thinking follow very atomic git commits, so it's nice to separate, say, some refactoring code from some actually new functionality when committing changes

  git log
  git show
  git status
  git blame
  git diff
  git add
  git reset

    git add
    git blame
    git branch
    git checkout
    git cherry-pick
    git clone
    git commit
    git diff
    git fetch
    git log
    git merge
    git pull
    git push
    git reset
    git rm
    git stash
    git status

My guess is, the OC relies on their IDE/editor for the functionality provided by some of these commands. But then, why not just go all the way. Just use all VC features provided by your IDE, and claim that you need zero git commands.

(well... it's about 1% because I do everything using the eclipse git UI, but that's the same behavior you get from that commands)

If you teach "checkout to move around and add -b when moving to a new branch the first time" that works pretty well

    git switch -c foo
    git push 
    > did you mean git push --args-with-branch-name?
    sigh, copy, paste, enter

Basically you can stop using checkout.

*edit*: fixed switch branch creation parameter.

I will keep using them so I can keep using old software. How new is it? Does ubuntu or debian have it?

git rebase HEAD~2 -i

git commit —amend

It summarizes fundamentals clearly.

https://youtu.be/EReooAZoMO0?si=sHqcYsf8v6LyWLAx

These are all people who have no problem understanding all kinds of other technologies and building complex systems from them.

It's not quite in "a monad is just a monoid in the category of endofunctors" territory, but when this many smart people have difficulty understanding something, I think Git is to blame, not the people.

Git is by no means perfect but the development community is great and there is a massive focus on improving the project and making things more approachable and intuitive.

And because of that, git actually has really solid, coherent documentation with easily digestible tutorials and guides for all the things you need to do.

So it always hurts me when I see people ranting and raving about how awful git is, how it can't do x, or how it doesn't make sense how it works but then you send them the guide or tutorial hosted on the git-scm website and suddenly it makes sense.

Not to be beating the RTFM horse but RTFM guys.

Or I have read a bunch of pages on the git-scm site, and I'm thinking "oh yes it all makes sense now." Then I'm trying to do something in the real world, and I get bizarre messages and conflicts that don't make any sense. Or I made a mistake and want to undo it, and end up in some crazy situation. The Documentation doesn't seem to help in anything but an ideal textbook scenario with no mistakes and complications.

1. https://git-scm.com/docs/user-manual

2. https://git-scm.com/book/en/v2

I can teach an artist or designer who has never heard of version control how to use Perforce in roughly 5 minutes. They will never blow off their leg and will likely never lose work. It will probably be a few months before they hit some edge case where they need help.

Git requires building a non-trivial mental model. Then it requires memorizing a whole bunch of unintuitive commands with unintuitive flags.

> Not to be beating the RTFM horse but RTFM guys.

Good tools are intuitive and can be incrementally learned without resorting to dense documentation.

RTFM is definitely a solution. But when a very large number of users have consistently similar issues at some point you have to stop blaming the users and admit the tool isn't easy to learn.

A significant part of this is that git explicitly supports more workflows than centralised VCS like subversion, perforce, or clearcase. Other than a few fairly small differences, mercurial and fossil (two other distributed VCS projects) have the same UX issues. You can't really reduce the complexity without just lopping off support. You can make that complexity more approachable/digestible (which the git devs are trying to do) but this fundamentally requires a certain willingness from the user to learn the tool.

For a lot of people git ends up being a sort of cargo cult where they get through the day with a set of magical incantations that make it work and solve their problems but without any real ability to troubleshoot when they do something wrong. Which is exactly the thing that prevents them from "gitting it".

And worth noting: I don't think I've ever worked with someone who has really gotten irreparably stuck with git after reading through the important parts of the user manual (not the references/man pages but the dedicated user manual [1]) and/or the git book [2]. There are some overly technical parts but they are towards the end of each. But if someone actually reads the entry-level user oriented parts of each/either document, odds are they'll understand enough to be able to actually solve their problems.

1. https://git-scm.com/docs/user-manual

2. https://git-scm.com/book/en/v2

I don't think this is quite correct. Mercurial is just as capable but has a much more accessible CLI.

Git pushes edge-cases to front and center. Almost all Git users use Git as a defacto centralized tool. There's a remote on GitHub, the end. Almost all users never need any feature that has to do with decentralization.

Git has somehow tricked people into thinking that version control is complicated. It's tragic.

Definitely unusual, but sometimes I want to move a folder between repos while preserving the commit history of the folder[0].

[0] https://stackoverflow.com/questions/41811986/git-move-direct...