Wednesday, July 22, 2020

Git with Delphi: The Basics

I wrote this blog post as I ran into a Delphi coder who was using some non-verson-control tool like Zip or DropBox to store their code.  Now I'm not saying you shouldn't ever store code in zip files or upload code to dropbox, but that should not be your source of truth.  This is a highly opinionated fly through of the basics that a non-git user should be aware of.


What is source control?  Source control means having a single  SOURCE OF TRUTH for what your code is.    Ideally that single source of truth should be on a private or public repository hosted on a git server, like bitbucket, or gitlab.

Why GIT?  There is literally nobody policing this, if you're a solo developer, pick whatever version control system you want, but if you pick anything other than Git, you're going to eventually probably  regret it.   There are network effects (an economics term, really) here. I'm not going to explain network effects. If you have to google that, go ahead.

What is a source of truth?  Git provides a source of truth because all git commits have a "revision hash", a fingerprint that marks them uniquely.  Git provides a way to say, for sure that if you have git commit A939B9.... (more digits omitted), you know exactly what content every single file in your produce source code contained.   In order to be really sure about it you should actually also be using Continuous Integration instead of building things on your developer PC.

What is CI (continuous integration)?   Another reason to use git is so that you can have your code built automatically whenever you change it and have that build happen in a controlled way, in a controlled and repeatable environment so that you actually know what you sent your customers, if you have customers.  If you are working for a company that sells software, and the software binaries you put on customer PCs were built on your own desktop computer, and not on a build server, and your company is more than just one person, you also should be using Git, so you can get ready to be building your software from an automated build (CI) environment.

What are these unit and integration tests things people talk about? You have those right.  If you have Git, and CI, and unit tests, you can be running those things every time your code builds. Are you beginning to see possibilities unfolding like flowers?  If you are a single developer, having CI and unit testing, and continuous unit testing on every git commit, can really help you.

How do I get started? The rest of this post lays out a basic plan for getting started with Git.

Wait I have objections...    Post them in the comments. I prefer subversion is an opinion, not an objection, but feel free to tell me that if you like. 

Step 1.  Sign up for an account on bitbucket.

Step 2. Download Source Tree. (The easiest Git client to learn, not the fastest, or most powerful, and not one you will stay with forever, SourceTree is good at holding new user's hands and getting them some critical early experience with version control, especially if you haven't used version control before and are coming from a background of using Zip or Dropbox to "back up"  your code.)

Step 3.  Create a dummy repository in bitbucket and clone it with source tree.  Follow their tutorials.

Step 4.  Create a delphi application with File -> New Application and commit that source code for the brand new main form right after the first time you save the project and main form and give them the NAME they are going to have for a while.   

Step 5. Using your  git GUI, Add and Commit the files to the local git repository. You have only now been working with your own files on your own hard drive so far.

Step 6. Push your commits up to the repo you created in bitbucket.  Log into the bitbucket website and find the code on your bitbucket account in the repositories page.  

Step 7.  Go to a different computer (if you can) or a different folder on the same computer (if you only have one) and clone the repo to that location.  Observe for yourself that Bitbucket is like a Transporter for Code.  The code on my computer is now code on another person's computer.  Yet another use for Git. Code transporter.  Team coding enabler. Backup system.   Historical log of what your code was over time.  And a thousand other things.  Once you have internalized and understood the value of even 5% of what a good version control tool can do for you, you will never work without one.

Step 8.   Make the application do something.  Fibonacci sequences.  Sorting interview question. Anything.   Once it works, Commit the working code, explain the code you wrote in your commit messages always. Get into good habits to start with so you don't have to learn the hard way.  Now mess the code up on purpose. Now using your Git Client (SourceTree or others) find the change and DO NOT COMMIT it, instead revert it. You have now observed another use for Git.  The Time Machine.  Any time you move your code in a way that makes it worse, you can just revert the change before you commit it.     

Step 9.   Make a bad change and commit it even though you know you just broke your app. Now find the way to revert a commit (get your code back to the way it was before the bad commit).   I'm not going to tell you what the command is called, because I want you to figure it out for yourself.   So git can not only be a time machine BEFORE BAD COMMITS it can also be a time machine to get you back code after bad commits.

Step 10. Now learn about .gitignore.  Do this before you import any real projects into git.  Find out what .gitignore is and how to write expressions into it like *.dcu and *.local.   Do not commit binaries (exes, dcus, dcps, bpls) into Git, unless you really really have to.  In general, you should NEVER EVER commit a DCU for a .PAS file that is in the repo as you should be BUILDING that .DCU file from source.  If your projects are badly configured (DCU Output folder is NOT set) then get used to setting the DCU Output folder option in Delphi to a sensible default for all your projects. Mine is .\dcu\$(Platform)\$(Config)   so that I can have win32, win64, and even other non windows platforms all build and not have my dcus get mixed up.     .gitignore is the place to code these dcu and exe output folders in so that when you add your source code into a git repo you do not commit the exes.   If you really really want to store your ssl dlls in git, nobody is going to come and arrest you, but please for the love of the flying spaghetti monster, learn what .gitignore is and use it. Don't commit DCUs. Sermon endeth.

