diff --git a/attendees_and_learners.rst b/attendees_and_learners.rst index 26239c9e..3f50786e 100644 --- a/attendees_and_learners.rst +++ b/attendees_and_learners.rst @@ -10,6 +10,11 @@ Workshops PyCon UK in Coventry, 22nd September 2013 ----------------------------------------- +* Arnav Khare https://github.com/arnav +* Helen Sherwood-Taylor (helenst) +* Tim Garner +* Mat Brunt +* John S DjangoCon US in Chicago, 2nd September 2013 ------------------------------------------- diff --git a/docs/git/commandlinegit.rst b/docs/git/commandlinegit.rst new file mode 100644 index 00000000..26aaa036 --- /dev/null +++ b/docs/git/commandlinegit.rst @@ -0,0 +1,368 @@ +###################### +Git on the commandline +###################### + +In this section you will: + +* install and configure Git locally +* create your own local clone of a repository +* create a new Git branch +* edit a file and stage your changes +* commit your changes +* push your changes to GitHub +* make a pull request +* merge upstream changes into your fork +* merge changes on GitHub into your local clone + +So far we've done all our Git work using the GitHub website, but that's usually +not the most appropriate way to work. + +You'll find that most of your Git-related operations can and need to be done on the commandline. + +Install/set up Git +================== + +:: + + sudo apt-get install git # for Debian/Ubuntu users + brew install git # for Mac OS X users with Homebrew installed + +There are other ways of installing Git; you can even get a graphical Git application, that will include the commandline tools. These are described at: + + http://git-scm.com/book/en/Getting-Started-Installing-Git + +Tell Git who you are +-------------------- + +First, you need to tell Git who you are:: + + git config --global user.email "you@example.com" + git config --global user.name "Your Name" + +Give GitHub your public keys +---------------------------- + +This is a great timesaver: if GitHub has your public keys, you can do all +kinds of things from your commandline without needing to enter your GitHub +password. + +* https://github.com/settings/ssh + +https://help.github.com/articles/generating-ssh-keys explains much better than +I can how to generate a public key. + +**This tutorial assumes you have now added your public key to your GitHub +account.** If you haven't, you'll have to use *https* instead, and translate +from the format of GitHub's *ssh* URLS. + +For example, when you see:: + + git@github.com:evildmp/afraid-to-commit.git + +you will instead need to use:: + + https://github.com/evildmp/afraid-to-commit.git + +See https://gist.github.com/grawity/4392747 for a discussion of the different +protocols. + + +Some basic Git operations +========================= + +When we worked on GitHub, the basic work cycle was *fork* > *edit* > *commit* +> *pull request* > *merge*. The same cycle, with a few differences, is what we +will work through on the commandline. + +Clone a repository +------------------ + +When you made a copy of the *Don't be afraid to commit* repository on GitHub, +that was a *fork*. Getting a copy of a repository onto your local machine is +called *cloning*. Copy the *ssh URL* from +``https://github.com//afraid-to-commit``, then:: + + git clone git@github.com:/afraid-to-commit.git + +Change into the newly-created ``afraid-to-commit`` directory, where you'll find +all the source code of the *Don't be afraid to commit* project. + +Now you're in the **working directory**, the set of files that you currently +have in front of you, available to edit. We want to know its status:: + + $ git status + # On branch master + nothing to commit (working directory clean) + +Create a new branch +------------------- + +Just as you did on GitHub, once again you're going to create a new branch, +based on *master*, for new work to go into:: + + $ git checkout -b amend-my-name + Switched to a new branch 'amend-my-name + +``git checkout`` is a command you'll use a lot, to switch between branches. The +``-b`` flag tells it to **create a new branch** at the same time. By default, +the new branch is based upon whatever branch you were on. + +Edit a file +----------- + +#. find the ``attendees_and_learners.rst`` file in your working directory +#. after your name and email address, add your Github account name +#. save the file + +``git status`` is always useful:: + + $ git status + # On branch amend-my-name + # Changes not staged for commit: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: attendees_and_learners.rst + # + no changes added to commit (use "git add" and/or "git commit -a") + +What this is telling us: + +* we're on the *amend-my-name* branch +* that we have one modified file +* that there's nothing to commit + +These changes will only be applied to this branch when they're committed. You +can ``git add`` changed files, but until you commit they won't belong to any +particular branch. + +.. note:: + When to branch + + You didn't actually *need* to create your new *amend-my-name* branch until + you decided to commit. But creating your new branches before you start + making changes makes it less likely that you will forget later, and commit + things to the wrong branch. + +Stage your changes +------------------ + +Git has a **staging area**, for files that you want to commit. On GitHub +when you edit a file, you commit it as soon as you save it. On your +machine, you can edit a number of files and commit them altogether. + +**Staging a file** in Git's terminology means adding it to the staging +area, in preparation for a commit. + +Add your amended file to the staging area:: + + git add attendees_and_learners.rst + +and check the result:: + + $ git status + # On branch amend-my-name + # Changes to be committed: + # (use "git reset HEAD ..." to unstage) + # + # modified: attendees_and_learners.rst + # + +If there are other files you want to change, you can add them when you're +ready; until you commit, they'll all be together in the staging area. + +What gets staged? +^^^^^^^^^^^^^^^^^ + +It's not your files, but the **changes to your files**, that are staged. Make +some further change to ``attendees_and_learners.rst``, and run ``git status``:: + + $ git status + # On branch amend-my-name + # Changes to be committed: + # (use "git reset HEAD ..." to unstage) + # + # modified: attendees_and_learners.rst + # + # Changes not staged for commit: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: attendees_and_learners.rst + # + +Some of the changes in ``attendees_and_learners.rst`` will be committed, and the +more recent ones will not. + + * run ``git add`` on the file again to stage the newer changes + +Commit your changes +------------------- + +When you're happy with your files, and have added the changes you want to +commit to the staging area:: + + git commit -m "added my github name" + +The ``-m`` flag is for the message ("added my github name") on the commit - +every commit needs a commit message. + +Push your changes to GitHub +--------------------------- + +When you made a change on GitHub, it not only saved the change and committed +the file at the same time, it also showed up right away in your GitHub +repository. Here there is an extra step: we need to **push** the files to +GitHub. + +If you were pushing changes from *master* locally to *master* on GitHub, you +could just issue the command ``git push`` and let Git work out what needs to go +where. + +It's always better to be explicit though. What's more, you have multiple +branches here, so you need to tell git *where* to push (i.e. back to the remote +repository you cloned from, on GitHub) and *what* exactly to push (your new +branch). + +The repository you cloned from - yours - can be referred to as **origin**. The +new branch is called *amend-my-name*. So:: + + $ git push origin amend-my-name + Counting objects: 34, done. + Delta compression using up to 2 threads. + Compressing objects: 100% (21/21), done. + Writing objects: 100% (28/28), 6.87 KiB, done. + Total 28 (delta 13), reused 12 (delta 7) + To git@github.com:evildmp/afraid-to-commit.git + * [new branch] amend-my-name -> amend-my-name + +.. note:: + Be explicit! + + Next time you want to push committed changes in *amend-my-name*, you won't + *need* to specify the branch - you can simply do ``git push``, because now + *amend-my-name* exists at both ends. However, it's *still* a good idea to + be explict. That way you'll be less likely to get a surprise you didn't + want, when the wrong thing gets pushed. + +Check your GitHub repository +---------------------------- + +* go to https://github.com//afraid-to-commit +* check that your new *amend-my-name* branch is there +* check that your latest change to ``attendees_and_learners.rst`` is in it + + +Send me a pull request +---------------------- + +You can make more changes locally, and continue committing them, and pushing +them to GitHub. When you've made all the changes that you'd like me to accept +though, it's time to send *me* a pull request. + +**Important**: make sure that you send it from your new branch *amend-my-name* +(not from your *master*) the way you did before. + +And if I like your changes, I'll merge them. + +.. note:: + Keeping master 'clean' + + You *could* of course have merged your new branch into your *master* + branch, and sent me a pull request from that. But, once again, it's a good + policy to keep your *master* branch, on GitHub too, clean of changes you + make, and only to pull things into it from upstream. + + In fact the same thing goes for other branches on my upstream that you + want to work with. Keeping them clean isn't strictly necessary, but it's + nice to know that you'll always be able to pull changes from upstream + without having to tidy up merge conflicts. + +Incorporate upstream changes +---------------------------- + +Once again, I may have merged other people's pull requests too. Assuming that +you want to keep up-to-date with my changes, you're going to want to merge +those into your GitHub fork as well as your local clone. + +So: + +* on GitHub, pull the upstream changes into your fork the way you did + previously + +Then switch back to your master branch in the usual way (``git checkout +master``). Now, fetch updated information from your GitHub fork (**origin**), +and merge the master:: + + git fetch + git merge origin/master + +So now we have replicated the full cycle of work we described in the previous +module. + +.. note:: + ``git pull`` + + Note that here instead of ``git fetch`` followed by ``git merge``, you + could have run ``git pull``. The ``pull`` operation does two things: it + **fetches** updates from your GitHub fork (**origin**), and **merges** + them. + + However, be warned that occasionally ``git pull`` won't always work in the + way you expect, and doing things the explicit way helps make what you are + doing clearer. + + ``git fetch`` followed by ``git merge`` is generally the safer option. + + +Switching between branches locally +---------------------------------- + +Show local branches:: + + git branch + +You can switch between local branches using ``git checkout``. To switch back to +the *master* branch:: + + git checkout master + +If you have a changed tracked file - a tracked file is one that Git is +managing - it will warn you that you can't switch branches without either +committing, abandoning or 'stashing' the changes: + +Commit +^^^^^^ + +You already know how to commit changes. + +Abandon +^^^^^^^ + +You can abandon changes in a couple of ways. The recommended one is:: + + git checkout + +This checks out the previously-committed version of the file. + +The one that is not recommended is:: + + git checkout -f + +The ``-f`` flag forces the branch to be checked out. + +.. note:: + Forcing operations with ``-f`` + + Using the ``-f`` flag for Git operations is to be avoided. It offers plenty + of scope for mishap. If Git tells you about a problem and you force your + way past it, you're inviting trouble. It's almost always better to find a + different way around the problem than forcing it. + + ``git push -f`` in particular has ruined a nice day for many people. + + +Stash +^^^^^ + +If you're really interested, look up ``git stash``, but it's beyond the scope of this tutorial. diff --git a/docs/git/conflicts.rst b/docs/git/conflicts.rst new file mode 100644 index 00000000..b7a1cb62 --- /dev/null +++ b/docs/git/conflicts.rst @@ -0,0 +1,117 @@ +################### +Resolving conflicts +################### + +In this section you will: + +* encounter a merge conflict on GitHub +* encounter a merge conflict on the commandline +* resolve the confluct in a new temporary Git branch + + +Encountering a merge conflict on GitHub +======================================= + +Sometimes you'll discover that your GitHub fork and the upstream repository +have changes that GitHub can't merge. + +There's an *unmergeable-branch* at https://github.com/evildmp/afraid-to-commit. +It's unmergeable because it deliberately contains changes that conflict with +other changes made in *master*. + +Try creating a pull request from *unmergeable-branch* to your *amend-my-name* +on GitHub. If you do, GitHub will tell you: + + We can’t automatically merge this pull request. + + Use the command line to resolve conflicts before continuing. + +GitGub will in fact tell you the steps you need to take to solve this, but to +understand what's actually happening, and to do it yourself when you need to, +we need to cover some important concepts. + +Merging changes from a remote branch +==================================== + +:: + + $ git checkout amend-my-name # make sure you're on the right branch + $ git fetch upstream + $ git merge upstream/unmergeable-branch + Auto-merging attendees_and_learners.rst + CONFLICT (content): Merge conflict in attendees_and_learners.rst + Automatic merge failed; fix conflicts and then commit the result. + +When there's a conflict, Git marks them for you in the files. You'll see +sections like this:: + + <<<<<<< HEAD + * Daniel Pass + * Kieran Moore + ======= + * Kermit the Frog + * Miss Piggy + >>>>>>> upstream/unmergeable-branch + +The first section is what you have in your version. The second section is what +Git found in the version you were trying to pull in. + +You'll have to decide what the file should contain, and you'll need to edit +it. If you decide you want the changes from both versions:: + + * Daniel Pass + * Kieran Moore + * Kermit the Frog + * Miss Piggy + + $ git add attendees_and_learners.rst + $ git commit -m "fixed conflict" + [amend-my-name 91a45ac] fixed conflict + $ git push origin amend-my-name + +Creating a branch for merging work +================================== + +Sometimes it's sensible *not* to do merging work in a branch you rely on. In +the example above, your *amend-my-name* branch doesn't contain a great deal of +work. If you had a branch that contained many complex changes however, you +certainly wouldn't want to discover dozens of conflicts making a mess in the +files containing all your hard work. + +So remember, **branches are cheap and disposable**. Rather than risk messing +up the branch you've been working on, create a new one specially for the +purpose of discovering what sort of conflicts arise, and to give you a place +to work on resolving them without disturbing your work so far:: + + git checkout -b resolve-conflict amend-my-name + +As before, this means: create and switch to a new branch called +*resolve-conflict*, based on branch *amend-my-name*. + +We'll use this new branch as a safe place to do the potentially messy work of +resolving the conflicts in. + +You have already resolved the conflict with *unmergeable-branch*, so I have +provided *unmergeable-branch-2* for you. The conflict I here is extremely +simple, but you could have conflicts across dozens of files, if you were +unlucky. Even if it all goes horribly wrong in here, that won't affect either +of the two branches you were trying to reconcile - they'll remain safely +untouched. + +Tell Git to attempt to merge the conflicting branch into this one:: + + $ git merge upstream/another-unmergeable-branch + +Resolve the conflicts as before (edit the file, ``add`` it, ``commit`` the +changes). Now your *resolve-conflict* branch has reconciled the latest changes +in your *amend-my-name*, *and* my *unmergeable-branch-2*. + +At this point, you would make quite sure that everything is correct (that +tests run and so on), *before* merging back into *amend-my-name*. + +Then the last step is to merge *resolve-conflict* into *amend-my-name*, thus +bringing with it the changes from *unmergeable-branch-2*:: + + git checkout amend-my-name + git merge resolve-conflict + git push origin amend-my-name diff --git a/docs/git/git.rst b/docs/git/git.rst new file mode 100644 index 00000000..9b825827 --- /dev/null +++ b/docs/git/git.rst @@ -0,0 +1,252 @@ +############## +Git and GitHub +############## + +In this section you will: + +* create a GitHub account +* create your own fork of a repository +* create a new Git branch +* edit and commit a file on GitHub +* make a pull request +* merge upstream changes into your fork + + +What is it? +=========== + +**Git** is a source code management system, designed to support collaboration. + +**GitHub** is a web-based service that hosts Git projects, including Django +itself: https://github.com/django/django. + +The key idea in Git is that it's *distributed*. If you're not already familiar +with version control systems, then explaining why this is important will only +introduce distinctions and complications that you don't need to worry about, +so that's the last thing I will say on the subject. + + +Set up a GitHub account +======================= + +* sign up at `GitHub `_ if you don't already have an + account + +It's free. + +Some basic editing on GitHub +============================ + +Forking +------- + +* visit https://github.com/evildmp/afraid-to-commit/ + +You can do various things there, including browsing through all the code and files. + +* hit the **Fork** button + +A few moments later, you'll have your own copy, on GitHub, of everything in +that repository, and from now on you'll do your work on your copy of it. + +Your copy is at ``https://github.com//afraid-to-commit/``. + +You will typically do this for any Git project you want to contribute to. It's +good for you because it means you don't have to sign up for access to a +central repository to be permitted to work on it, and even better for the +maintainers because they certainly don't want to be managing an small army of +volunteers on top of all their other jobs. + +.. note:: + Don't worry about all the forks + + You'll notice that there might be a few forks of + https://github.com/evildmp/afraid-to-commit; if you have a look at + https://github.com/django/django you'll see thouands. There'll even be + forks of the forks. Every single one is complete and independent. So, + which one is the real one - which one is *the* Django repository? + + In a technical sense, they all are, but the more useful answer is: the + one that most people consider to be the canonical or official version. + + In the case of Django, the version at https://github.com/django/django is + the one that forms the basis of the package on PyPI, the one behind the + https://djangoproject.com/ website, and above all, it's the one that the + community treats as cannonical and official, not because it's the original + one, but because it's the most useful one to rally around. + + The same goes for https://github.com/evildmp/afraid-to-commit and its + more modest collection of forked copies. If I stop updating it, but + someone else is making useful updates to their own fork, then in time + theirs might start to become the one that people refer to and contribute + to. This could even happen to Django itself, though it's not likely to + any time soon. + + The proliferation of forks doesn't somehow dilute the original. Don't be + afraid to create more. Forks are simply the way collaboration is made + possible. + + +Create a new branch +------------------- + +This isn't strictly necessary, but it's still a very good idea. Rather than +edit the *master* (default) branch of the repository, it's better to edit the +file in a new branch, leaving the *master* branch clean and untouched: + +#. select the **branch** menu +#. in *Find or create a branch...* enter ``add-my-name`` +#. hit **Create branch: add-my-name** + +.. note:: + Don't hesitate to branch + + As you may have noticed on GitHub, a repository can have numerous branches + within it. Branches are ways of organising work on a project: you can have + a branch for a new feature, for trying out something new, for exploring an + issue - anything at all. + + Just as virtualenvs are disposable, so are **branches** in Git. You *can* + have too many branches, but don't hesitate to create new ones; it costs + almost nothing. + + It's a good policy to create a new branch for every new bit of work you + start doing, even if it's a very small one. + + It's especially useful to create a new branch for every new feature you + start work on. + + **Branch early and branch often**. If you're in any doubt, create a new + branch. + + +Edit a file +----------- + +GitHub allows you to edit files online. This isn't the way you will normally +use Git, and it's certainly not something you'll want to spend very much time +doing, but it's handy for very small changes, for example typos and spelling +mistakes you spot. + +#. go to ``https://github.com//afraid-to-commit`` +#. find the ``attendees_and_learners.rst`` file +#. hit the **Edit** button +#. add your name (and email address, if you like) to the appropriate place in + the file +#. if following the tutorial by yourself, add your details in the *I followed + the tutorial online* section. + +Commit your changes +------------------- + +* hit **Commit Changes** + +Now *your* copy of the file, the one that belongs to *your* fork of the +project, has been changed; it's reflected right away on GitHub. + +If you managed to mis-spell your name, or want to correct what you entered, +you can simply edit it again. + +What you have done now is make some changes, in a new branch, in your own fork +of the repository. You can see them there in the file. + +Make a Pull Request +------------------- + +When you're ready to have your changes incorporated into my +original/official/canonical repository, you do this by making a **Pull +Request**. + +* go back to ``https://github.com//afraid-to-commit`` + +You'll see that GitHub has noted your recent changes, and now offers various +buttons to allow you to compare them with the original or make a pull request. + +* hit **Compare & pull request** + +This will show you a *compare view*, from which you can make your pull request. + +When preparing for a pull request, GitHub will show you what's being compared:: + + evildmp:master...:add-my-name + +On the left is the **base** for the comparison, my fork and branch. On the +right is the **head**, your fork and branch, that you want to compare with +it. + +A pull request goes from the **head** to the **base** - from right to left. + +You can change the bases of the comparison if you need to: + +#. hit **Edit** +#. select the forks and branches as appropriate + +You want your version, the **head branch** of the **head fork** - on the +right - with some commits containing file changes, to be sent to my **base +repo** - on the left. + +#. hit the **Pull Request** button +#. add a comment if you like (e.g. "please add me to the attendees list") +#. hit **Send pull request** + +You have now made a pull request to an open-source community +project - if it's your first one, congratulations. + +GitHub will notify me (by email and on the site, and will show me the changes +you're proposing to make). It'll tell me whether they can be merged in +automatically, and I can reject, or accept, or defer a decision on, or comment +on, your pull request. + +GitHub can automatically merge your contribution into my repository if mine +hasn't changed too much since you forked it. If I want to accept it but GitHub +can't do it automatically, I will have to merge the changes manually (we will +cover this later). + +Once they're merged, your contributions will become a part of +https://github.com/evildmp/afraid-to-commit. And this is the basic lifecycle of +a contribution using git: *fork* > *edit* > *commit* > *pull request* > +*merge*. + +Incorporate upstream changes into your master +--------------------------------------------- + +In the meantime, other people may have made their own forks, edits, commits, +and pull requests, and I may have merged those too - other people's names may +now be in the list of attendees. Your own version of afraid-to-commit, +*downstream* from mine, doesn't yet know about those. + +Since your work is based on mine, you can think of my repository as being +*upstream* of yours. You need to merge any *upstream* changes into *your* +version, and you can do this with a pull request on GitHub too. + +This time though you will need to switch the bases of the comparison around, +because the changes will be coming from *my version* to *yours*. + +#. hit **Pull Request** once more +#. hit **Edit**, to switch the bases +#. change the **head repo** on the right to *my* version, + ``evildmp/afraid-to-commit``, branch *master* +#. change the **base repo** to yours, and the **base branch** to *master* +#. hit **Click to create a pull request for this comparison** +#. add a **Title** (e.g. "merging upstream master on Github) and hit **Send + pull request** + +You're sending a pull request to to *yourself*, based on updates in my +repository. And in fact if you check in your **Pull Requests** on GitHub, +you'll see one there waiting for you, and you too can review, accept, reject +or comment on it. + +If you decide to **Merge** it, your fork will now contain any changes that +other people sent to me and that I merged. + +The story of your work is this: you **forked** away from my codebase, and then +created a new **branch** in your fork. + +Then you **committed** changes to your branch, and sent them **upstream** back +to me (with a **pull request**). + +I **merged** your changes, and perhaps those from other people, into my +codebase, and you **pulled** all my recent changes back into your *master* +branch (again with a **pull request**). + +So now, your *master* and mine are once more in step. \ No newline at end of file diff --git a/docs/git/index.rst b/docs/git/index.rst new file mode 100644 index 00000000..8e489a80 --- /dev/null +++ b/docs/git/index.rst @@ -0,0 +1,29 @@ +############## +Git and GitHub +############## + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + + git + commandlinegit + remotes + conflicts + moregit + + +**Git** is a source code management system, designed to support collaboration. + +**GitHub** is a web-based service that hosts Git projects, including Django +itself: https://github.com/django/django. + +Git is a quite remarkable tool. It's fearsomely complex, but you can start +using it effectively without needing to know very much about it. All you really +need is to be familiar with some basic operations. + +The key idea in Git is that it's *distributed*. If you're not already familiar +with version control systems, then explaining why this is important will only +introduce distinctions and complications that you don't need to worry about, +so that's the last thing I will say on the subject. diff --git a/docs/git/moregit.rst b/docs/git/moregit.rst new file mode 100644 index 00000000..3202549e --- /dev/null +++ b/docs/git/moregit.rst @@ -0,0 +1,70 @@ +####################### +More key Git techniques +####################### + +There are a few more key Git commands and techniques that you need to know +about. + +.gitignore +========== + +When you're working with Git, there are lots of things you won't want to push, including: + +* hidden system files +* .pyc files +* rendered documentation files +* ... and many more + +``.gitignore``, +https://github.com/evildmp/afraid-to-commit/blob/master/.gitignore, is what +controls this. You should have a ``.gitignore`` in your projects, and they +should reflect *your* way of working. Mine include the things that my +operating system and tools throw into the repository; you'll find soon enough +what yours are. + +With a good ``.gitignore``, you can do things like:: + + git add docs/ + +and add whole directories at a time without worrying about including unwanted +files. + +Starting a new Git project +========================== + +You've been working so far with an existing Git project. It's very easy to +start a brand new project, or turn an existing one into a Git project. On +GitHub, just hit the **New repository** button and follow the instructions. + +Combining Git and pip +===================== + +When you used pip to install a package inside a virtualenv, it put it on your +Python path, that is, in the virtualenv's ``site-packages`` directory. When +you're actually working on a package, that's not so convenient - a Git project +is the most handy thing to have. + +On the other hand, cloning a Git repository doesn't install it on your Python +path (assuming that it's a Python application), so though you can work on it, +you can't actually use it and test it as an installed package. + +However, pip is Git-aware, and can install packages *and* put them in a +convenient place for editing - so you can get both:: + + cd ~/ + virtualenv git-pip-test + source git-pip-test/bin/activate + pip install -e git+git@github.com:washort/parsley.git#egg=parsley + +The ``-e`` flag means editable; ``git+`` tells it to use the Git protocol; ``#egg=parsley`` tells it what to call it. + +And now you will find an editable Git repository installed at: + + ~/git-pip-test/src/parsley + +which is where any other similarly-installed packages will be, and just to prove that it really is installed:: + + $ pip freeze + -e git+git@github.com:washort/parsley.git@e58c0c6d67142bf3ceb6eceffd50cf0f8dae9da1#egg=Parsley-master + wsgiref==0.1.2 + diff --git a/docs/git/remotes.rst b/docs/git/remotes.rst new file mode 100644 index 00000000..63e10b65 --- /dev/null +++ b/docs/git/remotes.rst @@ -0,0 +1,109 @@ +#################### +Working with remotes +#################### + +In this section you will: + +* add a remote repository to your local clone +* fetch remote information +* checkout a remote branch +* merge an upstream branch + +Managing remotes +================ + +Your repository on GitHub is the **remote** for the clone on your local +machine. By default, your clone refers to that remote as **origin**. At +the moment, it's the only remote you have:: + + $ git remote + origin + + $ git remote show origin + * remote origin + Fetch URL: git@github.com:evildmp/afraid-to-commit.git + Push URL: git@github.com:evildmp/afraid-to-commit.git + HEAD branch: master + Remote branches: + amend-my-name tracked + master tracked + Local branch configured for 'git pull': + master merges with remote master + Local refs configured for 'git push': + amend-my-name pushes to amend-my-name (up to date) + master pushes to master (up to date) + +It's very useful for Git to know about other remote repositories too. For +example, at the end of the previous section, we considered a conflict between +your GitHub fork and and the upstream GitHub repository. The only way to fix +that is locally, on the command line, and by being able to refer to both those +remotes. + +Now you *can* refer to a remote using its full address: + + https://github.com/evildmp/afraid-to-commit + +But just as your remote is called **origin**, you can give any remote a more +memorable name. Your own **origin** has an upstream repository (mine); it's a +convention to name that **upstream**. + +Add a remote +------------ + +:: + + git remote add upstream git@github.com:evildmp/afraid-to-commit.git + +Fetch remote data +----------------- + +The remote's there, but you don't yet have any information about it. You need +to **fetch** that:: + + git fetch upstream + +This means: get the latest information about the branches on **upstream**. + +List remote branches +-------------------- + +``git branch`` shows your local branches. + +To see a list of them all, including the remote branches:: + + git branch -a + +Checkout a remote branch +------------------------ + +You'll have seen from ``git branch -a`` that there's a branch called +*additional-branch* on the **upstream** repository. + +You can check this out:: + + git checkout -b additional-branch upstream/additional-branch + +This means: create and switch to a new local branch called *additional-branch*, +based on branch *additional-branch* of the remote **upstream**. + +Managing *master* on the commandline +==================================== + +Until now, you have only updated your *master* on GitHub using GitHub itself. +Sometimes it will be much more convenient to do it from your commandline. +There are various ways to do it, but here's one:: + + git checkout master # switch back to the master branch + git fetch upstream # update information about the remote + git merge upstream/master # merge the changes referred to by + upstream/master + +``git status`` will tell you that your local master is ahead of your *master* +at **origin**. + +Push your changes to master:: + + git push origin master + +And now your *master* on GitHub contains everything my *master* does; it's +up-to-date and clean.