Add SourceTree

[git-wiki.git] / pep-git.txt

diff --git a/pep-git.txt b/pep-git.txt
index 9c07758a32ab236e6c6dbcf2cb90eb63ca076448..c123c389a0105284c043935ec8667f6e7f72eb64 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -75,19 +75,25 @@ Download and installation
 Unix users: download and install using your package manager.
 
 Microsoft Windows: download `git-for-windows
 Unix users: download and install using your package manager.
 
 Microsoft Windows: download `git-for-windows

-<https://git-for-windows.github.io/>`_.
+<https://github.com/git-for-windows/git/releases>`_ or `msysGit
+<https://github.com/msysgit/msysgit/releases>`_.

 
 MacOS X: use git installed with `XCode
 
 MacOS X: use git installed with `XCode

-<https://developer.apple.com/xcode/downloads/>`_ or download
+<https://developer.apple.com/xcode/downloads/>`_ or download from
+`MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or

 `git-osx-installer
 `git-osx-installer

-<http://sourceforge.net/projects/git-osx-installer/files/>`_.
+<http://sourceforge.net/projects/git-osx-installer/files/>`_ or
+install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
+
+`Atlassins's SourceTree <https://www.sourcetreeapp.com/>`_ is a free
+Git and Mercurial GUI client for Windows or Mac.

 
 Initial configuration
 ---------------------
 
 This simple code is often appears in documentation, but it is
 important so let repeat it here. Git marks every commit with author
 
 Initial configuration
 ---------------------
 
 This simple code is often appears in documentation, but it is
 important so let repeat it here. Git marks every commit with author

-and commiter names/emails, so configure your real name and preferred
+and committer names/emails, so configure your real name and preferred

 email::
 
     $ git config --global user.name "User Name"
 email::
 
     $ git config --global user.name "User Name"


@@ -101,13 +107,25 @@ Examples of git commands in this PEP use the following approach. It is
 supposed that you, the user, works with a local repository named
 ``python`` that has an upstream remote repo named ``origin``. Your
 local repo has two branches ``v1`` and ``v2``. For most examples the
 supposed that you, the user, works with a local repository named
 ``python`` that has an upstream remote repo named ``origin``. Your
 local repo has two branches ``v1`` and ``v2``. For most examples the

-currently checked out branch is ``v2``. That is, it's assumed you did
-something like that::
+currently checked out branch is ``v2``. That is, it's assumed you have
+done something like that::
+
+    $ git clone -b v2 http://git.python.org/python.git
+    $ cd python
+    $ git branch v1 origin/v1
+
+The last command creates a new local branch v1 and sets
+remotes/origin/v1 as its upstream remote branch.
+
+The same result can achieved with commands::

 
     $ git clone -b v1 http://git.python.org/python.git
     $ cd python
 
     $ git clone -b v1 http://git.python.org/python.git
     $ cd python

-    $ git fetch origin v2:v2
-    $ git checkout -b v2
+    $ git checkout --track origin/v2
+
+The last command creates a new local branch v2, sets
+remotes/origin/v2 as its upstream remote branch and checks it out into
+the working directory.

 
 
 Branches and branches
 
 
 Branches and branches


@@ -146,10 +164,10 @@ To see local and remote branches (and tags) pointing to commits::
     $ git log --decorate
 
 You never do your own development on remote branches. You create a
     $ git log --decorate
 
 You never do your own development on remote branches. You create a

-local branch that has a remote branch as an upstream and do
-development on that local branch. On push git updates remote branches,
-and on pull git updates remote branches and fast-forwards, merges or
-rebases local branches.
+local branch that has a remote branch as upstream and do development
+on that local branch. On push git updates remote branches, and on pull
+git updates remote branches and fast-forwards, merges or rebases local
+branches.

 
 When you do an initial clone like this::
 
 
 When you do an initial clone like this::
 


@@ -185,7 +203,7 @@ branch BRANCH and its upstream remote branch. But it refuses to update
 branches in case of non-fast-forward. And it refuses to update the
 current branch.
 
 branches in case of non-fast-forward. And it refuses to update the
 current branch.
 

-The first command is used internall by ``git pull``.
+The first command is used internally by ``git pull``.

 
 ::
 
 
 ::
 


@@ -236,8 +254,17 @@ git guesses (knowing upstream remote branches) that you really want
 
     $ git push origin v1:v1 v2:v2
 
 
     $ git push origin v1:v1 v2:v2
 

-Git pushes commits to the remote repo and updates remote branches. It
-is possible to configure git to make it push a few branches or all
+Git pushes commits to the remote repo and updates remote branches. Git
+refuses to push commits that aren't fast-forwardable. You can
+force-push anyway, but please remember - you can force-push to your
+own repositories but don't force-push to public or shared repos. If
+you find git refuses to push commits that aren't fast-forwardable,
+better fetch and merge commits from the remote repo (or rebase your
+commits on top of the fetched commits), then push. Only force-push if
+you know what you do and why you do it. See the section `Commit
+editing and caveats`_ below.
+
+It is possible to configure git to make it push a few branches or all

 branches at once, so you can simply run
 
 ::
 branches at once, so you can simply run
 
 ::


@@ -281,7 +308,7 @@ Commit editing and caveats
 ==========================
 
 A warning not to edit published (pushed) commits also appears in
 ==========================
 
 A warning not to edit published (pushed) commits also appears in

-documentation but it's also repeated here as it's very important.
+documentation but it's repeated here anyway as it's very important.

 
 It is possible to recover from forced push but it's PITA for the
 entire team. Please avoid it.
 
 It is possible to recover from forced push but it's PITA for the
 entire team. Please avoid it.


@@ -316,7 +343,7 @@ safely edit, remove, reorder, combine and split commits that hasn't
 been pushed yet. You can even push commits to your own (backup) repo,
 edit them later and force-push edited commits to replace what has
 already been pushed. Not a problem until commits are in a public
 been pushed yet. You can even push commits to your own (backup) repo,
 edit them later and force-push edited commits to replace what has
 already been pushed. Not a problem until commits are in a public

-repository.
+or shared repository.

 
 
 Undo
 
 
 Undo


@@ -343,15 +370,6 @@ Staging area aka index is a distinguishing feature of git. See
 Wiki.
 
 
 Wiki.
 
 

-Advanced configuration
-======================
-
-Line endings
-------------
-
-Git has builtin mechanisms to handle line endings.
-
-TODO: describe crlf configuration and .gitattributes.

 Merge or rebase?
 ================
 
 Merge or rebase?
 ================
 


@@ -368,6 +386,19 @@ Git has a builtin strategy for what Python core developers call
 ReReRe
 ======
 
 ReReRe
 ======
 

+https://git-scm.com/book/en/Git-Tools-Rerere
+
+
+Advanced configuration
+======================
+
+Line endings
+------------
+
+Git has builtin mechanisms to handle line endings.
+
+TODO: describe crlf configuration and .gitattributes.
+

 
 Database maintenance
 ====================
 
 Database maintenance
 ====================