GeoGig Workshop

2.5. Working with commits

With setup complete, we can now perform the basic task of a versioned repository: making commits.

2.5.1. Initial commit

Our repository is empty, so we will need to make an initial commit.

2.5.1.1. Importing data

We much import data into our repository for our first commit. This will be the baseline from which we will work.

  1. From the repo directory created in the previous section, use the geogig shp import command to import the data from the file into the repository:

    geogig shp import --fid-attrib ID ../data/bikepdx.shp
    
    Importing from shapefile ../data/bikepdx.shp
    
    Importing bikepdx          (1/1)...
    93%
    6744 distinct features inserted in 6.243 s
    
    Building final tree...
    
    6744 features tree built in 1.206 s
    100%
    ../data/bikepdx.shp imported successfully.

    Note

    Adjust the file path as necessary: geogig shp import ..\data\bikepdx.shp would be used on Windows, for example.

    Important

    What is --fid-attrib? GeoGig needs to know how to uniquely identify each feature in the data set. The bikepdx layer has an attribute named id that does exactly this, so we’ll inform GeoGig of it during the import. Note that GeoGig can also work with other data providers, like PostGIS, and it can automatically detect the unique identifier (the primary key) if it exists.

  2. The data will be imported into GeoGig, ready for versioning. Verify this:

    geogig status
    
    # On branch master
    # Changes not staged for commit:
    #   (use "geogig add <path/to/fid>..." to update what will be committed
    #   (use "geogig checkout -- <path/to/fid>..." to discard changes in working directory
    #
    #      added  bikepdx
    #      added  bikepdx/6526
    #      added  bikepdx/6527
    #      added  bikepdx/6524
    #      added  bikepdx/6525
    ...
    # 6748 total.
    

    On most terminals, the features that have been added are colored red.

2.5.1.2. Adding data

Now that our repository is aware of our spatial data, we can add all the features to the repository so that we can commit them all.

  1. Add all features to the repository:

    geogig add bikepdx
    

    Note

    If we wanted to add only some features to the repository, we could run geogig add bikepdx/[id] where [id] is one of the feature IDs.

    Counting unstaged elements...6748
    Staging changes...
    100%
    6747 features and 1 trees staged for commit
    0 features and 0 trees not staged for commit
  2. Run geogig status to see how the output has changed

    # On branch master
    # Changes to be committed:
    #   (use "geogig reset HEAD <path/to/fid>..." to unstage)
    #
    #      added  bikepdx
    #      added  bikepdx/6526
    #      added  bikepdx/6527
    #      added  bikepdx/6524
    #      added  bikepdx/6525
    ...
    # 6745 total.
    

    On most terminals, the features that have been added are colored green.

2.5.1.3. Committing data

Now we are ready to make our first commit. A commit will include anything that’s been added. It requires only a message to describe the commit. This is a useful text string as the history for a project grows, so it is important to make the message clear.

For example, the following commit messages are good, as they are a clear indication of what the commit entails:

  • “Added new attribute field OWNER”
  • “Removed Main St. feature”
  • “Renamed First Ave to First Avenue”

On the other hand, the following commit messages are not as good:

  • “Made changes”
  • “Added stuff”
  • “Commit”
  1. Commit our changes. Use the message “Initial commit of complete bikepdx layer” via the -m option:

    geogig commit -m "Initial commit of complete bikepdx layer"
    
    100%
    [cfdbd50c415a0d71b9a876eb51f90d5752e8f23b] Initial commit of complete data layer
    Committed, counting objects...6744 features added, 0 changed, 0 deleted.

You have now made your first commit!

2.5.2. Making an attribute change

With a baseline created, it’s time to do some editing.

2.5.2.1. Editing a feature

There are gaps in the bicycling system in Portland. One of the most famous is the “Sellwood Gap”, a one-mile long break in the Springwater Corridor, which is a 20 mile long rail-trail that stretches from the Willamette River to the very edge of the metropolitan area.

Zoom in to this area. To find the Sellwood Gap, find the multi-use trail (styled in dark green) that parallels the river on the east side. Follow it south to the point where it curves away from the river, and you will see that a section of it becomes dashed (meaning that it is not an active path).

../_images/commit_sellwoodgap.png

The “Sellwood Gap”

Note

If you skipped the optional step on adding a background layer, your view will look different.

Let’s say that all interested parties have gotten together and agreed to build this missing section of trail. After construction, you, in charge of updating the city’s GIS data, would change that feature to be an active section.

