How can I minimize git pain when everybody is working on master?

Question

Our documentation team of about ten people recently moved from SVN to Git. In SVN, everybody worked on master -- a model I've always hated, but I wasn't able to bring about that change. As part of the move to Git we've agreed to fix that, but we can't do it just yet (waiting on build changes that will allow builds from arbitrary branches). Meanwhile, everybody is working on master. Yes I know this is terrible, believe me.

We're seeing a lot more hiccups now than when we were using SVN, some of which are caused by Git's two-stage model (local and remote). Sometimes people commit but fail to push, or they pull and get conflicts with their pending local changes. Yesterday somebody clobbered recent changes -- somehow -- with a merge gone wrong, which I think was the merge that Git does when you pull and have outstanding changes. (He has not been able to tell me exactly what he did, and because he's using a GUI I can't just inspect his shell history.)

As the most-proficient Git user (read: I've used it before, though not for anything super-complicated), I'm the person setting policy, teaching the tools, and cleaning up messes. What changes can I make to how we are using the tools to make a shared, active master less error-prone until we can switch to doing development on branches?

The team is using Tortoise Git on Windows. We're using Tortoise Git because we used Tortoise SVN before. (I personally use the command line under Cygwin for some operations, but the team has made it clear they need a GUI and we're going with this one.) Answers should work with this tool, not propose replacements.

Tortoise Git has "Commit & Push" available as a single operation and I've told them to always do that. However, it's not atomic -- it can happen that the commit (which after all is local) works just fine but the push doesn't (say, due to a conflict, or a network issue). When that happens they get an ambiguous error; I've told them to check the BitBucket commit log if they have any doubts about a recent commit and, if they don't see it, to push. (And to resolve the conflict if that's the problem, or ask for help if they don't know what to do.)

The team already has the good habit of "pull early and often". However, it appears that pull can cause conflicts, which I think is new? If not new, much more frequent than in SVN. I've heard that I can change how Git does pulls (rebase instead of merge), but I don't have a good understanding of the trade-offs there (or how to do it in our environment).

The server is BitBucket (not Github). I have full administrative control over our repository but none on the server more generally. None of that is changeable.

The source files are XML. There are also graphics files, which everybody knows you can't merge, but we also almost never have collisions there. The merge conflicts come from the XML files, not the graphics.

What changes can I make to our use of Git to make sharing master go more smoothly for the team until we can move to using feature branches with reviewed, test-validated pull requests?

Answer 1

So far SourceTree was the best IDE to learn the concepts, because it shows all the relevant dialogs and options you have on each stage, the default options are usually fine, don't mess around with rebase, etc. Just follow the normal flow:

• Pull from master, just to be sure you are up to date
• Modify your files
• Commit your changes (that is only locally)
• Pull again from master (this will cause conflicts to appear)
• Edit all files until the conflicts are resolved, meaning the file is in the propper state you want to commit (no <<<<< HEAD and >>>> master messages in the raw file)
• Commit the merge changes
• Push

If everyone follows this recipe, they should be fine.

Each time someone does a bigger or central change, inform the other users to commit locally and pull from master, so they don't get too many conflicts later on and the first person is still around to resolve the conflicts together with them.

Invest a lot of time in getting everyone to understand the flow, otherwise they might get around a while and then feel comfortable with it while actually screwing the master branch, for example "use my file instead of remote" to resolve a conflict will just kick out all changes made by other people.

Git is a hard to learn system, especially if you grew up with Svn, be patient and give them time to learn it properly, with new users you can sometimes spend a day cleaning up some mess, that is normal. ;)

Answer 2

There are three main things to remember when you are working out of the same branch as someone else:

• Never use --force unless you really know what you are doing.
• Either commit or stash your work in progress before every pull.
• It usually goes easier if you pull right before a push.

Aside from that, I will point out that with distributed version control it doesn't matter if your "official" repo uses branches or not. That has no bearing whatsoever on what individual users do in their local repos. I used to use git to get local branches when my company used a completely different central VCS. If they create local branches for their features and make merging mistakes to their local master, it's a lot easier to fix without going into the reflog or some other magic.

Answer 3

Is it possible to take a day for everyone to learn git?

Computer using professionals should really be expected to learn a new tool and although possible to make many mistakes in any VCS they should be using the tool as it is designed to be used.

The best way to introduce this is to get every one to work on their own branch when they make a change (as short as possible) and rebase then merge back into master when they are done. This isn't too far off the current way of working and introduces a simple workflow that they can get used to until they feel confident enough to do more complicated operations.

I don't use windows but if Tortoise is basically hiding git from them and pretending that it is SVN then maybe Tortoise is the wrong tool.

