diff --git a/git_beginner/conf.py b/git_beginner/conf.py
index 00b11f968bb569283ad21bb1777f37bcf45b70b1..5794dfb14607a2dd9cc291ad8acd287d97e26372 100644
--- a/git_beginner/conf.py
+++ b/git_beginner/conf.py
@@ -41,8 +41,8 @@ source_encoding = 'utf-8'
master_doc = 'index'
# General information about the project.
-project = u'git4beginners'
-copyright = u'2013-2014, Holger Dinkel'
+project = u'git basics'
+copyright = u'2013-2015, Holger Dinkel'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -82,9 +82,9 @@ exclude_patterns = ['_build']
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-#pygments_style = 'sphinx'
+pygments_style = 'sphinx'
#pygments_style = 'colorful'
-pygments_style = 'lsi.lsiClassStyle'
+#pygments_style = 'lsi.lsiClassStyle'
# The default language to highlight source code in. The default is 'python'. The value should be a valid Pygments lexer name, see Showing code examples for more details.
highlight_language = 'console'
@@ -110,7 +110,7 @@ html_theme = 'nature'
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
-html_title = "git4beginners"
+html_title = "git basics"
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
@@ -194,7 +194,7 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'gitintro.tex', u'GIT For Beginners',
+ ('index', 'gitintro.tex', u'GIT Basics',
u'Holger Dinkel', 'manual'),
]
@@ -224,7 +224,7 @@ latex_show_urls = False
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'gitintro', u'GIT For Beginners',
+ ('index', 'gitintro', u'GIT Basics',
[u'Holger Dinkel'], 1)
]
@@ -238,8 +238,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'gitintro', u'GIT For Beginners',
- u'Holger Dinkel', 'gitintro', 'GIT For Beginners',
+ ('index', 'gitintro', u'GIT Basics',
+ u'Holger Dinkel', 'gitintro', 'GIT Basics',
'Miscellaneous'),
]
diff --git a/git_beginner/introduction.rst b/git_beginner/introduction.rst
index 54cac25891b879bbcb39a5337099ed4d566e0e5e..8b6f766027561c76c6e777869f9b9384ded8199d 100644
--- a/git_beginner/introduction.rst
+++ b/git_beginner/introduction.rst
@@ -1,6 +1,4 @@
-
-
The Benefits of Version Control
*******************************
@@ -71,10 +69,10 @@ repository
A repository is the history of all your project's commits.
-git Settings
+git settings
============
-setting your identity
+Setting your identity
---------------------
Before we start, we should set the user name and e-mail address.
@@ -87,7 +85,7 @@ and it's also incredibly useful when looking at the history and commit log: ::
Other useful settings include your favorite editor as well as difftool: ::
- git config --global core.editor vim
+ git config --global core.editor nano
git config --global merge.tool meld
@@ -113,56 +111,88 @@ You can use the `git config --list` command to list all your settings: ::
A Typical git Workflow
**********************
-.. figure:: _static/repo_single.png
- :scale: 50 %
+.. figure:: _static/git-local.png
+ :scale: 85 %
- Files are `added` from the `working directory`, which always holds the
- current version of your files, to the `staging area`. `Staged` files will be stored into the repository in the next `commit`.
- The repository itself contains all previous versions of all files ever committed.
+ Files are `added` from the `workspace`, which always holds the current
+ version of your files, to the `staging area`. `Staged` files will be stored
+ into the local repository in the next `commit`. The repository itself
+ contains all previous versions of all files ever committed.
+ (image courtesy of 'research bazaar' https://raw.githubusercontent.com/resbaz/lessons/master/git/git-local.png)
-.. figure:: _static/repo_distributed.png
+.. figure:: _static/git-remote.png
- Distributed Workflow using a centralized repository. Here, three local copies of one central repository allow you,
- Jon and Matt to work on the same files and sync files between each other using the central server.
+ Distributed workflow using a centralized repository. Here, you use `push`
+ and `pull` to synchronize your local repository with a remote repository.
+ (image courtesy of 'research bazaar' https://raw.githubusercontent.com/resbaz/lessons/master/git/git-remote.png)
Creating a git Repository
=========================
-Turning an existing directory into a git repository is as simple as changing into that directory and :index:`invoking <init>` `git init`.
-Here we first create an empty directory called `new_repository` and create a repository in there: ::
+Turning an existing directory into a local git repository is as simple as changing
+into that directory and invoking `git init`. However, here we
+want to create one repository which we can use from multiple other folders to
+sync to/from, therefore in this case, we need to initialize it as a `bare`
+repository.
+
+.. note:: Normally you do not need the `--bare`, but it's essential for this
+ exercise...
+
+So, here we first create an empty directory in our homedirectory called `repos`
+(this is meant to hold and serve all our repositories), and create a repository
+in there called `mythesis`: ::
- mkdir new_repository
- cd new_repository
- git init
+ mkdir ~/repos
+ cd ~/repos
+ mkdir mythesis
+ cd mythesis
+ git init --bare
-.. note:: As a result, there should be a directory called `.git` in this directory...
+.. note:: As a result, you should have the directory `~/repos/mythesis` and there
+ should be a directory called `.git` in this directory...
Cloning a git Repository
========================
-Instead of creating a new directory, we can :index:`clone` a repository. That `origin` repository can reside in a different folder on our computer, on a
-remote machine, or on a dedicated git server:
-Local directory: ::
+Next, we can `clone` this repository into the `~/Documents/mythesis` folder.::
- git clone ../other_directory
+ cd ~/Documents
-Remote directory: ::
+ git clone ~/repos/mythesis
- git clone ssh://user@server/project.git
+ Initialized empty Git repository in /localhome/training/Desktop/mythesis/.git/
+ warning: You appear to have cloned an empty repository.
-Remote git server: ::
+ cd mythesis
- git clone git@server:user/project
- git clone git@git.embl.de:dinkel/linuxcommandline
+By `cloning`, we not only get the exact copy as the remote side, but we
+automatically tell git where we had got the data from, which allows us later to
+sync our changes back...
+.. note:: You can clone from either a different folder on our computer, a remote machine (via ssh), or a dedicated git server::
+
+ Local directory: ::
+
+ git clone ~/repos/mythesis
+
+ Remote directory: ::
+
+ git clone ssh://remote_user@remote_server/mythesis.git
+
+ Remote git server: ::
+
+ git clone git@server:user/project
+
+
Checking the Status
===================
-If you don't know in which state the current repository is in, it's always a good idea to check: ::
+If you don't know in which state the current repository is in, it's always a
+good idea to check: ::
git status
@@ -172,13 +202,18 @@ If you don't know in which state the current repository is in, it's always a goo
#
nothing to commit (create/copy files and use "git add" to track)
+Here, everything is clear, not much going on (no news is good news).
+
+.. note:: In fact, it's good practice, to use `git status` as often as
+ possible!
+
Adding files
=============
First, we'll create a new file: ::
- echo "First entry in first file!" > file1.txt
+ echo "My first line towards a great paper!" > paper.txt
git status
@@ -189,12 +224,14 @@ First, we'll create a new file: ::
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
- # file1.txt
+ # paper.txt
nothing added to commit but untracked files present (use "git add" to track)
-Now we'll add this file to the so called `staging area`: ::
+Here, git tells us that there is a file, however it's `untracked`, meaning git
+does not know/care about it. We need to tell git first that it should keep track
+of it. So we'll add this file to the so called `staging area`: ::
- git add file1.txt
+ git add paper.txt
git status
@@ -205,10 +242,11 @@ Now we'll add this file to the so called `staging area`: ::
# Changes to be committed:
# (use "git rm --cached <file>..." to unstage)
#
- # new file: file1.txt
+ # new file: paper.txt
#
-This tells us that the `file1.txt` has been added and can be committed to the repository.
+This tells us that the `paper.txt` has been added and can be committed to the
+repository.
Committing changes
@@ -246,10 +284,21 @@ Name & Email-address of the committer, Date & Time of the commit as well as the
message describing the changes you made
+Exercise
+--------
+
+Repeat the add/commit procedures you just learned. Add more files, use an editor
+to add more content to the `paper.txt` file, commit your changes providing a
+meaningful commit message.
+
+
Pushing changes
===============
-If we had cloned this repository from a remote location, we probably want our changes to be propagated to that repository as well.
+In order to exchange/synchronize your changes with a remote repository, you use `git push`/`git pull`:
+
+.. figure:: _static/git-remote.png
+
To push all committed changes, simply type: ::
git push
@@ -257,7 +306,31 @@ To push all committed changes, simply type: ::
.. note:: git "knows" from which location you had cloned this repository and will try to
push to exactly that location (using the protocol you used to clone: ssh, git, etc)...
-.. warning:: If you get a warning message, you probably 'just' need to pull others changes before you are allowed to push your own...
+.. warning:: If you get a warning message, read it carefully! The most common
+ error you get when trying to push are changes on the remote end which you first
+ need to merge into your local repository before you are allowed to push your own...
+
+
+Creating a second clone
+-----------------------
+
+In order to simulate contrubting to our repository from another computer, we will again
+checkout the repository, but this time in a different folder named `mythesis-work`::
+
+ cd ~/Documents
+
+ git clone ~/repos/mythesis mythesis-work
+
+ cd ~/Documents/mythesis-work
+
+This repository should contain all the changes you've pushed so far.
+Now we want to improve our `paper.txt` document. Use an editor to add more lines
+to this file::
+
+ echo "This line was contributed from work..." >> paper.txt
+
+Again, `add`, `commit`, and `push` your changes.
+
Pulling changes
===============
@@ -270,8 +343,76 @@ In a centralized workflow you actually **must** pull changes that other people h
.. warning:: Ideally, changes from others don't conflict with yours, but whenever someone else has edited the same lines in the same files as you,
you will receive an error message about a **merge conflict**. You will need to resolve this conflict manually, then add each resolved file (`git add`) and commit.
-.. echo "And another entry in a second file." > file2.txt
-.. git add file2.txt
+
+So we go back to the directory `~/Documents/mythesis` and (after checking the
+status) try to get the changes we've done in the `mythesis-work` directory::
+
+ cd ~/Documents/mythesis
+
+ git status
+
+ git pull
+
+.. TODO: add output of git pull here
+
+
+
+Solving conflicts
+=================
+
+When working collaboratively on a project, it is unavoidable that the same
+file gets changed by different contributors. This causes a conflict and needs to
+be dealt with.
+
+.. hint:: It helps minimizing conflicts if you push/pull often!
+
+To solve a merge conflict, you can either:
+
+- manually merge the two files (see below)
+- discard the remote file: `git checkout --ours conflicted_file.txt`
+- discard the local file: `git checkout --theirs conflicted_file.txt`
+
+
+Manually merging a conflict
+---------------------------
+
+To create a conflict, we change the same line in the file `paper.txt` in both
+directories (`mythesis` and `mythesis-work`) without pulling each others changes
+in between.
+Once we pull, git will tell us that a conflict has occurred.::
+
+ Automatic merge failed; fix conflicts and then commit the result.
+
+When git encounters conflicts in files, it adds special markers `<<<<<<<`,
+`=======`, `>>>>>>>` into this file wrapping both conflicting changes. It is up
+to you to decide which of these changes to keep.::
+
+ ...
+ content of the file
+ ...
+ <<<<<<< HEAD:paper.txt
+ your home changes
+ =======
+ your changes introduced at work
+ >>>>>>> 000000000000000000000000000000000000:paper.txt
+ ...
+ rest of the file
+ ...
+
+Make sure to delete the lines that where introduced by git (otherwise you won't
+be able to commit changes. If you only wanted to keep your changes than you
+would delete everything except your changes::
+
+ ...
+ content of the file
+ ...
+ your home changes
+ ...
+ rest of the file
+ ...
+
+Now, you need to add this file again to the staging area and commit to finish
+this conflicting merge. Use `git status` to see the status of the repository.
Undo local changes
@@ -284,24 +425,33 @@ If you want to undo all changes in a local file, you simply checkout the latest
.. warning:: You will loose all changes you made since the last commit!
+If you want to checkout a specific version (revision) of a file, you need to
+specify the hash or name of the revision::
+ git checkout revision_name <filename>
-Using centralized workflow
-==========================
-
-When you want to use one central repository, to which everybody can push/pull,
-you should initialize this repo like so: `git init --bare`.
-Basically what this does is create a repository which all the files from the `.git` directory in the working directory.
-This also means that you should never add/edit/delete files in this directory. Rather clone this directory in another folder/computer,
-edit files there and commit/push (see below)...
-github
-******
-http://www.github.com
+.. Using centralized workflow
+.. ==========================
+..
+.. When you want to use one central repository, to which everybody can push/pull,
+.. you should initialize this repo as *bare* like so: `git init --bare`. Basically
+.. what this does is create a repository which all the files from the `.git`
+.. directory in the working directory. This also means that you should never
+.. add/edit/delete files in this directory. Rather clone this directory in another
+.. folder/computer, edit files there and commit/push (see below)...
+..
-To clone a repository::
- git clone username@github.com:username/repository
+.. github
+.. ******
+..
+.. Github
+.. http://www.github.com
+..
+.. To clone a repository::
+..
+.. git clone username@github.com:username/repository