Specifically, this would involve us making a single change: the attribute status for that feature should be changed from RECOMM to ACTIVE.

  1. If you haven’t already, zoom to the area that contains this feature.

  2. Click the bikepdx entry in the Layers list to ensure it is selected and not any other layer.

  3. Select Layer ‣ Open Attribute Table.

    ../_images/commit_attributetablelink.png

    Open Attribute Table link

  4. This will bring up the attribute table for the layer.

    ../_images/commit_attributetable.png

    Attribute table

  5. In the attribute table, click the pencil icon on the top left to Toggle Editing.

    ../_images/commit_toggleediting.png

    Toggle Editing

  6. Scroll down to the feature in question. The id for this feature is 6703. You may wish to click on the id column to sort numerically if it is not already.

    ../_images/commit_attributetablefeature.png

    Feature selected

  7. Double-click the value of the status column. Change the value to ACTIVE and press Enter.

    ../_images/commit_featureedited.png

    Feature edited

  8. Click the pencil icon again to save changes.

  9. Close the attribute table dialog. We have made a very small change to our dataset and the map view changes accordingly.

    ../_images/commit_sellwoodgapclosed.png

    Sellwood Gap fixed

2.5.2.2. Committing the change

Now we will want to commit this change. While the change was made in the file, GeoGig is not yet aware of the change. The process for making a change with GeoGig is: Import, Add, Commit. We will perform all of those steps now.

  1. On a terminal in the repository, type the following command:

    geogig shp import --fid-attrib ID ../data/bikepdx.shp
    

    This is the same import command as above. It makes the GeoGig repository aware that content has changed.

    Importing from shapefile bikepdx.shp
    
    Importing bikepdx          (1/1)...
    0%
    2 distinct features inserted in 485.2 ms
    
    Building final tree...
    
    6747 features tree built in 65.96 ms
    100%
  2. Now add the changes. If you want to add everything, type:

    ge
    

    Note

    Any unchanged features will be ignored.

    Counting unstaged elements...2
    Staging changes...
    50%
    1 features and 1 trees staged for commit
    0 features and 0 trees not staged for commit
  3. Notice that the output says that only a single feature is staged for commit. This makes sense; even though we have imported the entire table, GeoGig processes the import against the existing repository, and will only highlight the features that have changed.

  4. Run geogig status to see this single feature:

    # On branch master
    # Changes to be committed:
    #   (use "geogig reset HEAD <path/to/fid>..." to unstage)
    #
    #      modified  bikepdx
    #      modified  bikepdx/6703
    # 2 total.
    

    Note

    If you’re wondering why there are two changes to be committed when we have only changed a single feature, it is referring to the feature and its parent tree (the layer itself).

  5. Finally, we are ready to commit this change:

    geogig commit -m "The Sellwood Gap has now been fixed"
    
    100%
    [603d4bf0069203a42ac513f635f49f725c2a4f2a] The Sellwood Gap has now been fixed
    Committed, counting objects...0 features added, 1 changed, 0 deleted.

Your change has been made.

2.5.3. Showing differences between commits

Our first commit entered every single feature into the repository. Our second commit changed a single attribute of a single feature.

You can see specific differences between two commits by using the diff command.

Note

The two commits need not be adjacent. If two commits referenced in the diff command have commits in between them, the sum total of differences (including all of those additional commits) will be displayed.

In order to do this, we first need to learn about the commit log and commit IDs.

2.5.3.1. Commit log

The commit log is a list of commits that are entered into the repository. It is a “history” of the repository.

  1. In a terminal, type the following command:

    geogig log
    

    This will show the list of commits.

    Commit:  603d4bf0069203a42ac513f635f49f725c2a4f2a
    Author:  Author <author@example.com>
    Date:    (9 minutes ago) 2014-08-01 17:21:23 -0
    Subject: The Sellwood Gap has now been fixed
    
    Commit:  cfdbd50c415a0d71b9a876eb51f90d5752e8f23b
    Author:  Author <author@example.com>
    Date:    (19 minutes ago) 2014-08-01 17:10:30 -0
    Subject: Initial commit of complete bikepdx layer
  2. If the full list is too much information, you can reduce the amount of information to one line:

    geogig log --oneline
    
    b862ee8ced960965f7f17033a6e68f604e62fae6 The Sellwood Gap has now been fixed
    2b7629e284cbd5ed8cec023ab00763ebd700143f Initial commit of complete bikepdx layer

    Note

    There are lots of ways to filter this commit list, including by date and by author. Type geogig help log for a full list of options.

2.5.3.2. Commit IDs

The first line of each commit is the commit ID. Commit IDs are long alphanumeric strings that uniquely determine the commit. When referencing a commit, you can use this string. Thankfully though, you don’t need to reference the entire string; you only need enough of the beginning of the string to uniquely identify the commit.

In this case, since we only have three commits, we don’t need much of the string to be unique. Usually 7 characters is much more than you would ever need to uniquely identify the commit.

Note

If you’re interested: the chances of the first seven characters of two different commit IDs being identical is 1 in 16^7, about 270 million! If you like living on the edge, you could use 5 characters (about 1 in 1 million), and GeoGig will always warn you if there’s any ambiguity.

