ParaView/Git

From KitwarePublic
Jump to navigationJump to search

ParaView version tracking and development is hosted by Git.

Official Repository

One may browse the repository online using the Gitweb interface at http://paraview.org/gitweb.

Cloning

The clone URLs for the repository are

git://paraview.org/ParaView.git
http://paraview.org/ParaView.git

The push URL for the repository is

git@paraview.org:ParaView.git

For ParaViewData the URLs are

git://paraview.org/ParaViewData.git
http://paraview.org/ParaViewData.git
git@paraview.org:ParaViewData.git

See the VTK Git documentation for further details.

Branches

At the time of this writing the repository has the following branches:

  • master: Development (default)
  • release: Release preparation branch (prior to switching to a brancy workflow; may go away later)
  • hooks: Local commit hooks (place in .git/hooks)

Release branches converted from CVS have been artificially merged into master. Actual releases have tags named by the release version number.

Submodules

ParaView references a few other projects as submodules. They can be obtained using the git submodule command. First use the 'init' subcommand to register the submodules:

$ git submodule init

This configures the submodules to fetch from their default URLs, such as git://vtk.org/VTK.git for VTK. Next one may optionally configure a different URL, perhaps to use the http protocol:

$ git config submodule.VTK.url http://vtk.org/VTK.git

(and similarly for other submodules if necessary). Finally, use the 'update' subcommand to get the submodules:

$ git submodule update

Whenever you update your work tree to some revision of ParaView then 'git status' may report that the submodule directories are modified. This is because commands like 'git checkout' do not automatically update submodules. Use 'git submodule update' at any time to ensure that the submodule directories are updated to the versions referenced by the parent project.

VTK

ParaView references VTK as a submodule called 'VTK'. Repository URLs:

git://vtk.org/VTK.git
http://vtk.org/VTK.git
git@vtk.org:VTK.git

IceT

ParaView references IceT as a submodule called 'IceT' at path 'Utilities/IceT'. Repository URLs:

git://paraview.org/IceT.git
http://paraview.org/IceT.git
git@paraview:IceT.git

git://public.kitware.com/IceT.git
http://public.kitware.com/IceT.git
git@public.kitware.com:IceT.git

Xdmf

ParaView references Xdmf as a submodule called 'Xdmf' at path 'Utilities/Xdmf2'. Repository URLs:

git://paraview.org/Xdmf.git
http://paraview.org/Xdmf.git
git@paraview:Xdmf.git

git://public.kitware.com/Xdmf.git
http://public.kitware.com/Xdmf.git
git@public.kitware.com:Xdmf.git

Submodules

ParaView references the VTK repository as a submodule (and a few other projects too). See the git submodule command documentation.

Introduction

After the initial clone, Git does not tell you anything special about submodules by default:

$ git status
# On branch master
nothing to commit (working directory clean)

However, the Git submodule porcelain does:

$ git submodule status
-432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT
-17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2
-3bc24abbd97b3d63574e1bafb91948a61033af34 VTK

This says that the currently checked out version of ParaView points to commit 3bc24abb from VTK. The "-" prefix means that the VTK submodule is not checked out in the current work tree. We can confirm this by looking at the VTK directory:

$ ls -a VTK/
./ ../

Even though VTK is not there, the current version of ParaView knows what version of VTK it wants. We can see this by using Git plumbing commands to list the content of the top-level tree:

$ git ls-tree HEAD | tail -3
040000 tree d46aa321e9971c38f484350a2d0495183a0cc517    Utilities
160000 commit 3bc24abbd97b3d63574e1bafb91948a61033af34  VTK
100644 blob 1cdb942f9a8c9e13a1e3da52b6fdbe522626981a    vtkPVConfig.h.in

Note that the entry for "VTK" is not a blob or a tree...it's a commit! The commit is not necessarily known to the ParaView/.git repository because it comes from VTK. We can see the commit here: 3bc24abb

In order to get VTK we need to ask Git to checkout the submodules:

