This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Github provides github desktop app a GUI actually only for Windows and MacOS users but what about *nix like Os's(e.g. Linux) users? That page include
- A guide for those users who can (or want) use git only from console(shell). After all git was born(and effectively is) as a Command Line Application and medium-experienced users can exploit all git's powerful features trough a console
- A tutorial on git's use to collaborate your Open/free resources with free-programming-books
Guide
Installation
If you're a *nix user probably git is installed per default in your system if not for sure exist in your distribution's repository. You can install it flawlessly trough your distribution's package manager. For all other users git is available on all major platforms. Consult the official Git Web site go to Downloads section and choose the package to download in function of your platform
Configuration
Git comes with a long list of configuration options covering everything from your name to your favorite text editor and merge tool. You can set options with
- the git config command
- by manually editing a file called .gitconfig in your home directory.
Some of the most common options are presented below.
User Info
The first thing you’ll want to do with any new Git installation is introduce yourself. That's an important step because git records this information with your commits, and third-party services like GitHub use it to identify you.
git config --global user.name "John Smith" git config --global user.email john@example.com
The --global flag records options (at your home level) in ~/.gitconfig, making it the default for all new repositories you create. Omitting it lets you specify options on a per-repository basis(mean you can specify a different user name and/or email for different repositories you create or use).
Editor
Git’s command-line implementation relies on a text editor for most of its input. You can force Git to use your editor-of-choice with the core.editor option:
git config --global core.editor gvim
make sure you use the correct parameters required for the specified editor(take a glance on the editor's web page) e.g. for geany a lightweight GUI text editor you must use -imnst parameters otherwise geany when is called from git not stand open as it would but appears and disappears instantly
git config --global core.editor=geany -imnst
Aliases
By default, Git doesn’t come with any shortcuts, but you can add your own by aliasing commands. If you’re coming from an SVN background, you’ll appreciate the following bindings:
git config --global alias.st status git config --global alias.ci commit git config --global alias.co checkout git config --global alias.br branch
Here you can find some more useful aliases.
Learn more by running the git help config in your git Bash prompt.
Initializing Repositories
Git is designed to be as unobtrusive as possible. The only difference between a git repository and an ordinary project folder is an extra .git directory in the project root (not in every subfolder like SVN). To turn an ordinary project folder into a full-fledged git repository one way is to move into the project folder and run the following command:
git init
in case we were out of the project directory the argument of git init command should be a path to the repository (leaving it blank will use the current working directory) e.g.
git init path/to/repository
After git init(mean repository's initialization ) , you can use all of git’s powerful version control features.
Tutorial
Here are two main collaborative development models. Here we're using the more general fork and pull collaboration model adopted from the majority of the Open Source projects
Abstract: From a bird's eye view we have to
- create a free GitHub account
- Fork the free-programming-books's central public repository
- Clone the forked public repository
- Do our first change in our local repository
- Synchronize the forked repository with a changed central repository
Getting Started
Objective: Create a free GitHoub account
The best way to get started with GitHub is to open your favorite browser and enter https://github.com/ to open the GitHub's main page. You can sign up for GitHub directly from the home page simply by filling in the requested user name, email address, and password. The fields are dynamically validated, reporting any issues as you type.
Your user name(think and choose it carefully the very first time can save you from 404 page not found errors, see below for more details) will be visible on your public repositories, so be sure to choose one that you don’t mind sharing with other people.
You will be able to change your user name from your profile screen, and GitHub will automatically update your repository information.
However, if people have links to your old profile page, these will not be redirected to your new name, but rather return a 404 (not found) error. If you do change your user name, be sure to update any public profiles to reference the new name.
Choosing your plan
Once you’ve filled in your account information, the next step is to choose a GitHub plan. The default plan is the Free plan. This plan allows you to create public repositories and to interact with other repositories as well. That's the plan we have to choose here.
However as you work with GitHub, you may want to use it for your internal or private development work. In this case, the paid plans come into play.
Your dashboard
After entering basic account information and choosing a plan, you are taken to your personal dashboard page. The GitHub Bootcamp banner across the top lets you use a wizard approach to set up Git and your own repositories.
At this point, you have a GitHub account set up, and you are able to search GitHub, download code (and other files), and interact with other user’s repositories.
Fork the free-programming-books's central public repository
Ogjective: Fork(copy) the central(original) repository to a repository having the same name in our GitHub account
Go to Free Ebook Foundation's page click on free-programming-books's page and click on the Fork button up right.
As result GitHub's system has forked(copied an exact copy -at the fork time-) free-programming-books's (let's call it Central for further reference) repository to our GitHub's account. Notice that the two repositories Central and forked are distinct. Now we can play on our forked repository without impact/harm the Central repository
Clone the forked public repository to a local(hence private) repository
Objective: transfer our free-programming-books's forked(from the central repository) copy to our local disc.
You can use either https or ssh protocols
Go where you want to place your local copy and issue:
git clone https://github.com/EbookFoundation/free-programming-books.git
or trough ssh
git clone git@github.com:EbookFoundation/free-programming-books.git
That command create a clone(exact copy) of our forked copy of free-programming-books repository on our local disk mean transfer from our GitHub account the needed files create a new directory named free-programming-books in the place we choose and put the downloaded files into that directory. Also add in there a .git (hidden -because of dot-) directory that represent the very real git's repository of free-programming-books. The output of that command is:
harrykar@harrysas:~/Desktop/test$ git clone git@github.com:EbookFoundation/free-programming-books.git
Initialized empty Git repository in /home/harrykar/Desktop/test/free-programming-books/.git/
remote: Enumerating objects: 24, done.
remote: Counting objects: 100% (24/24), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 13016 (delta 8), reused 19 (delta 8), pack-reused 12992
Receiving objects: 100% (13016/13016), 4.35 MiB | 97 KiB/s, done.
Resolving deltas: 100% (7949/7949), done.
Do our very first contribution
Objective: Assume we have to contribute on English language books. Although the contribution is at an International level there are multilingual contributors but the procedure to follow is the same for all us. What change is the file on which we have to operate.
Before go further read the contributing page about the rules to observe.
First thing first we have Go to your cloned repository that's a directory(folder) named free-programming-books (created by git clone as we saw earlier). Open your shell and issue
harrykar@harrysas:~/git_repos/free-programming-books$ git status
On branch master
Git say we're on master branch the first thing we've to do is to create a new branch(let's call it harrykar) and move there
harrykar@harrysas:~/git_repos/free-programming-books$ git checkout -b harrykar
On branch harrykar
Ok now you can open the free-programming-books.md text file in your text editor. That file has a particular syntax and rules(nothing complex) you have to observe. One of the rules state the list of books may stay in alphabetical order(because so it's easier to find a book).
the general form of a book is Book's Title - Author
Let's say
It's a good practice the first times to take confidence contribute not more than one book
For our example
Update our forked repository with a changed central repository
Objective: Synchronize our forked repository with the central repository (trough our local repository)
So far we've three repositories
- Central(original) public repository belongs to EbookFoundation; now on we call it also remote upstream
- Forked public repository belongs to one of us Contributors; now on we call it also remote origin
- Local private repository belongs to one of us Contributors
The Central public repository is continuously updated from it's Integrators(people with special rights who's sole work is to investigate and finally integrate into the (Central) repository our(we're Contributors) proposals on open books). After we forked the central repository one second later probably our forked repository is out of date because of one or more changes(made from integrators) in the Central repository.
Before we send our proposal on open books to the free-programming-books Central repository we've to be updated with the latest Central's repository status.
In other words we must fetch the changes made meanwhile in the Central repository just in case someone else likely has already sent the very same proposal as us themselves as the environment is highly distributive
How can we synchronize our outdated forked repository with the Central repository? We can do it trough our local repository. Let's see how:
Immediately after we did git clone on our forked repository we have in our local repository one remote called(per default) origin:
harrykar@harrysas:~/git_repos/free-programming-books$ git remote -v
origin git@github.com:harrykar/free-programming-books.git (fetch)
origin git@github.com:harrykar/free-programming-books.git (push)
Our aim now is to make a direct connection trough our local repository and our Central(Source) repository(remote upstream) in order to update our local repository to the latest status(changes) of our Central repository and after that operation finally update our forked repository(remote origin) with the contents of the (updated to the latest changes) local repository.
To do all that we first have to add to our local repository the reference to our Central(Source) repository(remote upstream):
harrykar@harrysas:~/git_repos/free-programming-books$ git remote add upstream git@github.com:EbookFoundation/free-programming-books.git
now we have in our local repository other than remote origin(Forked repo) also remote upstream(Central repo)
harrykar@harrysas:~/git_repos/free-programming-books$ git remote -v
origin git@github.com:harrykar/free-programming-books.git (fetch)
origin git@github.com:harrykar/free-programming-books.git (push
upstream git@github.com:EbookFoundation/free-programming-books.git (fetch)
upstream git@github.com:EbookFoundation/free-programming-books.git (push)
The same info is available in a more simple form mean without the -v (verbose) flag
harrykar@harrysas:~/git_repos/free-programming-books$ git remote
origin
upstream
The following command connect to our remote origin(forked repo) and shows us some useful info about
harrykar@harrysas:~/git_repos/free-programming-books$ git remote show origin
- remote origin
Fetch URL: git@github.com:harrykar/free-programming-books.git
Push URL: git@github.com:harrykar/free-programming-books.git
HEAD branch: master
Remote branches: close-2491 tracked
deprecate-javascript-pages tracked
eshellman-patch-1 tracked
how-to tracked
...
Local branch configured for 'git pull':
master merges with remote master
Local ref configured for 'git push':
master pushes to master (local out of date)
The following command connect with our remote upstream and shows us some info about upstream(Central repo).
harrykar@harrysas:~/git_repos/free-programming-books$ git remote show upstream
- remote upstream
Fetch URL: git@github.com:EbookFoundation/free-programming-books.git
Push URL: git@github.com:EbookFoundation/free-programming-books.git
HEAD branch: master
Remote branches:
close-2491 new (next fetch will store in remotes/upstream)
deprecate-javascript-pages new (next fetch will store in remotes/upstream)
eshellman-patch-1 new (next fetch will store in remotes/upstream)
how-to new (next fetch will store in remotes/upstream)
...
Local ref configured for 'git push':
master pushes to master (local out of date)
After the last two purely informational commands it's time to go operational. The following command move us from e.g. our local collaborating(or whatever) branch to local master branch
harrykar@harrysas:~/git_repos/free-programming-books$ git checkout master
Switched to branch 'master'
The following command fetch(download) the remote upstream(Central) repo into our local repo. Our local repository becomes a sort of a concentration repository
harrykar@harrysas:~/git_repos/free-programming-books$ git fetch upstream
remote: Enumerating objects: 40, done.
remote: Counting objects: 100% (40/40), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 44 (delta 27), reused 35 (delta 24), pack-reused 4
Unpacking objects: 100% (44/44), done.
From github.com:EbookFoundation/free-programming-books
- [new branch] close-2491 -> upstream/close-2491
- [new branch] deprecate-javascript-pages -> upstream/deprecate-javascript-pages
- [new branch] eshellman-patch-1 -> upstream/eshellman-patch-1
- [new branch] how-to -> upstream/how-to
...
- [new branch] standardize-wikibooks -> upstream/standardize-wikibooks
The following command is an informational one: indicates us all the branches(local and remotes) that are contained in our local repo
harrykar@harrysas:~/git_repos/free-programming-books$ git branch -va
harrykar 9ca0f12 issues:add in list #3009,#3010, correction blank in #3011
- master 9ca0f12 issues:add in list #3009,#3010, correction blank in #3011
remotes/origin/HEAD -> origin/master
remotes/origin/close-2491
5a1a911add princeton algorithms
remotes/origin/deprecate-javascript-pages
6a461e9deprecate the javascript frameworks pages
remotes/origin/eshellman-patch-1
20b37e4remove js framework link
remotes/origin/how-to
8e35929add resource titles and delint
remotes/origin/master 9ca0f12 issues:add in list #3009,#3010, correction blank in #3011
...
remotes/upstream/standardize-wikibooks
5047c7fMerge branch 'master' into standardize-wikibooks
Time to incorporate the Central(source) repository's changes to our local repository. Notice that in the earlier step (git fetch) we had simply downloaded but not incorporated the Central's repo changes in our local repo After that operation the two repos(private local and public Central) are synchronized. Make sure you're in master branch (git status)
harrykar@harrysas:~/Desktop/test/free-programming-books$ **git status **
'#' On branch master
nothing to commit (working directory clean)
Notice here one can use merge or rebase command. I use rebase that time because of the more linear history. To recap the following command rebase(integrate) the upstream's(Central) master onto our local master branch
harrykar@harrysas:~/git_repos/free-programming-books$ git rebase upstream/master
First, rewinding head to replay your work on top of it...
Applying: issues:add in list #3009,#3010, correction blank in #3011
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
Auto-merging free-programming-books.md
Now miss only one final step and we're done (mean the updating circle is closed): update our forked remote origin repository(that as we know reside into our GitHub account) from our (just updated) local repo
$ git push -f origin master
Counting objects: 26, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (22/22), done.
Writing objects: 100% (22/22), 3.14 KiB, done.
Total 22 (delta 16), reused 0 (delta 0)
remote: Resolving deltas: 100% (16/16), completed with 4 local objects.
To git@github.com:harrykar/free-programming-books.git
46876e2...6807a45 master -> master (forced update)
Now we've done our forked repository is syncronized with the latest changes in our Central repository
(to be continued...)