So if we wanted details about a specific commit, we would use the show command:

  1. Get details about the most recent commit. Make sure to replace the commit ID with the one specific to your instance.

    geogig show b862ee8c
    
    Commit:        b862ee8ced960965f7f17033a6e68f604e62fae6
    Author:        Author <author@example.com>
    Committer:     Author <author@example.com>
    Author date:   (2 minutes ago) Fri Oct 23 00:48:26 PDT 2015
    Committer date:(2 minutes ago) Fri Oct 23 00:48:26 PDT 2015
    Subject:       The Sellwood Gap has now been fixed

2.5.3.3. Running a diff

With this, we have enough information to be able to see the difference (“run a diff”) between two commits.

  1. Enter the following command:

    geogig diff 2b7629e28 b862ee8ced9
    
    f15dd3... f15dd3... 9bf8e5... b06301...   M  bikepdx/1
    SHAPE_LEN: 871.638132806348 -> 871.6381328063
    
    f15dd3... f15dd3... 7c943c... e153fa...   M  bikepdx/6703
    STATUS: RECOMM -> ACTIVE
    SHAPE_LEN: 4862.01831066843 -> 4862.0183106684

Here we see that the specific feature (bikepdx/6703) is listed as having been modified (M), and with the precise change detailed: (that the status attribute has changed from RECOMM to ACTIVE,

Note

The order of the commit IDs is significant, being of the form before after. Reversing the order in this case would show that the attribute was changed in the opposite way, from ACTIVE to RECOMM.

2.5.4. Making a geometry change

The city’s bicycle plan is still incomplete. In addition to lanes that are only planned and not built, there are also gaps in the plan itself. Luckily, in this workshop, you get to play master planner, and see if you can fix some of the other gaps left behind by the system as it stands today.

Specifically, your next task is to add a new bike lane. You can draw it anywhere you want. (The specifics of the position of the feature is not important for this workshop.)

2.5.4.1. Draw a new feature

  1. Select Layer ‣ Toggle Editing to start the editing process.

    ../_images/commit_toggleediting.png

    Toggle editing

  2. The display will change, with a red “X” displaying over each vertex of every feature.

    ../_images/commit_editx.png

    Map window in Edit mode

  3. Zoom into an area of the map where you would like to place the new feature.

    ../_images/commit_addbefore.png

    A zoomed in area of the map

  4. Now add a feature by selecting Edit ‣ Add Feature.

    ../_images/commit_addfeature.png

    Add feature menu option

  5. Click on the map to place the initial vertex of the feature. Continue clicking to create each feature vertex.

    ../_images/commit_addduring.png

    Drawing a new feature

  6. Right-click when done. An attribute table dialog will display. Fill out the form, specifically entering in the following values:

    • id: 6773
    • segmentnam: [approximate street name, if known]
    • status: RECOMM
    • facility: MTRAIL
    ../_images/commit_addattributes.png

    Setting attributes for the new feature

  7. Click OK when done.

  8. Your feature will be displayed and styled with a dashed line (because status is not ACTIVE):

    ../_images/commit_addafter.png

    New feature added

  9. Select Layer ‣ Toggle Editing to complete the editing process. Click Save when prompted.

2.5.4.2. Commit the new feature

With the new feature added, we can now add it to our repository via another commit.

Note

Remember: “Import, Add, Commit”

  1. On a terminal in the repository, type the following command:

    geogig shp import --fid-attrib ID ../data/bikepdx.shp
    

    As before, this import command lets the GeoGig repository be aware that content has changed.

    Importing from shapefile ../data/bikepdx.shp
    
    Importing bikepdx          (1/1)...
    0%
    2 distinct features inserted in 3.260 s
    
    Building final tree...
    
    6773 features tree built in 285.1 ms
    100%
    ../data/bikepdx.shp imported successfully.
  2. Now add the changes:

    geogig add bikepdx
    
    Counting unstaged elements...2
    Staging changes...
    100%
    1 features and 1 trees staged for commit
    0 features and 0 trees not staged for commit

    Note

    To see details about what is staged for commit, remember that you can run geogig status.

  3. Finally, we are ready to commit this change, substituting the specific details about your new route:

    geogig commit -m "New recommended trail at Columbia and Argyle"
    
    100%
    [0dda0de72d5ff4a15a6f8067bcfe1a6ef4f974d5] New recommended trail at Columbia and Argyle
    Committed, counting objects...1 features added, 0 changed, 0 deleted.

Your change has been made.



Continue Reading

Previous: 2.2. GeoGig setup

Next: 2.6. Rolling back a change

This Page

About Boundless

Boundless provides commercial open source software for internet mapping and geospatial application development. We are dedicated to the growth and support of open source software.

License

This work is licensed under a Creative Non Commercial-Commons Attribution-Share Alike 3.0 United States License. Feel free to use this material, but we ask that you please retain the Boundless branding, logos and style.

Creative Commons License