#+TITLE: Magit Tutorial
#+AUTHOR: Christopher Baines
#+EMAIL: mail@cbaines.net

* Getting started
** Install Magit

There are different ways of installing Magit, if there is one suited
to your platform then try that first.

Otherwise, follow the instructions in the [[https://magit.vc/manual/magit/Installing-from-an-Elpa-Archive.html#Installing-from-an-Elpa-Archive][Magit manual to install from
the Elpa archive]].

** Bind =C-x g= to =magit-status=

As described in the [[https://magit.vc/manual/magit.html#Getting-Started][Getting started]] guide in the Magit manual, this
keybinding can be useful.

Add the following to your =.emacs= file.

#+BEGIN_EXAMPLE
(global-set-key (kbd "C-x g") 'magit-status)
#+END_EXAMPLE

** Clone this repository

Use the following command to clone the repository for the
tutorial. Change =~/magit-tutorial= to the directory you wish to use
if that is different.

#+BEGIN_EXAMPLE
M-x magit-clone RET https://git.cbaines.net/magit-tutorial ~/magit-tutorial RET
#+END_EXAMPLE

** Open the tutorial, and continue from Emacs

Now you have the tutorial on your computer, open it in Emacs and
continue.

#+BEGIN_EXAMPLE
C-x C-f ~/magit-tutorial/README.org RET
#+END_EXAMPLE

This file and the repository itself are used for the tutorial.

* Status

Opening the status window is the main way to interact with Magit. This
can be done by running =M-x magit-status= or =M-x g= if you have setup
that binding.

* Comitting

Add some text in to the empty example block below.

#+BEGIN_EXAMPLE

#+END_EXAMPLE

Use =M-x g= to open the Magit status window. If you haven't saved this
file, you'll be prompted to save it, answer =y= to save the file.

Once in the status window, stage the changes by pressing =s= when you
have the file highlighted (the cursor should be on the line which says
=modified README.org=.

Once you've staged the file, it's time to commit it. First, remember
these commands to use after you've written the commit message, use
=C-c C-c= to finish the commit and if you wish to cancel, use =C-c
C-k=.

When you commit with Magit, a new window will be opened to enter the
commit message. Press =c= and then =c= again to commit, which will
open a window to prompt for the commit message. Use the =C-c C-c=
command mentioned above to confirm the message once you've written it,
and finish the commit.

* Viewing the log

From the Magit status window, you can view a log of commits by
pressing =l= and then =l= again.

You can move up and down the log by pressing =p= and =n= respectively.

To view the details for an individual commit, press =RET= (also known
as Enter). To close the window, press =q=.

* Adding remotes

* Pushing

* Pulling

* Interactive rebasing

* Splitting commits

To split a commit, you can combine Magit's ability to revert portions
of a commit with an interactive rebase.

First, lets create a single commit to split. Add some text to both of
the following example blocks.

#+BEGIN_EXAMPLE

#+END_EXAMPLE

#+BEGIN_EXAMPLE

#+END_EXAMPLE

Then commit the additions as a single commit.

As the commit needing splitting is the most recent, it's not necessary
to rebase to edit the right commit, however, in general, you may need
to interactively rebase, and choose to edit the commit you intend to
split.

In the Magit status window, begin the interactive rebase, and then
edit the most recent commit.

Once you've begun the rebase, in the status window, select the commit
to split and press =RET= (Enter) to show the full details.

To split the contents of the commit, we are going to remove some parts
from it. To do that, we can revert those parts, stage that change,
then revert the staged changes. Once the staged changes have been
reverted, those changes can be appended to the commit, effectively
removing that part of the commit. Once this is done, the extracted
part of the commit can then be staged and committed.

First, select the part of the commit to remove and split out. This can
be a file, or a part of a file. To select individual lines, move the
cursor to the start or end of the section, use =C-Space= to start
selecting lines, and then =n= or =p= to move up or down.

Once the target region has been selected, use =v= to begin reverting
the region, press =y= to confirm. Then stage the unstaged changes,
select them and press =s=. Once this is done, revert the staged
changes, move the cursor to the "Staged changes" section, press =v=
and then =y= to confirm.

Then, amend the current commit by pressing =c= then =a=. Once this is
done, stage the unstaged changes, and commit them. When you're
finished committing the unstaged changes, continue the rebase to
finish.

If you wish to split one commit in to more than two commits, then you
can repeat the above process again once finished, or revert all the
parts you wish to split out, and then stage and commit the appropriate
parts of those unstaged changes.

* Viewing a file at a particular revision

* Next steps

From the Magit status buffer, press =?= to get the full list of
commands.

You can view the Magit manual within Emacs, start by pressing =C-h i=
and then navigating to the Magit section.

There are packages other than Magit that extend Emacs to work with Git
repositories. [[https://github.com/syohex/emacs-git-gutter][git-gutter.el]] provides indications within each buffer
when you add, remove or modify the contents.

[[https://github.com/rmuslimov/browse-at-remote][browse-at-remote.el]] allows you to jump from Emacs to common Git
hosting providers, for example, a specific commit.