Answer 4

Sometimes, what you're doing has to change.

The biggest issue is that everyone is working on master. This is not typical for code development, and could be the wrong model in your case as well. If you can change that, by asking/requiring that changes be done on separate branches, you'll be in much better shape. With branches, you can gain the following:

• Enforce that no pushes directly to master are allowed.
• Enforce through Bitbucket that pull requests are created and have at least one approval prior to merging. This ensures someone is looking at the changes, and also makes the merge itself less painful, as the UI will show conflicts against the remote version of the code, not whatever the user has on the desktop. This prevents the commit-succeeded-but-push-failed scenario.
• Execute "builds" against your repo prior to merging. I realize it's a doc repo, but maybe there's spell-checking, legalese scraping or even automated translation (export STRING_DEF things to a csv file) that could be built off this build. Or maybe not, depends on your work.
• Allow folks to work on multiple different things concurrently more easily. Yes this can be done with stashes as well, but it's a bit messier and something tells me you're not using those either.

If you can't use branching, you might consider writing a merge-and-push script that could automate some of the pain points away. Maybe it would check that the user is not behind on master, do a fetch and pull, and then attempt the merge (possibly with --no-commit --no-ff), and so on.

Answer 5

Emphasize that you can redo merges

It may be obvious to you but former SVN users might not be aware they can try to solve a merge multiple times. This might cut down the number of help flags your receive.

In SVN when working off of trunk you'd have changes uncommitted sitting around. Then you'd do an svn update. At which point your changes would mix with other peoples changes forever. There was no way to undo it (afaik), so you had no choice but to just manually check everything and hope the repo was in a good state. When really you'd be much more comfortable just redoing the merge.

People would have the same mentality even when we moved to git. Leading to a lot of unintentional errors.

Luckily with git there is a way back, specifically because you can make local commits. (I describe later on how this is expressed in the commandline)

Though how this is done will vary based on tooling. I find redoing a pull isn't something exposed in many GUIs as a single button but is probably possible. I like you use cygwin. My co-workers use sourcetree. Since you use BitBucket it would make sense to use that as your GUI since it is managed by the same company : Atlassian. I suspect there's some tighter integration.

Regarding pulls

