Blame doc/usage/forks.rst

Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
.. _forks:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Forks
Jeremy Cline 0b19fd
=====
Jeremy Cline 0b19fd
A fork in Pagure is a copy of a repository. When contributing to a project on
Jeremy Cline 0b19fd
Pagure, the first step is to fork it. This gives you a place to make changes
Jeremy Cline 2772cf
to the project and, if you so wish, contribute back to the original project.
Jeremy Cline 2772cf
If you're not already familiar with Git's distributed workflow,
Jeremy Cline 0b19fd
`the Pro Git book has an excellent introduction
Jeremy Cline 0b19fd
<https: book="" distributed-git-distributed-workflows="" en="" git-scm.com="" v2="">`_.</https:>
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
You can see a list of projects you've forked on your home page.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
.. _create-fork:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Create a Fork on Pagure
Jeremy Cline 0b19fd
-----------------------
Jeremy Cline 0b19fd
To fork a project, simply navigate to the project on Pagure and click
Jeremy Cline 0b19fd
the fork button. You will then be redirected to your new fork.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
.. _configure-local-git:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Configure your Local Git Repository
Jeremy Cline 0b19fd
-----------------------------------
Jeremy Cline 0b19fd
Now that you have forked the project on Pagure, you're ready to configure a
Jeremy Cline 0b19fd
local copy of the repository so you can get to work. First, clone the
Jeremy Cline 0b19fd
repository. The URL for the repository is on the right-hand side of the
Jeremy Cline 0b19fd
project overview page. For example::
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
    $ git clone ssh://git@pagure.io/forks/jcline/pagure.git
Jeremy Cline 0b19fd
    $ cd pagure
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
After cloning your fork locally, it's a good idea to add the upstream
Jeremy Cline 0b19fd
repository as a `git remote <https: docs="" git-remote="" git-scm.com="">`_. For</https:>
Jeremy Cline 0b19fd
example::
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
    $ git remote add -f upstream ssh://git@pagure.io/pagure.git
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
This lets you pull in changes that the upstream repository makes after you
Jeremy Cline 0b19fd
forked. Consult Git's documentation for more details.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Pushing Changes
Jeremy Cline 0b19fd
---------------
Jeremy Cline 0b19fd
After you :ref:`configure-local-git` you're ready to make your changes and
Jeremy Cline 0b19fd
contribute them upstream. First, start a new branch::
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
    $ git checkout -b my-feature-or-bugfix
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
It's a good idea to give the branch a descriptive name so you can find it later.
Jeremy Cline 0b19fd
Next, make your changes. Once you're satisfied, add the changes to Git's staging
Jeremy Cline 0b19fd
area and commit the changes::
Jeremy Cline 0b19fd
René Genz a2130c
    $ git add -A  # add all changes
René Genz a2130c
    $ git commit -s # prepare changes for upload
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Your text editor of choice will open and you can write your commit message.
René Genz a2130c
If you have not done so already :ref:`upload-your-ssh-key` now.
René Genz 520020
Afterwards, you are ready to push your changes to your remote fork::
Jeremy Cline 0b19fd
René Genz a2130c
    $ git push -u origin my-feature-or-bugfix # upload changes
Jeremy Cline 0b19fd
René Genz 5d0807
In case you cloned the repo via HTTP, for example using a command like `git
Pierre-Yves Chibon aec95f
clone https://...`, the push will fail. Pagure.io does not support pushing
René Genz 5d0807
over HTTP. An easy workaround is to use::
René Genz a2130c
René Genz a2130c
    $ git push -u origin my-feature-or-bugfix ssh://git@pagure.io/forks/jcline/pagure.git
René Genz a2130c
René Genz a2130c
You are now ready to :ref:`open-pull-request`.