View source for Git and github stuff

I use Git and GitHub to version manage all software I write and maintain. I started using it with IDEs, like PyCharm and Android Studio, with support for Git built in, so I didn't really have to learn what was under the hood. Now using it with the Arduino IDE, I need to know enough to more directly use it. In addition, GitHub deprecating username/password authentication kind of forced me to dig into it some.

==Git Basics==

First of all, I use Git on Windows, so I am running [https://gitforwindows.org/ Git for Windows.] This includes the base Git software, which is available from the command line, Git Bash, which is an alternative Unix command line, Git Command, which is just an alternative Windows CMD window, and Git GUI, which is a graphical interface for Git. After trying GitHub Desktop and Tortoise Git, which are pretty decent GUIs, but have problems with authentication, I have settled on stuff directly from Git, which is a little clunky, but seems to always work.

To create and work on a local Git repository, you need to set the working directly to the directory that contains the code. E.G. for my current Arduino code, this is in C:\development\arduino\ejbfleet-v1\ The Git directory, .git is in there along with the source files. 

===Git Functions I Use All The Time===

'''Git clone'''

Clones a repository, either local or remote (generally on GitHub.) I use this to copy up to date code to a machine where I want to work on it. For me, I generally start a coding project on ejbdesk or ejblap, and eventually have occasion to work on it on the other machine, and possible on my shop machine, ejbshop.

'''Git add .'''

In the gui, this is '''Stage Changed'''. Not sure why they use a different name, add vs stage, but so be it. This sets up all changed files to be committed to the repository. Git add <filename> or Git add <directory name> will stage specific things to commit.

'''Git commit'''

This commits staged files to the repository, i.e. marks them as changed and takes a snapshot of the changes. It is also customary for the person who does the commit to add commentary about what has changed, the state of the project, etc.

'''Git push'''

This sends the repository to a remote repository (GitHub for me.) What it is really doing is sending the changes, so we can keep track of them. If the GitHub repository is now cloned, the whole history will come with it.

'''Git fetch'''

This fetches the necessary information (metadata) to update it to the remote version. It does not change the files in the local repository. That is done with the "merge" command, which merges the changes into the local copy. It is actually more complicated than that when there are multiple branches in the repository. more formally, git fetch pulls in the latest remote commits, which may come from multiple developers, and then git merge combines all of the changes from those commits.

'''Git merge'''

After a fetch pulls in all of the latest commits from the remote repository, the git merge command executes the changes in those commits to a destination branch. This can get complicated, and I don't understand it beyond the basics, but since I am not doing complicated stuff, and usually only work on one branch, git merge for me just applies the commits I have made in the remote repository since the last time I committed from the local machine, effectively just pulling in the most recent version. The git pull command, included in some git interfaces, seems to effectively do a fetch followed by a merge.

=='''GitHub Authorization'''==
GitHub has deprecated the username/password method of authenticating a login as described [https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ here.] In its place, the thing that I found made the most sense for me was to add a SSH key to each of my computers and put a matching public key on my GitHub account. Here is how I did it on my Windows 10 computers:

==Create an SSH key on the computer and put the matching public key on GitHub==
To use SSH authorization with GitHub, you need a key on the computer with a Git repository and then the public key that goes with it needs to be copied to your account on GitHub. This is a condensed version of the instructions on the GitHub web site.

This is all command line stuff in Git Bash, so if you have not installed Git for Windows, that has to happen first.

===Check if there is already a key pair===
I am assuming if there is already a key pair on the computer, you can use it. It would normally be in your user directory\.ssh (c:\users\ed\.ssh on EJBDESK) What I see there is id_ed25519 and id_ed25519.pub, which is the key pair I have already created for use with GitHub.

===How to create a key pair===

Using Git Bash...

$ '''ssh-keygen -t ed25519 -C "your_email@example.com"''' 

The ed25519 is a particular algorithm, and the generated public/private key pair will be id_ed25519 and id_ed25519.pub

There will be a prompt > Enter a file in which to save the key (/c/Users/you/.ssh/id_ed25519):[Press enter]

Just pressing enter tells it to use the default. Note that in Bash, /c means C: to the keys will go in C:/users/your_user_name/.ssh/

Next, you are prompted to provide a passphrase. Note you can leave this empty, which is what I opted for because my stuff on GitHub is open to everybody anyway, and I don't plan on using these keys for anything else.

===Add the SSH key to the ssh-agent, which manages the keys===
Note: While open SSH is available for windows, Git for Windows includes a version, so when you start wingit, including Git Bash, that version gets started. I explored the native windows version, and decided to put it off, because I am only using it for Git.

First we need to start ssh-agent. This is done with the Git Bash command

$ '''eval "$(ssh-agent -s)"'''

...this will return a line like this...

> Agent pid some_process_id

Now we can send it commands:

$ '''ssh-add ~/.ssh/id_ed25519'''

...which adds the key we generated to the agent.

So now we have the local key on the computer. We need to do this on each computer that is going to address our GitHub account.

===Copy the public key to GitHub===
To make GitHub recognize the key we just created, we need to put a copy of the public key into our GitHub account. This is just a copy/paste operation. Still in Git Bash, do this...

$ '''clip < ~/.ssh/id_ed25519.pub'''

This copies the public key to the clipboard. You can also do it by opening the key in a text editor and copying the contents of the file to the clipboard.

Now we log into GitHub and click on our round user icon in the upper right corner, which opens a menu containing "Settings."

Under Settings, pick SSH and GPG keys, and then the "new SSH key" button.

Fill in the Title field with a description of the key. For mine, I just used the name of the computer that key came from.

Below that, there is a space for the key. Just paste the key there as text and click  the "Add SSH key" button. You may need to type your GitHub account password to finish this.

Note: all of this came from the GitHub web site. See it [https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent here]

===Using Github with ssh authentication===

First of all, make sure Git is up to date. I was running 2.19.1 and the latest version was 2.34.0

Since GitHub stopped supporting username/password authentication August 13, 2021, I was having a hell of a time doing pushes, because authentication never succeeded. Poking around, I would get a ssh prompt every once in a while, but did not know what to type for the "token". So here is what I found out.

* The token is a "passphrase" you attach to the ssh public key with a command, '''ssh-keygen -p -f ~/.ssh/id_ed25519'''. Once you have done that, there is essentially no record of it, so you gotta remember it. I had not created a passphrase when I created the key.
* The local git repository needs to have the URL for the remote repository specified the right way... git@github.com:user/repo.git, where user in my case is eburdick, and repo.git is the name of the repository, like myprogram.git. The git command for this is '''<nowiki>git remote set-url origin https://github.com/USERNAME/REPOSITORY.git</nowiki>'''
* Make sure programs that embed git functionality are up to date. I updated PyCharm, and the first time I tried to do a git push, it complained that git was out of date.