I think you are right that the merge in pull is whats messing people up. A pull is actually git fetch which retrieves the changes from the server, followed by git merge origin/<branchname>* which merges the remote changes into your local branch. (https://git-scm.com/docs/git-pull)

The upshot is all standard merge commands work with pull. If that merge has conflicts you can abort by git merge --abort. Which should take you back to before your merge. Then you can try again with either git pull or git merge origin/<branchname>.

If you can somehow learn how to do the above using your co-workers' GUI tool of choice I think that'll solve most of your problems. Sorry I can't be more specific.

* I understand that origin is not always the case here.

Use git reflog to diagnose problems

I, like you, have to diagnose problems mostly created by misuse of GUI tools. I find that git reflog can sometimes be helpful as that is a fairly consistent trail of actions on the repository. Though it is hard to read at times.

An alternative

Since your situation is temporary, you could just go back to SVN until you have the process in place to roll out. I'd be hesitant to do this as many places would go on saying 'We tried git once but it just didnt work...' and never really pick it back up.

Some other common transitional problems

• People would often delete and reclone their repo, being convinced their repo was in an unusable state. Usually this was caused by losing track of the local and remote difference. Both GUI tools and the CLI fail at showing this well. In the CLI I find git log --decorate the easiest way to overview the differences. But if things get too hairy on master (for example) you can git reset --hard origin/master

Answer 6

One possible mechanism, that a lot of open source teams have adopted, is to use the forking model - https://www.atlassian.com/git/tutorials/comparing-workflows (be sure to enunciate clearly when discussing a forking git workflow).

In this each developer or sub-team has their own fork of the repository that they check out from BitBucket does provide a mechanism for this, setting an "upstream" origin in addition to the default remote - they will have to remember to "fetch upstream" and "merge remote/upstream/master" on a regular basis.

It will possibly resolve your build mechanism problems as the build tools would possibly be pointed to the master on a different project, i.e. the fork.

You could then remove from most people the ability to push directly to the master project and make that a smaller team of people with review & approve roles. See https://www.atlassian.com/git/tutorials/making-a-pull-request

The place to read up on ensuring that just about any desirable checks are done before pushes is in the git book section on hooks - https://git-scm.com/book/gr/v2/Customizing-Git-Git-Hooks - you can use pre-commit and pre-push hooks to do things like running some tests on the proposed commit to ensure that the work is valid, etc. - the only problem with client side hooks is that developers can disable them or fail to enable them.

Both upstream fetch/merge & hooks are available in TortoiseGit.

Answer 7

This is going to sound counterintuitive, but hear me out:

Encourage them to start experimenting with git

One of the interesting things about git is that it's surprisingly easy to make any local operation completely safe. When I first started using git, one of the things I found myself doing was zipping up the entire directory as a back up in case I screwed something up. I later discovered that this is an enormous kludge and is almost never actually necessary to protect your work, but it has the virtue of being very safe and very simple, even if you don't know what in the heck you're doing and how the command you want to try will turn out. The only thing you have to avoid when you're doing this is push. If you don't push anything, this is a 100% safe way to try out anything you want.

Fear of trying stuff is one of the biggest hindrances to learning git. It gives you so much control over everything that it's kind of daunting. The reality is that you can stick to a few very safe operations for most of your daily use, but finding which commands those are takes some exploring.

By giving them a sense of safety, they'll be far more willing to try to figure out how to do things on their own. And they'll be far more empowered to find a personal work flow on their local machine that works for them. And if not everyone does the same thing locally, that's fine, as long as they adhere to standards with what they push. If it takes zipping up the entire repo before doing an operation to make them feel that way, it's fine; they can pick up on better ways of doing things as they go and as they try stuff. Anything to get yourself to start trying stuff and seeing what it does.

This doesn't mean training is worthless. On the contrary, training can help introduce you to features and patterns and norms. But it isn't a replacement for sitting down and actually doing stuff in your daily work. Neither git nor SVN are things that you can just go to a class and then you know everything about. You have to use them to solve your problems to get familiar with them and which features are well suited for which problems.

Stop discouraging them from learning the ins and outs of git

I mentioned not pushing anything, which actually goes against one of the things you've been teaching them: to always "Commit & Push". I believe you should stop telling them to do this and tell them to start doing the opposite. Git has basically 5 "places" where your changes can be:

• On disk, uncommitted
• Staged but not committed
• In a local commit
• In a local stash
• Remote repositories (Only commits and tags are ever pushed and pulled between different repositories)

Instead of encouraging them to pull and push everything in a single step, encourage them to leverage these 5 different places. Encourage them to:

• Fetch changes before they commit anything.

• Make a decision how to handle the fetched changes. Options are:

  • Commit their local changes, then rebase them on top of the fetched changes.
  • Commit their local changes and then do a merge with the fetched changes.

  • Stash their changes, merge, and then unstash and resolve any conflicts.

    There's other stuff, but I won't get into it here. Note that a pull is literally just a fetch and a merge. It's not like them; it is them. (Passing --rebase changes pull from fetch+merge to fetch+rebase.)

• Stage their changes and then review them.
• Commit their staged changes and then review the commit.
• Push separately.

This will encourage them to check their work before it's made publicly available to everyone, which means they'll catch their mistakes sooner. They'll see the commit and think, "Wait, that's not what I wanted," and unlike in SVN, they can go back and try again before they push.

Once they get used to the idea of understanding where their changes are, then they can start deciding when to skip steps and combine certain operations (when to pull because you already know you want fetch+merge or when to click that Commit & Push option).

This is actually one of the enormous benefits of git over SVN, and git is designed with this usage pattern in mind. SVN, by contrast, assumes a central repository, so it's unsurprising if the tooling for git isn't as optimized for the same workflow. In SVN, if your commit is wrong, your only real recourse is a new commit to undo the mistake.

Doing this will actually naturally lead to the next strategy:

Encourage them to use local branches

Local branches actually ease a lot of the pain points of working on shared files. I can make all the changes I want in my own branch, and it will never affect anyone since I'm not pushing them. Then when the time comes, I can use all of the same merge and rebase strategies, only easier:

• I can rebase my local branch, which makes merging it into master trivial.
• I could use a plain merge (create a new commit) in master to bring my local branch's changes into it.
• I can squash merge my entire local branch into a single commit on master if I think my branch is too much of a mess to salvage.

Using local branches is also a good start to figuring out a systematic branching strategy. It helps your users understand their own branching needs better, so you can choose a strategy based on needs and the team's current understanding/skill level and not just drop in Gitflow because everyone has heard of it.

Summary

In brief, git is not SVN and cannot be treated like it. You need to:

• Eliminate the fear by encouraging safe experimentation.
• Help them understand how git is different so they can see how that changes their normal workflow.
• Help them understand the features available to help them solve their problems more easily.

This will all help you gradually adopt better git usage, until you reach the point where you can start implementing a set of standards.

Specific features

In the immediate term, the following ideas might help.

Rebase

You mentioned rebase and that you don't really understand it in your question. So here's my advice: try out what I just described. Make some changes locally while someone else pushes some changes. Commit your changes locally. Zip up your repository directory as a back up. Fetch the other person's changes. Now try running a rebase command and see what happens to your commits! You can read endless blog posts or receive training about rebase and how you should or shouldn't use it, but none of that is a replacement for seeing it live in action. So try it out.

merge.ff=only

This one is going to be a matter of personal taste, but I'm going to recommend it at least temporarily since you've mentioned you already have trouble with conflict handling. I recommend setting merge.ff to only:

git config --global merge.ff only

"ff" stands for "fast forward." A fast forward merge is when git doesn't need to combine changes from different commits. It just moves the branch's pointer up to a new commit along a straight line in the graph.

What this does in practice is prevent git from ever automatically trying to create merge commits. So if I commit something locally and then pull someone else's changes, instead of trying to create a merge commit (and potentially forcing the user to deal with conflicts), the merge will just fail. In effect, git will have only performed a fetch. When you have no local commits, the merge proceeds normally.

This gives users users a chance to review the different commits before attempting to merge them and forces them to make a decision about how to best handle combining them. I can rebase, go ahead with the merge (using git merge --no-ff to bypass the configuration), or I can even just put off merging my changes for now and handle it later. I think this small speed bump will help your team avoid making the wrong decisions about merges. You can let your team turn it off once they get better at handling merges.

Answer 8

I went through the exact same SVN -> git experience at my company and from my experience, the only remedy is time. Let people get used to the tools, let them make mistakes, show them how to fix them. Your velocity will suffer for a while, and people will lose work, and everyone will be a bit tetchy, but that is the nature of changing something as fundamental as your VCS.

That said, I agree with everyone who is of the opinion that TortoiseGit is a hindrance, rather than a help, so early in the transition period. TortoiseGit is... not a great GUI at the best of times, and by obscuring how git actually works in the name of simplicity, it's also preventing your coworkers from gaining an understanding of core git concepts such as the two-phase commit.

We made the (rather drastic) decision to force devs to use the command-line (git bash or posh-git) for a week, and that worked wonders for comprehension of how git actually operates and how it differs from SVN. It may sound drastic, but I'd suggest you try it simply because it creates that understanding of the git model - and once they have that down, your coworkers can start using whatever GUI facades over git they like.

Final note: there will be some of your coworkers who grok how git works almost immediately, and there will be some who never will. The latter group, you just have to teach the mystical incantations to make their code get from their local machine to the server so that everyone can see it.

Answer 9

Well, recently I adapted the following workflow to never f*ck up the master branch:

1) Everyone uses their own branch, which is intially a copy from the master branch.

