`GitHub` Quickstart Guide

This is a short and bare bones installation guide and introduction to setting up git as well as gh. It focuses on a NodeJS project example, but any language can be substituted fairly easily. Hopefully you can find it slightly helpful.

Important Files

.gitignore this file tells your repository what to NEVER commit to itself. This is a great way to exclude things that should NEVER be committed to a repository (even a local one!), like any login tokens, API keys, or other credentials.

Here's an example .gitignore.

/credentials
/.idea/*
.env
/players_*.json

Development Recommendations

I (zod / jason) strongly recommend that, if developing on a non-unix operating system such as Windows, git bash be installed and used instead of cmd / Command Prompt, as this project's development target is ultimately a Debian 10 Linux environment, so all code is expected to be functional there.

Requirements

This is an overview of what will be installed in this tutorial.

Note that node and npm are not strictly necessary if they are not needed for your development workflow. For example, in python, the package manager is called pip. These should be already installed, or must be obtained for a python project, Simply install the necessary binaries for your project, along with these two GitHub command line tools.

⚠️_{the versions in parentheses below may or may not be relevant anymore.}

node (~>v16.15.1) available here, comes with npm
npm (~>v8.19.0)
git (~>2.36.0.windows.1) this is implicitly installed if you installed git bash as suggested above.
gh (~>v2.9.0) available here

Installation

Your Operating System (OS) plays a large part in how you will install gh and git, but after installing, they are all (mostly) the same. See the headers below for installation options for common OSes.

Windows

Install and use git bash for the instructions. (this will install a special sort-of bash terminal that you will use for git stuff)

Windows is the shortest and first section... What has the world come to?

Mac

✅ This should work for both M1 and Intel based darwin systems.

First, open Terminal. Now, if you've somehow avoided doing so, install Homebrew. This is the 1-liner to execute from their homepage.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⌚ This will likely take a little while the first time!

Finally, with brew installed, now run the following

$ brew install gh

Bravo.

^{if this doesn't work, just use the CLI installation instructions for linux}

Linux (Debian-based)

This includes Ubuntu, Debian, Kali_{unfortunately}, etc.

🍾 `gh` is FINALLY in `aptitude`!

It's not hard to install anymore! Just

$ sudo apt update -y && sudo apt upgrade -y    # because you are a sane person
$ sudo apt install -y gh

Done!

^{if this doesn't work, just use the CLI installation instructions for linux}

Other Linux / BSD

Good luck.

🧪 Linux & BSD Installation Instructions

Getting Started

The wording in this section references cloning as that's what it was originally written for, but it can be safely ignored and replaced with 'initialized' if you're starting a new repo with git init.

Open git bash and navigate to the location where you want your development files to be cloned.^{or where you want your new repository initialized!} use command cd <path>, example: cd /c/users/jason/documents/zodtf/.
Clone_{or init!} this project.
1. Authenticate your github user. This is because <repo> is a private repository full of proprietary, not-for-reuse-with-modification code. use command gh auth login and follow steps.
  
  You may have to manually copy the auth code of format XXXX-XXXX from your terminal to your browser, especially if your connection is through ssh. If that's the case, the URL is github.com/login/device.
  
  After logging in, use gh to configure the normal git with authorization stuff by executing gh auth setup-git. This has NO output if successful, so don't worry.
  
  if cloning...
2. After authenticating, you simply need to clone the repository. use command gh repo clone zodtf/<repo>.
  
  otherwise...
3. After authenticating, you need to add all your changed files (or just some of them) to your commit, and then commit. This can be done with

 $ git add .                        # add all files in current dir
 $ git commit -m "Initial commit".  # commit with a message to your **LOCAL** repo.

After this, you need to upload your repository to the world! This command will prompt you for all necessary information to upload your masterpiece.

 $ gh repo create

IF JUST UPLOADING

CLICK TO SKIP

YOU DON'T NEED THE FOLLOWING

this branch is frequently called master or main. You are automatically checking out this branch when signing in, so this step can most likely be skipped.

Check out your development branch for your work. use command git checkout \<new branch name\>.

of course only use node package manager to install your project dependencies if your project is a NodeJS project. For python,

Install nodeJS dependencies. use command npm install to install all dependencies defined in package.json.
REDACTED

That's it to start - you're ready to go!

Workflow

This is how I expect progress to be made and pushed to the live repository.

Best Practices / Documentation

When developing, please comment your code reasonably thoroughly & descriptively. Please also use the standard JSDoc format for commenting method headers. (Examples of this can be seen on other methods, especially in processItems.js) Use descriptive variable names or I will get irritated. Otherwise just use your best judgement and keep the code formatted nicely. Thank you.

Commits

After you finish working each session, please commit your code to your branch of the repository. This can be accomplished numerous ways, but here is an example workflow from the command line using git bash.

$ git add .
	#This command adds all the changes you have made locally to the repository to your current commit environment.
$ git commit -m "Added standalone login functionality for standalone executing of priceItems.js via credLoader.js"
	#This command takes all the changes you just added and creates a commit for them. Additionally, the -m flag is used to provide a commit message.
$ git push
	#this command pushes the commit you just staged with the previous command to the remote host, in this case this GitHub repository.

Commit Messages

IT IS VERY IMPORTANT that you use meaningful, descriptive git commit messages which explain (broadly) what changes you have made in the commit you are making.

Versioning

For this subproject, and indeed for most projects, keeping track of project versions is done using the industry standard of major.minor.patch numbers. The current version is defined in the package.json file, and must be updated.

Usually I simply evaluate the amount and types of changes I've made in a given session of coding at commit time, and then increment one of the three numbers (major, minor, or patch) accordingly. For instance, if I spend 8 hours straight and create a new section of the website, I will increment the minor version number, (you may have thought I would use the major number here, however that number signifies large changes / updates to the entire project.) but if I work a few hours on updating said new section later, I will increment the patch number.

Make sure to make this update to the "version" field in package.json BEFORE committing your new changes. It's also helpful to note the new version number within your commit message.

That's All

Good luck out there champ.

-- @zod

zod.tf

fullstack development, server administration, web design, branding creation, musical scoring, video editing, and idk another thing

zudsniper/GITHELP.md

GitHub Quickstart Guide