Leveraging Git and Github

This is one in a series of guides discussing software tools and their use in
Lever projects. Working through this guide will provide a basic understanding
of git and GitHub as well as a start on the use of VSCODE with Lever.

1. Introduction.

git is a developer's tool that can be used to manage the source code
for your projects. It provides a way to experiment with changes to
the code and to track changes once they're finalized.

git is designed to be multi-user. It allows different developers
to work on the same project at the same time without getting in
each other's way. Developers can contribute fixes to the codebase
in general or focus on maintaining different branches, or versions,
of the code.

git is one of several competing tools known as Version
Control Systems. This particular tool was created by Linus
Torvalds, the original developer of Linux. To read more about
Version Control Systems,
click here.

git can be used as a stand-alone tool on one developer's PC or
as a collaborative tool. In the latter case, a codebase lives on
a server, which may be a private machine that belongs to a venture
or a public git web service.

If you'd like simply to share your source code for others to use, it's
easy to create a source tarball and link to it. However, if the goal
is to open your project up to collaborative development, presently,
git web services are one of the best approaches.

Typically, git web services are free, up to a point, but charge for
extra features. There are several services of this type. The best one
is generally considered to be GitHub. GitHub is located online
at the following link:

2. Prerequisite.

If you read through the
getting started with vscode -guide
You created a hello-world folder. Open that folder with the 'File' -menu.
If someone has deleted that directory, it's okay. Just create a new directory
and put something there. But open a directory anyway, it will become a git
repository in this guide.

In the left tab you've got this diamond shaped symbol, when you press it
tells you 'git' is not installed.

3. Install Git for Windows.

The next step is to install Git for Windows, if you don't already
have it.

If you click at the 'git-scm.com' -link, it starts to download git. Let
it finish and run the installer. Then step through until you hit a following
dialog.

Earlier dialogs have lot of options, they seem to be right from the
start, and it's okay for you to change them if you know something about what
each means. One thing is that you probably want to keep the "Git Bash Here"
and "Git GUI Here" installed. They are both very useful.

In this dialog you are best off by checking 'Checkout as-is, commit
as-is' here.

There are lot of programming terms such as 'checkout' or 'commit' here.
So, it may look a bit chaotic.

3.1. Line endings: Some history.

This part is optional.

The line-ending issue is historical. To read more about it,
click here.

In short, many early computers fed text directly from the memory to a
teletype printer head that printed characters to paper. CR is a control
character that made the print head to switch to a new line.

Because the print head was not fast enough, it did not manage to finish
the operation in time and you would often see the next letter get printed to
a middle of page. To avoid this, text files ended up with CR+LF sequence,
with the LF doing nothing. This gave the print head enough time to
return.

Hardware drivers eventually ended up to abstract away the details, and
computers were free to use a single character as newline. Unix adopted the
LF as a newline, while Windows kept using CR+LF as a newline.

The problem here is that Git is very sensitive for line feed
characters. If the line feed convention changes along the way, it renders
the Git diff useless. There are some places where you still see CR+LF used,
but they appear in protocols and such, not in text files. The standard we use
with Lever files is to just use LF everywhere.

3.2. Line endings: What to choose.

We recommend 'Checkout as-is' because this
means you get a repository directory that is safe to move from a computer to
an another without committing it through Git. You have an editor, that if
you put like I proposed is configured to use LF everywhere. Also the VSCode
doesn't force the file encoding so you shouldn't have problem with editing
text files using any of the above settings.

Once you have a git installed, you can create a git repository in
VSCode!

I assume that the flow is as follows:
You install Git for Windows, the hello-world project is added
to git, you create a repo on the GitHub side, and then you make
changes and commit. Is it something like this? Make the flow
clearer to the casual reader.

If Git Bash is part of this, should probably add a paragraph or
two explaining more about what it is and linking to a Git Bash
tutorial.

There are images further down that need more context. The casual
reader will like to understand what is going on, not just execute
steps exactly.

Now you have a git repository and the git tab is active. It's showing up
the changes that haven't been committed to the repository.

Git created a directory for you that has a history. Every git directory
has a history that is stored in '.git' -folder. It is possible to checkout a
from any point in this history and see how the directory looked back then.
For example, here's the directory tree of
a first commit to lever repository. It looked like
that in October 29, 2014!

This is very useful feature for managing your projects.

The chances are transferred into history in stagings, multiple files at
once. Every stage gets a message that should tell what was done.

Lets make the first commit. There is very clear plus -sign that appears next to
a file in that list. Press it to stage a file.

The staged changes appear into their separate list. We leave the main.lc.cb
away because that's a binary file that Lever compiles from main.lc before it
runs it.

To commit something you need a message, but this is the very first commit so
we can give it a message 'initial commit'.

BOINK! Git hits you to the head! You lose 5 sanity points!!

To avoid this, open the GIT Bash to get this kind of very discomforting
black screen you've probably seen in hacking movies. Type the commands such
as in the screenshot, but replace 'cheery' with user name of your own, and
the email address with your own. These lines tag and identify the code you
wrote.