Step 11. After you understand git ignore then take your source code folder and do a git init there, from source tree.  Add things in small chunks. Not 10K files in one commit. Add one top level folder that contains less than 50-80 megabytes of content, at a time, if you can.  Trust me you'll be glad you did this, if you have a 1 gigabyte project, please do not add 1 gigabyte of files in a single commit.  After each commit, add more files until your repo is built.   If you were previously using mercurial or subversion there are tools to keep your subversion and mercurial history and convert over to git.  I'm not going to cover them but I know they exist and that they work as I've used a variety of them.  I generally don't bother. I just start over with new history in git, and I go back and look at the old version control systems to see old versions.

Step 12.  Get used to comitting all your code after you write it and writing GOOD COMMIT MESSAGES. A good commit message is a message that explains the purpose of your changes.   If you are lazy here, your future self will hate you. You don't need that kind of rejection in your life. WRITE GOOD COMMIT MESSAGES NOW.

Step 13. Push after every commit until you have made it a habit.

Step 14. Delay using and learning about submodules, branching, tagging, and other topics in Git until everything I have said above is well ingrained and is part of your habits.  Learn to use Diff tools, learn to merge, before you learn to branch.     Imagine you learn to drive a car but you concentrated on learning how to drive fast before you're very good at steering and braking.     Steering and braking are the ways you stay out of trouble.  Merging, and diffing are ways to get out of trouble. Submodules, and branching are ways to get into it.  Until you have the tools to sort yourself, just don't make the crazy advanced messes. Don't try to deploy and manage a Gitlab instance at cluster scale when you don't even know how to Diff two files, compare them, and solve merge conflicts.

I believe the above will be helpful as I've written it, but I reserve the right to amend the advice above if anyone can point out ways in which the above might lead a new Git user astray. The happy path, of a contented Git user, is a gradual growth in competence with a powerful tool.

Can git be frustrating? Yes. Is it complicated?  Yes.  Is it worth it to learn it? Also Yes.

Are most of us going to do things wrong, and learn everything the hard way? Yes, because you are human. It's okay. 


  1. Source Tree the fastest GUI? I would like to disagree - it became a slow as a slug in the past years. If you want a nice and clean GUI then try out Fork (

    1. "The easiest and fastest GUI you can learn".

      It is not the fastest GUI in operation, it's the one with the least accidental complexity and crazed featuritis.

    2. I updated the article to say

      Download Source Tree. (The easiest Git client to learn, not the fastest, or most powerful, and not one you will stay with forever, SourceTree is good at holding new user's hands and getting them some critical early experience with version control, especially if you haven't used version control before and are coming from a background of using Zip or Dropbox to "back up" your code.)

    3. Please try out Fork and let me know if you still have that opinion. I used to be a Sourcetree (one word by the way) fanboy but when I saw Fork I did not look back a single time (well, not true, one time to copy over my custom actions into Fork)

    4. I am not a SourceTree fanboy. I'm a pragmatist. If Fork is better, use it!

  2. I wish (and have begged for years to Embarcadero) for RAD Studio to have a good functional way to use GitHub inside the IDE (like Visual Studio has since the 2015 version).

    1. Why continue to recommend GitHub? I don't even recommend it. I recommend GitLab, Bitbucket, and anything that is not GitHub.

    2. "GitHub? I don't even recommend it."


    3. My employer use Github for private repos. I assume we choose it because it was largest. Didn't compared the alternatives so much. But curious why others are better that Github ?

    4. I once had to make the decision where to put my code when Google Code (anyone remember?) was about to be shut down.

      The choice was basically Bitbucket or GitHub - GitHub at that time did not offer private repos for free, Bitbucket did (limited users though). But over the years as so many things Atlassian took a very strange course with their products (and not only the two free ones I am complaining about here).

      If I nowadays would have to make the decision it would be GitHub or GitLab - GitHub now offers free private repos and overly has improved - their bugtracker runs circles around what Bitbucket offers. GitLab on the other hand has a way nicer CI - especially when you want to build Delphi which cannot be simply put on some cloud service. And we use it at work which gives me a bit of knowledge about it.

    5. I highly recommend GitLab. My concern with GitHub is that Git was supposed to be a decentralized version control system, so giving GitHub a virtual monopoly is harmful to the overall software world. In fact, in many ways the fact that Git itself is now the standard, is also harmful, but that ship has already sailed.

      At least, Git is decentralized. There should be more than one place on the internet where code lives, and putting all the code of the whole world in github is problematic.

      Secondly, many organizations will want their code to live behind a firewall, and not on the public internet. For them, a self hosted Gitlab CE instance is ideal, if they have the IT capability.

      Gitlab's Continuous Integration system, and it's massive broad and tightly integrated feature set make it a true Github killer.

  3. I set up Gitlab for one of my employers. They have a disaster recovery plan, and an IT squad capable of executing on one. And they desired to have their code stay off the big scary internet. An exploit that got at Github private repos or Bitbucket private repos is not beyond the realm of possibility.

    With Gitlab, your future is in your own hands. Read that twice. If you suck at backup and disaster recovery planning, Gitlab self-hosted is not your baby. Gitlab hosted for you by a competent organization, or pay Gitlab themselves to host yours, is your baby.