# 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
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::
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.::
