User manual ########### Using BAM is easy and fun! Provided that: - you know how to use the command line of your os - have some experience of how versioning systems work Actually, this is not true, and in this guide we will explain to use BAM client from scracth. .. hint:: Do not try to follow this page as a step-by-step tutorial, since its content might be not completely coherent. The purpose of this manual is simply to explain the bam workflow from the artist point of view. Project Initialization ====================== In order to start working, we need to initialize a *project folder*. This operation should be done only once. To create a project folder we need to open our terminal, and go to the location where we want to store the project folder. Then we can type:: bam init http://bam:5000/gooseberry This command creates a ``gooseberry`` folder, containing information about the project. If we enter the folder and use the ``ls`` comand command, we notice that it is empty, but if we use the ``bam ls`` command we see a directory listing. This listing is provided by the project server on the fly and it allows us to browse its content without having a local copy on our machine. The project folder can be moved anywhere, at any time. The exact ``bam init`` syntax is available in the reference section. Session creation ================ Once the project has been initialized and we are able to browse it remotely, we can proceed checking out a file from it. For example we can type:: bam co libs/envs/jungle/jungle_opening.blend This creates a ``jungle_opening`` folder inside of our ``gooseberry`` project folder, which will contain the ``jungle_opening.blend``, along with all its dependencies (library files, textures, etc.) organized as follows. :: jungle_opening.blend relative/maps/path/map.png _absolute/maps/path/map.png As we can see, folders starting with the ``_`` character map to an absolute path on the server, while the other folders are relative to the file that was used to create the session. Editing ======= At this point we can edit any file in the session, and the system will keep track of our changes. Currently we can: - add new files to the session - delete files - edit files We can not: - rename files In order to check what is the status of our edits, we can use ``bam st``, which will print a list of edited, added and deleted files. .. note:: Sessions are meant to create a contained and controlled working environment. We should never, ever refer to content that is outside of a session folder. Committing changes ================== Once we are happy with the changes we made to the session, we can sent id back to the server, which will take care of versioning and merging it back into the project. To commit a change, simply type:: bam ci -m 'Updated trees' If you are outside the session folder, you have to specify it:: bam ci jungle_opening -m 'Updated trees' After committing, we can keep working in the same session, and do further commits. Updatding and existing session ============================== It is possible to update and existing session by running:: bam update Make sure you have committed your files before updating.