I'm not sure, but the name perhaps must be the same you use with your
upcoming github account. You can change it later with this very same way.

Now you should be able to commit!

Generally you do not want to commit everything into your repository,
you absolutely do not want to commit things other people shouldn't see such
as your passwords or customized server configs. You also don't want to
commit most binaries or files that get generated when you run your program.

If you've run a program with lever, you got one right there named
'main.lc.cb'. To ignore all files with lever bytecode file extension, add
the following line '*.lc.cb' to new file '.gitignore'

I also made '.vscodeignore', because I thought it would ignore files in
vscode -view. Turns out I was wrong.

Prefer to describe what you do in the commit message. It is common to see very
bad commit messages and it is understandable because naming can be hard. But you
will get better every time you try. Eventually it will become your second nature
to write meaningful commit messages.

When something becomes useless later on, you can delete it from the tree
and stage a commit to delete it.

Notice that this does not delete a file from the history.
So if you commit a file you should have not commit, often the easiest way to
truly remove it is to destroy the whole repository. There are some gentler, but
very much more challenging ways to remove files. Best way to avoid this is
to not do that error in the first place.

If you can invalidate the information the file contains, it's usually
better way than to change a git repository.

If the file isn't very dangerous, the best way is to let it stay in the
history. It's the job of git to handle the history. Let it do its job.

So.. We gits have a hub these days. We call it Github!

The following sequences shows out how to create a public repository where
you can push changes from your local repository.

There's a very little button in the upper right corner of the site...

...And it opens up like this. The best results are gained by names that tell something
important about your work. For example 'nike' is a goddess of victory. A fine
name for sports clothing. Do the same trick and you'll be walking along the titans.

Remember to keep the next page open.

So there's no much use of this if you can't push your changes from your
repository to the github repository. To use the above lines you need to open
a Git Bash to your repository.

If github is new SSH destination to you, you see this kind of
message. Just type 'yes' as answer and press return.

BOINK! Github hits you to the head! Well no. Actually it just denies your
access to the repository because it cannot know it is yours. You need to
authenticate.

Public-key authentification.. Safer than any other authentification
method as long as people do not snuff or see your private key. If it's not
your personal computer that is safe from snoopys, remember to invalidate
the key at github's end afterwards.

The program prints out fancy things such as a fingerprint and ASCII art.
They aren't very interesting. Check out the path it points out. Open the
whole directory in your VSCode.

The 'id_rsa' is a private key. People who have this key can identify as
you. And you can identify as someone whose key you have.

The 'known_hosts' probably contain the github now because you said
'yes' to an important question. It's OK. Just good to know where those
things go.

The 'id_rsa.pub' is your public key. Copy it from your file!

Go to https://github.com/settings/keys
in your browser and press 'New SSH Key', paste your public key and name it
something that identifies the computer you have. I put 'esa computer' there
because I am on his computer. Notice the button 'Delete' - that lets you
invalidate your key any time.

Next when you try the same thing as again, it lets you do it. Below you
see the outcome.

After a while also your VSCode recognizes this. You can notice you will
be able to 'Sync', 'Pull' and 'Push' from the menu aside the 'do a barrel
roll!' -button.

I made a commit on the github website so I could pull. You see the '1'
and a downarrow in the status bar aside the words 'master'. This means that
you're in a master branch, and the 'remote' or github repository is 1 commit
ahead of yours master branch.

Doing the pull changes the markings, like this.

So, is this worth all the effort? Might be the first thing you ask when
you get accomodated to version control of any kind. I use it because it
enables incredibly rapid collaboration and allows everyone to grab a
development version and contribute.

I have no brightest idea how it could benefit you. But you would be able
of writing guides such as this, or sample programs. Or then improve and
document the existing sample programs and guides using git & github.

Also it's weird but knowing how to use git&github allows you to
contribute to lots of things.
For example there's this guy who
wrote a kernel. Say you wanted to contribute to such projects somehow,
maybe fix something there for yourself. You could press the 'fork' button to
get a clone of this repository to github where you can commit your own
changes. Then you could make a 'new pull request' to the original maintainer
and he can decide whether to pull your changes or not.

If he doesn't like your changes and rejects them, you could keep your
fork and still use it yourself, as long as you follow the license rules.
It's even optional to keep it in sync with the mainline and update it from
time to time, though you may want to stay updated for your sake if you fork
a kernel.

If want to write closed source code, you could ignore github or then use
their private repositories -feature that costs a little bit. Overall using
git is still useful even if you didn't intend to put anything online.

There's lot ways to operate on git repositories using Git Bash. But
they're out scope of what I should teach to you. This is here because I
think it's something every programmer should know how to do.

The guide coming after this one will explain how to compile Lever on
windows 10. It's something skilled programmers want to do, because Lever can
miss a feature or two they want, even if that feature was otherwise trivial
to implement.