Gallery:Using Git:Advanced Topics

Working with a gallery3 fork on GitHub

These are some basic instructions on creating your own fork of gallery3 on GitHub, making changes to it, keeping it up-to-date and getting your changes back into the master repository. These are the basic steps that you will have to take:

Installing the git client

First of all you will need to install the git client software on your machine. See above for a description on how to do it on Windows.

Creating the fork

If you don't already have one you will need to create an account on GitHub.

Once you are logged in you go the gallery3 master repo at [1] and click on the fork button at the top.

Setting up your public key

In order for you to be able to push changes to your fork repo you will need to provide GitHub with you puplic key. This authenticates you and makes sure you have the necessary permission to push to that repo.

You find a good explanation on GitHub on how to do that: [2]

Cloning the repo on your local machine

In order to get a copy of the code onto your local machine you have to clone your fork repo. You will have to use 'Your Clone URL' instead of the 'Public Clone URL', because the later one is read-only. So what you will have to do is run:

$ git clone git@github.com:username/gallery3.git

Keeping your repo up-to-date

This is where it becomes a little tricky. But this GitHub guide should help: [3]

Committing changes to your fork

• From the Git Bash command prompt, navigate to the directory that your code is stored in (if you haven't already).
• You can type "git status" to display a list of new and modified files.
• You can type "git add FILENAME" to add the file to the list to be committed. You must do this when initially adding new files. You will then type "git commit" to commit the changes.
• Alternately, if the files are already being tracked, you may also type "git commit -a" to commit all modified files at once.
• At this point git will open up a VIM window listing new and modified files that are to be committed. Type in some text on the top line to explain this commit, and then press ESC and type ":wq" (without the quotes).
• Now type "git push" to upload your new commit back to github.

Merging your fork with the master repo

To merge changes to the master repo back into your fork, first start up Git Bash and navigate to the directory your code is stored in.

• Type "git fetch NAME" (example: "git fetch gallery3" or "git fetch gallery3-contrib") to download any newer changes.
• Type "git merge NAME/master" (example: "git merge gallery3/master" or "git merge gallery3-contrib/master") to merge these changes into the local copy of your repository.

See above for committing those updates back to your github account.

When to fork, clone or branch

notes courtesy of talmdal - core developer

Here, we'll discuss these concepts of using git. What to do and when to do it.

I fork gallery/gallery3 so I can make changes to the gallery that may never be moved to the originating repository. I might have some unique changes that I want to make to my gallery installation, but don't think they will ever be integrated into the main gallery3 distribution.

I clone the remote repository to that I can have a local repository that I can edit and test against.

I branch a repository when I want to make changes that I expect to re-integrate with the original repository. The difference between fork and branch is intent and access. Fork when you don't have write access or may diverge; "branch" when you do have access and will likely re-merge the changes.

Target development environment

notes courtesy of talmdal - core developer

I want the following development environment. I have read/write access to all the gallery/* repro's being a core developer. A non core developer would only have Read access to the gallery/* repro's and write to their own fork.

On my development system the above respository structure looks like:

/var
  /git_data
    /gallery3
      gallery/gallery3 (main) Read/Write Access
      gallery/gallery3:talmdal (branch) Read/Write Access
      talmdal/gallery3 (fork) Read/Write Access
      talmdal/gallery3: my_branch (branch) => Read/Write Access talmdal/gallery3
    /gallery3-contrib contains:
      gallery/gallery3-contrib(main) Read/Write Access
      gallery/gallery3-contrib:talmdal(branch) Read/Write Access     
    /gallery3-vendor
      gallery/gallery3-vendor(main) Read/Write Access
    /gallery3-packaging
      gallery/gallery3-packaging(main) Read/Write Access

/var/www/gallery3 is a symlink to /var/git_data/gallery3

I also symlink any -contrib modules from the web root i.e. from the /var/www/gallery3/modules directory ln -sf /var/git_data/gallery3-contrib/modules/developer developer Then in /var/git_data/.git/info/exclude add the line modules/developer This will allow the gallery3 module administration to find the developer module yet will force git to ignore it when it checks status and does commits.

Setting up the gallery3 repositories

• A) First clone the gallery3 main repository using the public url. From the git_data directory:

 git clone git://github.com/gallery/gallery3.git gallery3

• B) Add your fork as additional remote

 cd gallery3
 git remote add <remote name> <git-url>
 git fetch <remote name>

At this point, you should be able to to pull updates from the main gallery repository git pull origin master and push your changes to your repository git push <remote name> master

If you are using a git repository that you have write access to, you can create a branch to make the changes without changing the main trunk.

• C) Set the push default.

 git config push.default tracking

• D) Create a branch

 git checkout -b <branch-name> origin/master

• E) Push the branch back to repository

 git push origin <branch-name>

• F) Create a branch that tracks the remote that you was added (b)

 git branch --track <new-branch> <remote name>/master

At this point, you should have 2 unique repositories:

git remote show

And multiple branches

git branch -l

Setting up the -contrib repositories

This is my setup, but could be applied to your clone of the repository.

• A) first clone the yourname/gallery3-contrib using its write access url. From the git-data directory enter:

git clone <git-url> gallery3-contrib

• B) Set the push default. this will determine which remote repository the commited changes will be pushed to:

 cd gallery3-contrib
 git config push.default tracking

• C) Create the branch

 git checkout -b <branch-name> origin/master

• D) Push the branch back to repository

 git push origin <branch-name>