Learning Git (and GitHub) so we can contribute to openHAB

Development
, ,
1

We got into this subject in another thread, which I started out to reply in. But then my answer got a little long and I thought (hoped) this topic might spur additional discussion, so I decided to create a new thread. Also, I know it’s not directly related to openHAB but I feel it is tangentially related, so I hope the mods will indulge me. My hope is to increase understanding of Git (always a complicated topic) and thereby potentially “teach people how to fish” so to speak which will (hopefully) eventually increase participation and contributions.

TL; DR

Read the Pro Git book which is available free online (as in freedom, check the license). Although I encourage you to read on, as I plan to tell some tales (true ones!) and have a bit of fun along the way… :smiley:

And so on with it

I was just about to ask, because if that’s the case then you probably don’t realize that those are even 3 different things. So that’s probably a good place to start.

Well, grab a cold beverage and pull up a chair. :wink:

Because Git (not unlike openHAB) is a pretty powerful tool, and like most powerful tools there will be some learning curve. However the payoff, IMO, is worth it.

I would also like to state at the outset that I am but a low level wizard myself, and I was able to figure it out, so you can too. But like all wizard skills, it does require spending some time at the podium(s) of the scrolls of ancient wisdom. :smiley:

Git

I think probably the hardest (conceptually) to get your head around is the underlying tool Git itself. But once you get that, everything else should fall into place.

First, a bit of History

None other than Linus Torvalds himself wrote Git because the version control (VC) software they were using at the time wasn’t cutting the mustard in developing the Linux kernel. So he wrote a new one from scratch in like 3 days(!). And it is an amazing piece of software, once you realize what it does. Because it is distributed version control. That means, that a whole bunch of different people, all over the world, can simultaneously work on a project together, and then merge all their changes back together into one. In fact, without Git I don’t think it is an exaggeration to say that Linux would probably never have become what it is today. It allowed first hundreds (and by now thousands) of hackers geographically dispersed all over the whole world to collaboratively work on a software project together. Well, that plus the Internet. But I digress… :smiley:

I do think it is valuable however to understand the history, why something was created. The Wikipedia article on Git (that I linked to above) goes into some of those reasons, so I won’t duplicate that here. But I found it all quite fascinating. In fact there are a couple nice documentaries (available free online) that explain how all of this came to be, I could dig up the links if anyone is interested.

Hopefully understanding some of that background will whet your appetite to learn more. I know it did for me. Plus hearing about Git all the time. Well actually GitHub, where so many of these wonderful F/LOSS projects are hosted. It was only after researching that led me to the underlying Git.

Anyway, once I got to this point, I think the greatest help to me was reading the Pro Git book, which is available online and for free. It really explains the underlying concepts of Git and version control, and was the main way that I learned it.

Alongside reading the book, I did the exercises on a GNU/Linux machine which makes it very easy to learn (just sudo apt install git). If you are on Windows I am not sure what to tell you (switch to Linux :smiley: ). Another tip: there are all these tools and GUIs that are supposed to make it “easier” but IMO all they do is obscure the underlying command line, which are really simple and easy actually (once you begin to get your head around the underlying concepts in the book).

Finally, I will just state again that Git is a very powerful tool. And that I am by no means an expert. I probably only understand maybe 5-10% of it. But that is enough to use it. The basic commands that you will use all the time are only a few:

git commit
git pull
git push
git clone
git merge

etc…
There are tons more of course but those are for much higher level wizards that use it every day. You do not need almost any of those advanced commands in every day practice.

GitHub

Just understand that GitHub is a website that hosts Git instances (called Repositories) along with some other nicely related features like forums, bug trackers, etc. for free (community projects) or paid (businesses / with support contract, etc.). But you don’t have to use GitHub to use Git. For example, for your own personal stuff that you don’t want to share with the world. I think not enough people understand this. If you are already running GNU/Linux on some Single Board Computer (as many of us are with openHAB already) then you can self host your own repositories. Which is super neat and is what I do for lots of (text based) things like my own personal/private text based accounting (using Beancount) data, Orgmode notes, dot files, etc…

Once you understand the command line Git tools, structure of repositories, etc. it will become immediately apparent their GitHub counterparts.

And finally there is…

openHAB GitHub Policies

Most projects (including openHAB) have a particular workflow, coding style, etc. In the case of openHAB, a stepping stone into these guidelines can be found here.

And Finally, to actually Answer Your Question

I guess I cannot directly answer a step by step, because without the underlying knowledge of each of the above big moving parts, and how they work together, I don’t think you will be successful in using them. Because at the intersection of multiple complicated tools, there is no “one size fits all” answer. And this way you will be much better prepared to contribute to other projects in the future also.

But I have faith in someone who has successfully integrated openHAB to be able to get their head around it. You do have to take a step back though and eat the elephant one bite at a time so to speak. Don’t try and do it when you are in a hurry or need to contribute something “right now.” Or when the wife and kids are nagging you. Take a separate day (or few days, right now over holiday break is a perfect time) and grab a cold tasty delicious (adult?) beverage of your choosing, sit down at your favorite computer area, open the Git Pro book in one window and a terminal in the other, and start learning the basics.

I will back up actually. If I recall correctly, I think I had to take a couple (few?) different stabs at reading the book before the concepts started to sink in. Only then (when things started to “gel”) did I get all excited about it and it was then that I sat down at the terminal and everything has just flowed from there ever since. :smiley:

Let me know if you (or anyone else) have any particular sticking points, conceptually or otherwise, and I will be happy to try and help, just as I have received so much help through these very forums.

4 Likes
2

To summarize git in very simple terms. There are 2 concepts. First. A branch which is a stack of changes. Each entry (a commit in git) on the stack describes the differences with the previous entry on the stack. Second. The distributed part is in the work you need to do in synchronizing those stacks (branches). It can be a local branch or a remote branch, for example on GitHub. The complexity is in the large amount of features git provides to manage and synchronize those branches in almost any way possible.

2 Likes
3

In addition to what hilbrand said, JimT (in another thread) was able to come up with the short answer that I couldn’t seem to manage:

Of course I still think it helps tremendously to read the book and understand the concepts first. But there you go.

4

I did not understand anything of what follows…

1 Like
5

@vzorglub,

I don’t know if you had any time yet to look into anything I posted, but I was curious about how you might be getting on? :slight_smile:

Another thought occurred to me. I actually keep my openHAB text config files (amongst many other things) under version control in Git (instead of sharing the folder over the network as is recommended by openHAB). I mean I see why they recommended that as it’s “easier” but I really don’t like the idea of sharing priveledged user /etc/* folders over the network, even if it is my own local network…

Anyway, my idea was, maybe I could write up a brief walkthrough of the (really it’s only a few) steps one would need to do to set this up and then what commands you do and when in the course of managing your config files in this way. I think that would be illustrative.

Let me know if there is any interest and I’ll try and make the time.

6

Not yet

Yes please

7

OK, I need to take a break and eat and stuff, but I’ll try and get something together later. I really do think a nice simple example like that will be illustrative.

I still highly recommend perusing the Git book though, at least the first few chapters, as that is all you will need to get your head around the basic concepts (which are admittedly weird, at first).

But think of like editing your config or text files or some source code over and over and saving them file1 file2 file3 etc. Well, Git is basically the solution to that. Except with a whole lot more features. :wink:

1 Like