Merge pull request #2496 from Airblader/feature-917

[i3/i3] / docs / userguide

diff --git a/docs/userguide b/docs/userguide
index 068ecd87edab0e0444057432ee090cafcdd23885..4eb8c7f59c36b39370de49f6aa8b963bde030d81 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -1988,6 +1988,39 @@ bindsym $mod+c move absolute position center
 bindsym $mod+m move position mouse
 -------------------------------------------------------
 
+=== Swapping containers
+
+Two containers can be swapped (i.e., move to each other's position) by using
+the +swap+ command. They will assume the position and geometry of the container
+they are swapped with.
+
+The first container to participate in the swapping can be selected through the
+normal command criteria process with the focused window being the usual
+fallback if no criteria are specified. The second container can be selected
+using one of the following methods:
+
++id+:: The X11 window ID of a client window.
++con_id+:: The i3 container ID of a container.
++mark+:: A container with the specified mark, see <<vim_like_marks>>.
+
+Note that swapping does not work with all containers. Most notably, swapping
+floating containers or containers that have a parent-child relationship to one
+another does not work.
+
+*Syntax*:
+----------------------------------------
+swap container with id|con_id|mark <arg>
+----------------------------------------
+
+*Examples*:
+-----------------------------------------------------------------
+# Swaps the focused container with the container marked »swapee«.
+swap container with mark swapee
+
+# Swaps container marked »A« and »B«
+[con_mark="^A$"] swap container with mark B
+-----------------------------------------------------------------
+
 === Sticky floating windows
 
 If you want a window to stick to the glass, i.e., have it stay on screen even