git_roadmap

Initial author : K. A. Draziotis

=== Simple Github tutorial v.1.0 ===


-- Basic Definitions --

Repository : a database that contains information to manage the history
 of a project. There two structures of a git repository. 
1. Index : which is a binary file and
2. obejct store :  which is a directory. The object store  contains 
four objects : Blobs, trees, commits, tags.

<> Blobs : each version of a file is represented as a blob. Blobs are only
referenced by the trees and references nothing. I.e blobs are at the bottom
of the data stracture in a git repo. 

<> Trees : contain some metadata as blob identifier,
pathnames etc. In this way an hierarchy of files and subdirectories is built.
Trees, point to other trees or to blobs.

<> Commits : ia an object that holds metadata for each change into a repository. 
It holds the author name, commit date, log message and others.
Tag : this is the hash of an object, usually a commit. Tags point to
commit(s).

<> Index : is a binary file that describes the structure of the repository.

<> HEAD is simply a reference to the current commit (latest) on the current branch.

--- States of a files ---
Untracked       : The file is just created. Git sees a file you didn’t have in the previous commit.
Staged/Unstaged : If you give "git add" to an untracked file the the new status of the file is Staged. If you give "git reset <file>" you go back to
the previous state.
Modified        : 
commited        :


-- basic Git commands --

$git help or $git help --all|less
$git --version
$git help "command" for instance $git help add

If you want all the commits (not only for the specific directory) to use 
a specific name and email then you have to use the following command:
$git config --global user.name "John"
$git config --global user.mail "a@a.com"
To list the settings of all variables give:
$git congig -l

Since the configuration fields are text files,
If you want to delete or edit something, give
$sudo nano ~/.gitconfig
or:
$git config --local user.name "John"
$git config --local user.email "a@a.com"

Say you want to commit a file foo.txt then do:

$git add .
$git commit -m "something"
$git push

and the file will be transfered to the remote repo.

The command $git add .
updates the object store and indexed by sha1. 
The files are now stagged. Since you have to apply "git add ." the sha1's will be 
computed again. Giving now 
$git diff --cached
you will get the differences of the files you changed relatively to the previous version (of the same file).
When you apply 
$git commit
then, the file becomes a part of the working directory and your are now one commit  ahead from the remote repo.
To update the remote repo 
$git push
If you don't give $git push and instead give
$git checkout filename
then, all the changes will be lost.

In case you want to create and checkout to a new branch then

$git checkout -b foo

and to push it in the remote repo

$git push origin foo

Now you have two branches : master and foo

Say that you've made a change on a specific file while you were
in the branch foo. Now, if you want to add the changes of the file to the
master branch you have to do 
$git checkout master  
$git merge foo

Contents
---------
1. Syncing your local fork with the main repo
2. Go back to the previous commit
3. If you want to delete a remote branch
4. If by a mistake you made git pull 
5. If after pull request you get, error: Your local changes to the following files would be overwritten by merge:..
6. If you want to change the commit message of a previous commit
7. Review a Pull request of the upstream repository
8. Review a Pull request from the origin 
9. Review a specific commit from the origin
10. Delete a file from remote repo
11. Go back to the previous commit
12. git pull does not update my files locally
13. Develpoment, using a branch
14. rename a local branch
15. diff of two files
16. clone a specific branch of a repository
17. Merge two branches
18. Merge specific files from one branch to another
19. Compare two files from different branches
20. mv a file between two branches
21. a better git log
22. ssh and github
23. If you get a message : this branch is 1 commit behind the upstream and has conflicts that must be resolved
24. Remove a remote file that is in .gitignore
25. Initialize a new branch
 
=== 1.Syncing your local fork with the main repo ===

First configure a remote for your fork:

$git remote add upstream https://github.com/ORIGINAL_OWNER.git
$git remote -v

Then sync your fork with the upstream:

$git checkout master
$git fetch upstream
$git merge upstream/master 
(or git merge upstream/main)

so now you have:

origin	https://github.com/drazioti/repo_name.git (fetch)
origin	https://github.com/drazioti/repo_name.git (push)
upstream	https://github.com/ORIGINAL_OWNER/repo_name.git (fetch)
upstream	https://github.com/ORIGINAL_OWNER/repo_name.git (push)

You may now clone your fork to a local directory of your PC.
To sync your local repo (i.e. this in your PC) with your github repo (i.e. your fork) give $git pull, and to add in your fork, give 
add/commit/push as usual. When you are ready, make a pull request from the github site to the upstream.

To delete the upstream

$git remote rm upstream


=== 2.Go back to the previous commit ===

Say that your commit has hash H (using git status you cna find the hash), then 
$git checkout H -b foo

will make a new branch "foo" and move the HEAD to commit with hash H.

=== 3.If you want to delete a local/remote branch ===

$git push <remote_name> --delete <branch_name>
Usually <remote_name> is origin
or delete a local branch
$git branch -D <branch name>

=== 4.If by mistake you made $git pull === 

Say you want to go back to the previous state, give
$git revert HEAD #this will not rewrite history

