diff options
| -rw-r--r-- | README.org | 164 |
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. |