Initial commit.

1 files changed, 164 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..9bc24f9
--- /dev/null
+++ b/README.org
@@ -0,0 +1,164 @@
+#+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, 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.
+
+* 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.