Hello again--this post isn't about audio, hardware, MPUs, soldering, DACs, or even electronics tools like EDA's and scopes.
 |
| Why the kitten with the octopus tentacle? |
Intro: WHY USE A VCS?
Even a small potatoes software developer like me needs version control.
Back when dinosaurs roamed the earth I wasted a lot of time screwing up (a.k.a "disimproving") working code, then, after laying the working code to waste, spending hours cursing and hating life while I got the code "got back to square one".
Did I save a copy first? Nope.
And! I still have major headaches at my day job when a contracted programmer takes working code and breaks it.
Now users are crying.
"Do a damn git reset!" I tell the programmer's boss, a big shot compsci contractor CTO with a Posh PhD.
"We don't use VCS's" the CTO says.
Righto--what's the red wire for again?
Enough!
I have been a big advocate of VCS since I was introduced to version control (
Gnu CVS).
Nowadays I use
Git, but don't set it up often enough to remember the anything beyond the basics--that's
why we use AI, oops I mean, that's why we write things down.
So! If you are a beginning programmer and want to learn a bit more about this free VCS--"
version control system"--Git is the most popular VCS nowadays--this content might be of interest.
If you know GIT better than I do--which is likely--I only know and use maybe 5% (?) of its commands--you're probably going to want to skip this one.
EVEN BETTER: if you are an experienced Git geek, please read this post; where you find it oversimplified, misleading, or downright butt, please comment so I can correct things and better learn GIT.
WHEN U ASSUME?
Assumptions:
- Your development computer has GIT installed--here.
- You have some previous experience with version control software or at least knows what it's used for/why it's important.
- You are not a CTO who drives a Range Rover and lights cigars with $100 bills yet doesn't know red is positive.
- You have a user identity already set up on Github (mine is "cslammy"; yours isn't)--if not, get one! New user creation is well documented--go here.
- You use SSH to securely communicate between your dev system(s) and Github--there are other ways to do this, but I know SSH pretty well so it's what I am use and what's covered in this post.
FIRST STEPS: SETTING UP SSH
============CREATING PASSWORDLESS SSH===========
On your development PC(s) install
OPENSSL if needed.
For UBUNTU desktop (22.04), openssl was already installed; nothing to do. If not? different distros have different installation steps. As a Ubuntu/Debian/Mint guy, for me it would be something like
this.
For Windows: get
cygwin64, install using defaults, and add C:\cygwin64\bin to %PATH%. This will allow opensll (needed for keygen) to run from Windows command line (cmd). Step by step instructions for this are
here.
===========SSH PRIVATE AND PUBLIC KEYS===========
For a machine to talk to github using SSH you have to create SSH keys, store the private key locally, and upload the public key to github; more
here.
The following command creates a public/private key pair in ~/.ssh on linux; the same command works for cygwin Windows:
ssh-keygen -t ed25519 -C [github assigned email address]
so for me:
ssh-keygen -t ed25519 -C cslammy@github.com
#note:
why "cslammy@github.com"? Why not the gmail email address I associated with my github.com account when I first created an account?
It's the way Github works: each user gets a github.com email address when they join github.
This Github assigned email is used for SSH key management; you use git@github.com in the git CLI for ssh remote, but you use your personal email address (e.g.: foobar42@gmail.com) for other github related things, like getting informational emails from the github community.
These 3 different logins/identities confused me at first....it made more sense after I used git and github for awhile. Like it or not, you will need all 3.
========POTENTIAL LINUX GOTCHA?=========
Check that the generated keys are copied to ~/.ssh by default.
On one of my ubuntu hosts I saw that the keys were not stored in ~/.ssh directory.
or maybe I didn't choose to save to default location?
As far as I can tell, the keys (at least private?) need to be in ~/.ssh or SSH to github will not work!!
If they are not there:
- Figure out where the keys got stored (maybe in your home directory?)
- Note existing CHMOD's/CHOWN's for private and public keys
- Copy keys to ~/.ssh directory
- If needed, CHMOD and CHOWN copied files/folders to match originals.
===========UPLOAD PUBLIC KEYS TO GITHUB===========
On the dev system's ~/.ssh folder that has the private key there will be a
public key; its filename ends in .pub.
- Cat the .pub file or in Windows open it in Notepad.
- Copy the .pub text content without any spaces, extra lines, etc. to your clipboard.
The public key will look something like what you see below, which is an example, not a real public key:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAFBAAIFo+Zumzwrm/DsmDqJCZLJQQmr4CA5Qhgb2TyxI1gtqX cslammy@github.com
Then:
- Go to github.com, log in
- Click on your profile icon in the top right of the main page.
- Go to settings > ssh and gpg keys > ssh tab
- Upload the SSH public key text to github (more here).
NOTE: as far as I can tell, the public keys uploaded to github don't stick around forever. You may need to re-upload your public keys from time to time.
============ADD GITHUB TO KNOWN HOSTS============
I have only seen this on Linux, and only occasionally,
ssh-keyscan github.com >> ~/.ssh/known_hosts #Not sure this was needed
Did it work?
➜ .ssh more config
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_rsa
Was/is this is step needed? Probably not.
=========TEST WITH SSH===========
From a system that has the required private key etc.
ssh -T git@github.com
Note you use git@github.com as username/domain, NOT your git username (for me, cslammy....)
(or)
ssh -Tv git@github.com #includes verbose debug info.
If if works, you should see something like this:
Hi cslammy! You've successfully authenticated, but GitHub does not provide shell access.
NOTE: Again, you must use git@github.com<mailto:git@github.com> when testing SSH protocol to github. Not some other username. Not clear from most docs I read when trying to learn GIT.
SETTING UP THE REST
=========GIT CONFIG ON YOUR PC=========
Git has a lot of options you can configure on your dev PC.
One is to make sure to set: that the default Git
branch is “main” locally. That will match github.com’s default.
You have to change this for at least some Linux distros--local default branch for Ubuntu git for me last time i set up git/Github was “master” which did not match the Github default.
On linux or Windows, from terminal:
git config --global init.defaultBranch main
From:
There are other things to set up.For instance, you may need to set how carriage returns are handled--different for Windows OS vs. Linux....details
here.
There are a lot more things you can set--at a minimum for each dev PC I set the features
here; kitchen sink details are
here.
========GET THE URL OF THE NEW REPO==========
Create new github repository at the public github website (how-to is
here).
**DO NOT ADD ANY CONTENT YET**
- There is a green button called CODE in the new repository
- There is choice for what to display: SSH or HTML.
- click on SSH
- You will see a URL looking string to use for SSH to this new repro; here is an example.
git@github.com:cslammy/AD9833VCO.git
Copy this to clipboard, add it to notepad, save it using textpad, whatever.
You will need this again shortly.
==========LOCAL DIR AND GIT INIT=======
Create new directory on local Linux or windiows machine for the new project.
(or)
CD to an existing directory where you already have some code.
issue this command:
git init
This creates .gitignore, DB files etc, for any data in the directory.
============SETTING UP PUSHES AND PULLS==========
Ah! Now we are getting somewhere....
Now that we have the above steps done, we can start using version control for code and copy code changes to github. That way the data is in two places--always a good thing.
To do pushes and pulls git uses commands like this:
git push [variable] [branch]
git pull [variable] [branch]
But before any of that works, in addition to having SSH set up (above) you have to set things up so git knows the values of [variable] and [branch]
First, think of a variable name, a common one in our situation is "origin"
Make sure your variable isn't already set. If it is, you want to get rid of it.
DANGER! Failing to do this can lead to all sorts of problems.
open terminal and CD to your project's directory. Then run this.
git remote -v
if you already see an "origin main" pointing to a different repo, you need to get rid of it (or choose another variable).
git remote rm origin
Then, set a git variable to the remote repo. In my case I usually call it “origin” again. I have no idea why.
Here is an example:
git remote add origin git@github.com:cslammy/AD9833VCO.git
[Branch] is the info you wrote down or copied into clipboard or notepad....will look something like this:
git@github.com:cslammy/AD9833VCO.git
AD9833VCO.git is the name of a repo folder you want to push to.
.
=====EDIT YOUR .GITIGNORE FILE ==========
.gitignore basics are
here.
.Gitignore is a text file that tells Git what files and folders you don't want to version control.
You will probably want to modify .gitignore for each project you version control--otherwise a whole buncha crap of you don't want to replicate will replicate (such as a "build" folder and all its contents, created by cmake). Doh!
A pretty typical .gitignore file for me, for VSCODE/CMAKE coding, that seems to work, has only 3 lines:
Deprecated
deprecated
build
docs
Deprecated is where I put anything no longer salient to the project; docs are things like PDFs of IC's used. Whatever. Up to you.
======README AND LICENSE=========
Then:
=====DO AN INITIAL PUSH OF FILES FROM GITHUB TO LOCAL====
Assuming I already have some code in my project folder, I do a git push first.
Git needs to know about your work so far...git status says what needs to get uploaded; git add . adds everything except gitignore files and folders to the queue, and git commit gets everything packed up and ready to go:
cd to your project directory if you aren't already there, then:
git status
git add .
git commit -m "initial upload"
Then, use this to push files for the first time to github.
git push -f origin main
After successful push you will see your local files in your new repo online.
And...if it worked, you will see something like this:
git:(main) git push origin main
Warning: Permanently added the ECDSA host key for IP address 'x.x.x.x' to the list of known hosts.
Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (13/13), 6.52 KiB | 667.00 KiB/s, done.
Total 13 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), done.
To github.com:cslammy/SYNTH.git
You now have version control working and your precious code in more than one storage repo.
SUCCESS!
========ESSENTIAL COMMANDS FOR VERSIONING=======
Once your git/Github setup works you can use the gazillion other commands (reference is
here) to pay off your Range Rover.
Obviously I won't go into all of it here--just the basics, ma'am.
A good command to see what changes you have made since the last commit:
git diff
OK, you've made some code changes, now you want to get save your changes as a new version.
git status
git add .
git commit –m “added foobar function to main.c”
If you just say
git commit
your commit notes will be editable in your text editor--which you can configure using git config, how to do this is
here.
Finally push the changes up to the cloud:
git push origin main
======GOING BACK TO PREVIOUS SAVED VERSIONS=====
git log
this shows the messages you tagged to each commit and its commit ID
Once you have locked in on the ID you want to roll back to, here is the command to roll things back.
git reset --hard 0ad5a7a69ab9240da
=====DIFF CURRENT CODE AND LAST COMMIT===========
I use this all the time, useful not just for version control but to see your last bread crumb trail
git diff
OUTTRO
Wow already a long post, and this post only covers the very basics.
Git can get pretty complex--there are tons of commands--but try not to let that get you down, the basics aren't that difficult.
I will be adding to/correcting/updating this post as time goes on and I have git projects in front of me.
I am revising code for a RP2040 clock multiplier, that will have a fair amount of embedded C and need a gitload of work.
Will it work? Who knows? Hopefully more about that project in the next few posts.