If you want to go back to a specific commit both the local and the remote repo (origin)
then,

$git reset --hard db2b8f5       # this will rewrite history
$git push -f origin master      # this will sync the remote repo (origin master) with your local (master) i.e.
				# the remote repo will go back to the previous commit with fingerprint : db2b8f5 
or
$git push -f origin main

=== 5.if after pull request you get, error: Your local changes to the following files would be overwritten by merge:..

$git stash save --keep-index

This will remove all local changes from your working copy

Another solution is 

$git reset --hard

which will remove all you local changes but it will not change branch.
This is a good solution if you use many times 

$git fetch origin pull/46/head:bug --update-head-ok 

and in parallel you make local changes to your files.


=== 6.If you want to change the commit message of a previous commit ===

see https://help.github.com/en/github/committing-changes-to-your-project/changing-a-commit-message
[first $git --amend and then $git push --force-with-lease origin EXAMPLE-BRANCH]

=== 7.Review a Pull request of the upstream repository ===

$git status

If you do not have any collisions, then
say you want to review the pull request
[WIP] bug fixing #46

$git fetch upstream pull/46/head:bug
$git checkout bug

=== 8.Review a Pull request from the origin ===

the same, but
$git fetch origin pull/46/head:bug
and you can review the bug.
If changes were made and you want to update

$git fetch origin pull/46/head:bug --update-head-ok 

=== 9.Review a specific commit from the origin ===

$git checkout -b branch_name hash_of_the_commit

=== 10.Delete a file from remote repo ===

Say that you delete (with rm) a file or files from your local repo and want to update the remote repo.

$git commit -a -m "A file was deleted"
$git push

=== 11.Go back to the previous commit ===

$git reset HEAD^ --hard
$git push -f

=== 12.git pull does not update my files locally ===

try the following :

$git fetch --all
$git reset --hard origin/master


=== 13.Develpoment, using a branch ===
Create a new local branch say "mybranch" to your fork.

$git checkout -b mybranch

Then add/make the changes you want.
Push the branch to your (remote) fork

$git add .
$git commit -m "sthm"
$git push --set-upstream origin mybranch
$git checkout master
$git add .
$git commit -m "."
$git push

If while editing files in your branch 'mybranch'
another user changed something in the remote master branch 
do the following.

$git checkout master
$git fetch upstream
$git merge upstream/master
$git checkout mybranch
$git rebase origin/master
$nano [conflict file]
solve conflicts by removing <,=,> markers
$git rebase continue

=== 14.Rename a local branch

$git branch -m <old name> <new name>

=== 15.diff of two files

Say you made some changes of 'foo' file in some branch. You want to see
all the differences of the 'foo' file as is in the repository and with the new
updated 'foo'.

$git diff HEAD:foo foo

=== 16. clone a specific branch of a repository

$git clone --single-branch --branch <branchname> <remote-repo>

=== 17. Merge two branches

Say you have only branch1 locally. In origin you have another branch say branch2.
You want to merge branch2 to branch1.

In the cuurent state you have :

$git branch
*branch1

First give

$git fetch origin <rbranch>:<lbranch>

rbranch : name of the remote branch, i.e. branch2
lbranch : name for the local branch, again branch2

Now you also have the branch2 

I.e.

$git branch
*branch1
branch2

Finally, you are ready to merge.

=== 18. Merge specific files from one branch to another

Say you have branch1 and branch2 and you are in branch2.
There is a file foo.txt in branch1. To merge this file into branch2 you have to give

$git checkout --patch branch1 foo.txt
and answer [y] to the question.

Then, add/commit/push.

=== 19. Compare two files from different branches

$git diff branch1 branch2 foo.txt

base file is foo.txt in branch2

=== 20. mv a file between two branches

You are in branch2 and there is a file in branch1, say foo.txt. 
You want to copy foo.txt in branch2.

$git checkout branch2 foo.txt

=== 21. better git log

$git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

(see https://coderwall.com/p/euwpig/a-better-git-log)

Now you can use $git lg

=== 22. ssh and github

After you've added your ssh key to github, accessing github from console, will continue to ask for username/password.
Go to your repo that you want to access with ssh and give

$git remote set-url origin git@github.com:github_username/repository_name

Also, every time you restart your pc, give

$eval "$(ssh-agent -s)"
$ssh-add ~/.ssh/id_ed25519 % assuming you generated keys based on Edwards elliptic curve

=== 23. If you get a message : this branch is 1 commit behind the upstream and has conflicts that must be resolved

sync your fork (branch : main)  with the original repository (upstream).
 
$git pull --rebase upstream main
$git add .
$git commit -m "."
$git push

=== 24. Remove a remote file that is in .gitignore

say you want to remove .ipynb_checkpoints/ from remote repo
 
$git rm -r --cached .ipynb_checkpoints/
$git rm -r --cached .ipynb_checkpoints/ [without git add]
$git push

=== 25. Initialize a new branch

$git checkout -b foo
$git push --set-upstream origin foo