$ git submodule init
Submodule 'IceT' (git://paraview.org/IceT.git) registered for path 'Utilities/IceT'
Submodule 'Xdmf' (git://paraview.org/Xdmf.git) registered for path 'Utilities/Xdmf2'
Submodule 'VTK' (git://vtk.org/VTK.git) registered for path 'VTK'
$ git submodule update
Initialized empty Git repository in /path/to/ParaView/Utilities/IceT/.git/
...
Submodule path 'Utilities/IceT': checked out '432f38d95bfa3c68d1345917680f4d2b4d1267c4'
Initialized empty Git repository in /path/to/ParaView/Utilities/Xdmf2/.git/
...
Submodule path 'Utilities/Xdmf2': checked out '17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f'
Initialized empty Git repository in /path/to/ParaView/VTK/.git/
...
Submodule path 'VTK': checked out '3bc24abbd97b3d63574e1bafb91948a61033af34'

Now Git's submodule porcelain reports

$ git submodule status
 432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT (432f38d)
 17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2 (17f7aad)
 3bc24abbd97b3d63574e1bafb91948a61033af34 VTK (v5.4.2-4340-g3bc24ab)

Note the leading space on each line. This means that the submodule is checked out to the version that our current ParaView version references. We can confirm this by looking in VTK:

$ cd VTK
VTK$ git rev-parse HEAD
3bc24abbd97b3d63574e1bafb91948a61033af34

Note that the VTK work tree is on a detached head, meaning that its HEAD does not point at a branch but instead directly at a commit:

VTK$ cat .git/HEAD
3bc24abbd97b3d63574e1bafb91948a61033af34
VTK$ git status
# Not currently on any branch.
nothing to commit (working directory clean)
VTK$ git branch
* (no branch)
  master
VTK$ cd ..

This is because the submodule reference stored in ParaView (3bc24abb) does not refer to a branch of VTK, but the specific commit.

Look at the log of the VTK submodule in ParaView:

$ git log -p -- VTK
commit 71e7789b18f8006010d6989baa6ced79dc2e3f96
...
diff --git a/VTK b/VTK
index 46a8f04..3bc24ab 160000
--- a/VTK
+++ b/VTK
@@ -1 +1 @@
-Subproject commit 46a8f04a3d6084d18136ac6e51c3eb2685907497
+Subproject commit 3bc24abbd97b3d63574e1bafb91948a61033af34

commit 9f88e601468ecda4c3f52dd07c36b7c275646855
...
diff --git a/VTK b/VTK
index 8920140..46a8f04 160000
--- a/VTK
+++ b/VTK
@@ -1 +1 @@
-Subproject commit 892014037f07ac668979c85b85112fc850515b94
+Subproject commit 46a8f04a3d6084d18136ac6e51c3eb2685907497
...

Note that this does not show the changes in VTK, but rather the changes to the version of VTK that ParaView references.

Think of VTK as a file in ParaView that specifies the version of VTK to use. The content of this "file" is the version of VTK that is checked out in the VTK subdirectory. We can see this by changing the version of VTK in our work tree:

$ cd VTK
VTK$ git checkout 'HEAD^'
VTK$ cd ..

Now our ParaView repository sees that we've modified "VTK":

$ git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   VTK
#
no changes added to commit (use "git add" and/or "git commit -a")
$ git submodule status
 432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT (432f38d)
 17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2 (17f7aad)
+81de700ff1bb6752b4f9710c49ca7454ee2889ae VTK (v5.4.2-4339-g81de700)

The leading "+" means that the submodule is checked out to a different version than that referenced. We can see the modification just like any other file:

$ git diff
diff --git a/VTK b/VTK
index 3bc24ab..81de700 160000
--- a/VTK
+++ b/VTK
@@ -1 +1 @@
-Subproject commit 3bc24abbd97b3d63574e1bafb91948a61033af34
+Subproject commit 81de700ff1bb6752b4f9710c49ca7454ee2889ae

At any time we can ask Git to checkout the version that ParaView wants:

$ git submodule update
Submodule path 'VTK': checked out '3bc24abbd97b3d63574e1bafb91948a61033af34'
$ git status
# On branch master
nothing to commit (working directory clean)
$ cd VTK
VTK$ git rev-parse HEAD
3bc24abbd97b3d63574e1bafb91948a61033af34
VTK$ cd ..