Skip to content

Clarify the meaning of remote commands. #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bitdancer wants to merge 3 commits into from
Closed

Clarify the meaning of remote commands. #26

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e6956e7
Clarify the meaning of remote commands.
bitdancer Jul 25, 2016
8018fb2
Clarify that git fetch doesn't update local branches.
bitdancer Jul 25, 2016
57bd784
Fix typo.
bitdancer Jul 25, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 44 additions & 15 deletions faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ For everyone
The following FAQs are intended for both core developers and contributors.

Where can I learn about the version control system used, Git?
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Git_'s official web site is at https://git-scm.com/. A book on Git published
by Apress, `Pro Git`_, is available for free online.
Expand Down Expand Up @@ -243,6 +243,7 @@ Simply use ``git checkout`` to checkout another branch in the current directory:
$ git branch
master
* 3.5
$ make

@brettcannon brettcannon Jul 25, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the make command?

@bitdancer bitdancer Jul 25, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mentioned that in the commit message. You can't do any testing unless you run make after switching branches. If you forget the make, weird and mysterious things may happen.

@willingc willingc Jul 25, 2016

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bitdancer It's likely more user friendly to separate out the make command to a separate paragraph.

Perhaps:

 Simply use ``git checkout`` to checkout another branch in the current directory::

    $ git branch
    * master
      3.5
    $ git checkout 3.5
    Switched to branch '3.5'
    Your branch is up-to-date with 'origin/3.5'.

To verify that your branch has been checked out, enter git branch. After changing branches, it's good practice to run make before executing the tests:

   $ git branch
       master
    * 3.5
   $ make
    $  make


Note that, due to some previously built executables being used as a part of
the build process, you may sometimes run into issues when attempting to
Expand All @@ -267,6 +268,11 @@ Create several clones of your local repository::
Switched to branch '3.5'
Your branch is up-to-date with 'origin/3.5'.

Alternatively, if you have a new enough version of git and don't mind using
a somewhat-experimental feature, you can use `git worktree
<https://git-scm.com/docs/git-worktree>`_ to manage multiple working
directories using a single clone.


.. _git-paths:

Expand All @@ -287,29 +293,52 @@ Then set it as the upstream::
How do I compare my local repository to a remote repository?
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

To display the list of changes that are in your local repository, but not
in the remote, use::
You have in your clone a copy of the state of the branches in the remote
repository. This state is updated any time you do a ``git pull`` or
``git fetch``. You can find out if your local copy is up to date with
its origin by running::

$ git remote show origin

@berkerpeksag berkerpeksag Jul 25, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think using origin is a bit misleading here. origin will likely be the user's fork so unless they explicitly update their fork this command won't show the actual results. Perhaps we need to add a new FAQ entry about adding a new upstream remote and then use it here?

@soltysh soltysh Jul 25, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you do so, please add an information how to sync one's fork with current master as well and how to rebase patches, imho. Both of these are valuable information.

@bitdancer bitdancer Jul 25, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I agree, this should be fixed and rebase should be mentioned. This is turning into a tutorial about using git for cpython development, though. Does it belong in the FAQ or is there somewhere better (and then this faq entry can link to it).

What I do is clone from the original repo, making that origin, and then add my github clone as the remote 'dev'.

@soltysh soltysh Jul 25, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for the faq entry that can be then linked everywhere where appropriate.

@brettcannon brettcannon Jul 26, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we consider not keeping the FAQ around anymore and simply do a good tutorial for using git with cpython development? There's tons of docs online on how to use git unlike Mercurial back in the day, so maybe this whole file will lose its usefulness once we switch to GitHub?

@bitdancer bitdancer Jul 26, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's my thought at this point: that a tutorial covering the actions one will want to do with regards to the CPython repo will be the most useful, specifically covering our workflow, including the interaction with the bug tracker. We'll need to fine tune it as we work the latter out.

@brettcannon brettcannon Jul 26, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, then let's just delete the FAQ. I created #27 to track the deletion of the FAW and #28 to track creating a tutorial.

Feel free to close this PR, @bitdancer , or if you want to take on the deletion and repurpose this PR then that's obviously fine as well.


If there are commits in any of the remote branches that you haven't
merged into your local copies of the branches, this command will tell
you so, and also tell you whether or not you can do a fast-forward merge
(a ``git pull`` without having to make a separate merge commit).

You can do::

$ git fetch

to make sure your copies of the remote branches are up to date. This does
*not* update your local versions of those branches, just your copies of
the state of the remote branches, and thus is always "safe" no matter
what checkins you have or haven't made to your local branches.

Once you have updated your clone from the origin, you can display the list of
changes to your local master branch that are not in your copy of the remote
master branch with::

$ git log origin/master..

This is the list of changes that will be sent if you call
``git push``. It does **not** include any :ref:`uncommitted
This is the list of changes that will be sent if you call ``git push`` with the
master branch checked out. It does **not** include any :ref:`uncommitted
changes <hg-status>` in your working copy!

Conversely, for the list of changes that are in the remote repository but
not in the local, use::
Conversely, for the list of changes that are in your copy of the remote
master branch but not in your version of that branch, use::

$ git log ..origin/master

This is the list of changes that will be retrieved if you call
``git pull``.

Note that these commands will not query the latest state of the remote
repository, but instead the state the repository was in the last time you ran a
command such as ``git fetch`` or ``git pull``. To update the state of remote
branches, run::
This is a list of changes that will be merged into your local copy of the
master branch if you call ``git pull`` with the master branch checked out.
(Additional changes may also be merged, if there have been additional
commits to the remote since the last time you did a ``git fetch`` or
``git pull``)

$ git remote update
Note that these log commands do *not* query the latest state of the remote
repository, but instead are comparing your branch to the state the repository
branch was in the last time you ran a command such as ``git fetch`` or ``git
pull``.


How do I update my local repository to be in sync with a remote repository?
Expand Down