Let's name the master branch "master", and my own branch "my_master".

I just made my branch from the master, so it's exactly the same. I start working on a new feature on my own branch, and when it's done I do the following.

Currenly on my branch, just finished coding

git add . && git commit -m "Message" && git push

Go back to the master branch

git checkout master

Pull if it is not up to date

git pull

Go back to my own branch

git checkout my_master

Merge the latest master to my own branch

git merge master

Fix conflicts & merges

Test everything again

When everything is merged & fixed on my own branch, push it

git push

Go back to the master branch

git checkout master

Merge with my branch

git merge my_master

Impossible to have conflicts as they are resolved on your own branch with previous merge

Push master

git push

If everybody follows this, the master branch will be clean.

Answer 10

So we have a team that switched from TFS to git and retained the old ways of thinking. The general rules of operation are more or less the same.

Yes, this means everybody works on master. This isn't that bad; and a team used to TFS or SVN will find this most natural.

General procedures to make this as painless as possible:

1. do git stash && git pull --rebase && git stash pop every morning
2. commit early and often (don't need to push immediately; we can at least start taking this advantage of git early)

3. for pushing do the following loop:

   git add git commit git pull --rebase fix any merges compile git push loop until you don't get the can't fast forward error message.

Answer 11

If everyone is working on master, there's nothing that you can do. Things will inevitably get messed up.

You should use master for completed products that get sent to a customer. You should use development for ongoing development, and you should not allow anyone to push to development. The standard is that everyone branches from dev, makes their changes, pushes them from local to their branch on the server, and issues a push request. Then someone reviews the change and merges it into development.

To avoid conflicts, everyone merges development into their own branch before pushing, and solves conflicts at that stage (so it only affects one developer locally). If merging into development would cause conflicts, then it isn't merged - the developer merges development into their branch again, and pushes to the server again, and then it is reviewed again.

You can use sourcetree for example to make this work without any pain.