a sketch of a future git how-to focused on thought patterns

how-to-git.md

how to git.

these are the mental patterns that i associate with git actions. whenever you have the following thoughts, try these actions.

you don't need github to get started. only once you want to share, move between computers, or you don't have a local backup solution.

"yay! this scrap of code is working!"

you've been working on some lil chunk of something, and it finally reaches a "hello world" moment. now is the time to wrap it in a git repository:

# make sure your file(s) is in it's own directory (folder)
cd <your_project> # enter the folder where your project is
git init # turns the current folder into a git repository
git add * # add everything into the working state
git commit -m "it works!" # saves the working state into the repo

now you can keep hacking away on the next thing. no need to make a new branch yet.

"i've been working on feature x, but i want to switch to feature y"

this is a great way to use branches and avoid situations where a semi-working feature gets in the way / distracts you from the thing you want to do.

git status # check what branch you're on
# here we assume you're working on the 'main' branch and not a feature specific one
git checkout -b "branch_name" # where branch_name is the name of the original feature
git add * # add everything
git commit -m "WIP feature x does a but not b"
git checkout main # or whichever branch you came from
# now you're back "before" the changes, and you can start on feature y

"both feature x & feature y work now. i want to combine them"

git checkout main # checkout the branch you want to merge into
git merge feature_x # merge branch feature_x into main
git merge feature_y # merge branch feature_y into main
# you may need to fix some "conflicts" now
# after fixing conflicts, you need to 'git commit -m "merged so and so"'

"i'm ready to merge an older feature, but it's 'out of date'"

you'll often need to do this when opening a PR to a remote repo where there are many people making changes to the same repo. basically you need to bring your feature branch up-to-date with the main branch you want to merge into.

typically (always?) this means there are 'conflicts' between your branch, and the 'upstream' branch you're pushing to.

this is called 'rebasing' i think, but i don't use 'git rebase'

git checkout main # go to the main branch which has changed
git pull # updates your local copy to match the server repo
git checkout your_feature # now move to your feature
git merge main # updates your branch 
# there will be conflicts which the command line will tell you about
# fix them in your code (TODO suggest interactive method)
git commit -m "merge main from upstream"
git push -u origin your_feature # to push your changes to the server
# now you can open a PR on github

"i've been working for a while, and it's not working, so i'm going to change a bunch of random shit."

this is where git shines! you can use it to provide a safety net so you can freely start changing random things.

git status # make sure you're on the right branch
git add -p # add all changes to the next commit
git commit -m "WIP. feature x is kinda broken"
# now start hacking!

as you're hacking away, you'll probably discover the issue was completely unrelated to what you've been changing. you've got 2 options here:

option 1: (use this when it's 1 line, or a typo) just roll back all the junk, and apply the specific change manually:

git reset --hard # abandon everything since the commit
# now change your code to solve the problem correctly
# git add & commit etc

option 2: (use this when you wrote some helper fns, or bigger changes)

git add -p # gives you an interactive method to save specific changes
# git will show you 1 chunk at a time.
# you enter 'y', to add that part
# enter 'n', to skip that part
# enter 's', to split the chunk into smaller pieces (if you only want to save part of it)
git commit -m "the changes that matter" # commit the important elements
git reset --hard # abandon all the junk that didn't work

"this feature is working, i want to commit it, but i'm inside the wrong branch."

when you start using multiple branches you may find yourself having finished something, but before you

git status # will display the name of the branch and the changes you can commit
# oh damn! i'm on the wrong branch!
git stash # save the current changes to the "stash"
git checkout <correct_branch> # switch to the place you want to save it
git stash pop # apply the "stashed" changes onto <correct_branch>
# now you can git add like normal
# you may get a conflict here, but git will guide you to solve it